Building a prediction
The options, the lock, the split, one final pick, and the claim after it resolves.
One card. Today it sits on top of the quest system, so it uses the quest provider and the quest machine. When predictions move to their own surface, this page will change with them. Keep the card self-contained and the move stays small.
Finding predictions
They come back in the quest list. Pull them out by template name, and give them their own place in your product:
import { useQuestsList } from '@xborglabs/fanbase-react'
const PREDICTION = 'basic.prediction'
const { data: quests = [] } = useQuestsList()
const predictions = quests.filter((q) => q.template?.name === PREDICTION)
const everythingElse = quests.filter((q) => q.template?.name !== PREDICTION)Match on the exact template name. There is no SDK function that returns "prediction" for you.
Opening one
Each one opens in Quest.Provider, with fetchRewards on so a fan who calls it right can claim:
import { Quest } from '@xborglabs/fanbase-react'
<Quest.Provider questId={prediction.questId} quest={prediction} fetchRewards>
<PredictionCard />
</Quest.Provider>The card
import { resolveMessage, useQuest, useQuestResults } from '@xborglabs/fanbase-react'
function PredictionCard() {
const { state, actions } = useQuest()
const quest = state.quest
const { options = [], lockAt } = quest.template.args
const picked = quest.metrics?.text
const reason = state.machine.reason
const locked = reason === 'PREDICTION_LOCKED'
const closed = locked || reason === 'PREDICTION_SUBMITTED'
const { data } = useQuestResults(quest.questId)
const counts = data?.results ?? {}
const total = Object.values(counts).reduce((sum, n) => sum + n, 0)
return (
<section className="your-prediction">
<p>{locked ? 'Entries closed' : `Closes ${formatDate(lockAt)}`}</p>
{total > 0 && <p>{total} entries</p>}
{options.map((option) => {
const count = counts[option.label] ?? 0
const share = total ? Math.round((count / total) * 100) : null
return (
<button
key={option.label}
disabled={closed || !state.canSubmit}
aria-pressed={picked === option.label}
onClick={() => actions.submit({ text: option.label })}
>
{option.imageUrl && <img src={option.imageUrl} alt="" />}
<span>{option.label}</span>
{option.description && <small>{option.description}</small>}
{share !== null && <span>{share}%</span>}
</button>
)
})}
{closed && <p>{resolveMessage(`Quests.disabled.${reason}`)}</p>}
</section>
)
}formatDate is yours.
Sending the pick
Send the option's label, as { text: option.label }. Not its index, and not an id. The label is what your team resolves against, so it is what has to arrive.
Use actions.submit(payload), not Quest.Submit. A prediction is a typed template, and Quest.Submit sends no body, so the pick would be lost.
One click, one submit. There is no "change my answer". Make that clear before they tap: a confirm step, or a line saying the pick is final, is worth more here than on any other quest.
Reading back the pick
A fan who already entered has their pick in quest.metrics.text. Mark that option as theirs, and disable the rest. Do not show the options as if they could still choose.
The lock
Read it from the machine, not the clock:
state.machine.reason | Means | Show |
|---|---|---|
PREDICTION_LOCKED | The lock time has passed | Entries closed, and when they closed |
PREDICTION_SUBMITTED | This fan has already picked | Their pick, highlighted |
Both have display strings, Quests.disabled.PREDICTION_LOCKED and Quests.disabled.PREDICTION_SUBMITTED. Display strings.
Use lockAt only to display the deadline. Comparing it to the fan's own clock to decide whether to enable the buttons gets it wrong for anyone whose device clock is off. The machine already knows.
The split
useQuestResults(questId) returns the count per option, keyed by label:
{ results: { Northwind: 1822, Tidebreak: 1025 } }The total is the sum. Turn counts into percentages yourself, and show them before the fan enters as well as after. That is how a prediction is meant to read.
The hook is typed unknown, because the same endpoint serves polls too. Read results defensively, as above, and render the options without percentages if it is missing or empty. A brand new prediction has no entries yet.
After it resolves
Once your team marks the right answer, a fan who called it has a reward waiting. state.canClaim flips, and your normal claim button takes it from there:
{state.canClaim && (
<Quest.Claim asChild>
<button className="your-button">{state.buttonLabel}</button>
</Quest.Claim>
)}That only works if the provider has fetchRewards on. Without it, the claim button never appears and a fan who got it right is never paid.
If the reward is a raffle entry or a physical prize, the claim may need details first. Claims that need details.
A fan who picked wrong has nothing to claim. Say so plainly. They lost nothing, and the next prediction is the reason to come back.
Gating
A prediction takes the same audience rules as any quest. A members-only prediction shows its card to everyone, but the machine keeps it closed for anyone who does not qualify, with a reason to show. Render that reason rather than hiding the card: "For Premium members" is a better nudge than nothing.
Checklist
- A prediction renders through its own branch, from the template family
- The pick is sent as the option's label, through
actions.submit - The fan knows the pick is final before they tap
- A fan who already entered sees their pick, and the options are disabled
- The lock comes from the machine, and the card says when entries closed
- The split shows before and after entering, and survives having no entries
fetchRewardsis on, so a winning fan can claim- A losing fan sees a clear, kind result, not an error