Quest templates
Template families, routing, and payload shapes.
The map from template name to what you render and what you submit. Dozens of template names are live. You do not write a branch per name, you write one per family.
What arrives on the wire
Three different vocabularies show up on a quest, and mixing them up is the most expensive mistake on this page.
template.name is a namespaced wire value, lowercase and dotted:
basic.auto-complete
basic.submit-walletThe family names below are not wire values, and no SDK function returns them.
text, visit, bind and the rest are a grouping you map names into yourself, with
the router under Routing. Comparing template.name === 'visit' matches
nothing, and because the comparison fails quietly, every quest falls through to your
default branch and the page looks like it works.
Two SDK helpers look like they should do this and do not. getApiType returns the
submit path, accept, complete or image, and getQuestType returns a number.
Neither is a family. Switching on either one sends every quest to your default branch.
Requirement codes are a third namespace, upper snake case, and they are what you see when the machine holds a quest closed rather than what you switch on:
| Code | Means |
|---|---|
VISIT_LINK_MISSION | An outbound link the fan has not opened. See Visit-link quests. |
EVENT_JOIN_NOT_ALLOWED | The fan cannot join the event this quest belongs to. |
SOCIAL_* | A social account that is not linked. Needs authProfile. |
WALLET_* | A wallet that is not linked. Needs authProfile. |
JOIN_* | A community membership gate. |
A quest also carries questType, a coarse grouping such as SOCIAL. It is not the
template and it is not granular enough to route on.
The full list of names ships inside the package, in the Catalog section of
node_modules/@xborglabs/fanbase-react/quest.md. The router below covers every
typed name in it. Anything it does not recognise is empty-body, which is the safe
default.
Families
Filter by how you submit. Typed families take a payload, empty-body families do not, and that distinction is the one your code actually branches on.
The same thing as a table
| Family | Submit | You render |
|---|---|---|
text | submit(payload) | A text field |
answer | submit(payload) | A free-form answer field |
prediction | submit(payload) | Outcome picker |
quiz | submit(payload) | Question with options |
poll | submit(payload) | Options, single choice |
email | submit(payload) | Email field with validation |
wallet | submit(payload) | Wallet address field |
image | submit(payload) | File upload with preview |
visit | Quest.Submit | Outbound link, then the CTA |
bind | Quest.Submit | Link-account button, then the CTA |
progress | Quest.Submit | Progress readout, CTA when complete |
auto | Quest.Submit | Status, no input |
unknown | Quest.Submit | Fall through to the default branch |
Typed families take a payload. Empty-body families do not. That distinction is the one your code branches on.
Routing
Map the template name to a family yourself. Only eight names take a payload, so the map is short, and everything you do not recognise falls through to an empty-body submit:
// Yours to own. Built from the template catalog in the package's quest.md.
const TYPED = {
'basic.text-submission': 'text',
'basic.answer-submission': 'answer',
'basic.prediction': 'prediction',
'basic.quiz': 'quiz',
'basic.poll': 'poll',
'basic.submit-email': 'email',
'basic.submit-wallet': 'wallet',
'manual.image-submission': 'image',
}
const VISIT = new Set([
'basic.visit-link', 'basic.visit-facebook', 'basic.visit-instagram',
'basic.view-instagram-post', 'basic.view-tiktok-post',
'youtube.visit-channel', 'youtube.watch-video',
])
const BIND = new Set(['twitch.follow', 'twitch.subscribe', 'youtube.subscribe', 'youtube.like', 'steam.wishlist-game'])
const BIND_PREFIXES = ['twitter.', 'discord.', 'spotify.']
export function familyOf(name = '') {
if (TYPED[name]) return TYPED[name]
if (VISIT.has(name)) return 'visit'
if (BIND.has(name) || BIND_PREFIXES.some((p) => name.startsWith(p))) return 'bind'
if (name === 'basic.auto-complete') return 'auto'
return 'other' // progress, gaming, wallet checks and anything new: empty body
}Typed names come first because they are the ones where a wrong guess loses the fan's input. A new empty-body template needs no change here at all. A new typed one does, and the package's changelog is where you would see it.
familyOf(name)actions.submit(payload){ text: option }getApiType(name) returnsswitch (getApiType(name)) with a case 'poll' never matches, so this quest drops to your default branch and is submitted with no payload. The fan's input is lost.quest.md.Always have a default
default:
return (
<Quest.Submit asChild>
<button disabled={!state.canSubmit}>{state.buttonLabel}</button>
</Quest.Submit>
)An unrecognised name should render something usable rather than a blank panel. The machine still knows whether the fan can act.
Template args
template.args carries the settings a community team configured for that quest. Options for a poll, a URL for a visit, an accepted file type for an upload.
Read defensively. Args are per-template, optional keys are common, and a key being present in the admin panel does not mean it arrives populated:
const options = template.args?.options ?? []
const url = template.args?.urlTypes vary across communities for some flags, so compare loosely rather than with a strict === true on a value that might arrive as a string.
Two things worth knowing before you rely on a key:
A documented key can still be null on live rows. Text-submission quests on beta
have been observed with args.text null across every row on a tenant. Supply your
own fallback label rather than rendering an empty prompt:
const prompt = template.args?.text ?? 'Your answer'Some templates carry matching flags alongside the value. An answer-family quest arrives with the comparison rules next to it:
{ "answer": "1WH3NC1", "matchExactly": true, "caseSensitive": true }You submit what the fan typed and let the platform compare. Do not do the comparison yourself, even though the pieces are sitting right there.
Payload shapes
Every typed template sends its value under text, whatever the family. Only the image upload is different.
| Family | Payload | Notes |
|---|---|---|
text | { text: string } | At least 3 characters |
answer | { text: string } | Not answer. The fan's earlier answer reads back from quest.metrics.answer. |
prediction | { text: option.label } | The option's label, not its index. Predictions. |
quiz | { text: option } | The option string itself. The platform marks it. |
poll | { text: option } | The option string itself |
email | { text: email } | |
wallet | { text: address } | A 0x address |
image | File[] | The files, passed straight to actions.submit |
| empty-body | none |
Do not invent a payload shape. If a template needs something not listed here, ask rather than guessing, because the platform validates on submit and a wrong shape fails silently from the fan's point of view.
Display names
Templates carry a displayName for admin-facing surfaces. Fan-facing copy comes from the quest's own title and description, so you rarely need it in your app.