The quest model
Quests, templates, requirements, rewards, allocations.
What a quest is made of, and the vocabulary the rest of the docs uses.
A quest
Something you ask a fan to do, and what they get for doing it. Created in the admin panel, delivered to your app through the API.
Every quest has a title, a description, a template, a status, an optional date window, and zero or more rewards.
Templates
The template decides what the fan has to do and what your UI has to render. A poll template needs options and a choice. A photo submission needs an upload. A follow template needs a linked social account.
Dozens of template names are live, and they group into a handful of families that behave the same way in code. You do not write a branch per template name, you write one per family. Quest templates is the full map.
Two families matter most:
Typed templates take a payload. Text, answer, prediction, quiz, poll, email, wallet, image. You collect input and submit it.
Empty-body templates take no payload. Visit a link, bind an account, progress-tracked, automatic. The fan does something, you tell the SDK it happened.
Templates arrive with args, a bag of template-specific settings from the admin panel. A poll's options are in args, as is a visit quest's URL.
Treat args as readable by anyone using your app. It reaches the browser, so do not build a mechanic whose fairness depends on a value in there staying hidden. If you need a quest whose answer cannot be seen ahead of time, ask us which template to use rather than assuming a given one hides it.
Requirements and gates
Some quests can only be acted on under certain conditions. Signed in. Discord account linked. Link opened. Inside the date window.
The state machine evaluates all of it and hands you canSubmit, canClaim, a button label and a reason. You render the answer, you do not compute it. See How it fits together.
Rewards
What the fan gets. Points and resources, physical or digital prizes, personalisation items like avatar parts or borders, and loot boxes.
Each reward carries a slug identifying its type. The SDK resolves a slug into the right presentation. Loot boxes have their own flow because they involve a reveal. Rewards and claims.
Allocations
A reward that has been assigned to a fan but not necessarily handed over. The gap matters for loot boxes, where allocation happens on claim and the contents resolve a moment later. You poll allocations until the result is there.
Status
Quests carry a status enum. The values do not read the way they look. INACTIVE means the fan has not started, not that the quest is switched off.
Do not render the raw enum. The SDK ships display strings for all of them. Display strings is a short page and skipping it is the most common cosmetic bug in a first integration.
Lifecycle
- Publishes a quest in the admin panelCommunity team
- Serves it on GET /v1/questsFanBase platform
- Renders the list from one callYour app
- Opens detail, seeds the providerYour app
- Machine decides: actionable, gated or doneFanBase platform
- Renders canSubmit, buttonLabel and the reasonYour app
- Verifies the submissionFanBase platform
- Makes the reward claimableFanBase platform
- Claims, and runs the lootbox revealYour app
Your app owns four of those nine steps and none of the verification. Whether someone actually followed the account, whether the prediction was right, whether the purchase happened. You do not implement any of it.