Results and rewards
The event leaderboard, the fan's own rank, who wins what, and claiming it once the event completes.
The competitive half of an event: the standings while it runs, and the payout when it ends.
The leaderboard
state.leaderboard is the event's own board. Its rows have the same shape as the community leaderboard, so the table you built there works here.
import { QuestEvent, getQuestEventLeaderboardScore, resolveMessage, useQuestEvent } from '@xborglabs/fanbase-react'
function EventBoard() {
const { state } = useQuestEvent()
const board = state.leaderboard
if (board.listReason === 'AUTH_REQUIRED') return <SignInPrompt />
if (board.listReason === 'EMPTY') return <p>{resolveMessage('Errors.globalErrors.leaderboard_list_empty')}</p>
return (
<>
<table>
<thead>
<tr>
<th>{resolveMessage('Leaderboard.rank')}</th>
<th>{resolveMessage('Leaderboard.username')}</th>
<th>{board.resourceType?.name ?? resolveMessage('Leaderboard.score')}</th>
</tr>
</thead>
<tbody>
{board.users.map((row) => (
<tr key={row.user.userId}>
<td>{row.rank}</td>
<td>{row.user.displayName}</td>
<td>{getQuestEventLeaderboardScore(row, state.event)}</td>
</tr>
))}
</tbody>
</table>
<QuestEvent.LeaderboardPreviousPage asChild>
<button type="button">{resolveMessage('Leaderboard.previousPage')}</button>
</QuestEvent.LeaderboardPreviousPage>
<QuestEvent.LeaderboardNextPage asChild>
<button type="button">{resolveMessage('Leaderboard.nextPage')}</button>
</QuestEvent.LeaderboardNextPage>
</>
)
}Three things differ from the community board.
It needs a session. The community leaderboard is public. The event one is not. For a signed-out fan the provider does not ask for it at all, and listReason is AUTH_REQUIRED. Show a sign-in prompt in its place.
The score column depends on the event. BASIC and SCORE events rank by points. A COLLABORATIVE event ranks by quests completed. getQuestEventLeaderboardScore(row, state.event) returns the right number for either, so use it for the cell and you never branch on type.
The column heading is the event's own points. board.resourceType?.name is what your team called them. Fall back to Leaderboard.score.
Paging
The two pager components disable themselves on the first and last page. Ten rows a page by default. state.leaderboard.pageMeta has the page count if you want to print it.
To keep the page in your URL, control it:
<QuestEvent.Provider
eventId={id}
leaderboardPage={page}
onLeaderboardPageChange={setPage}
leaderboardLimit={25}
>Give the pager buttons your own text. Their built-in labels are plain English and do not go through your i18n adapter.
The fan's own rank
state.viewerRank is where the signed-in fan stands: rank, points, percentile and questsCompleted.
{state.viewerRankReason === null && state.viewerRank ? (
<p>
{resolveMessage('Events.yourRank')}: #{state.viewerRank.rank} · {state.viewerRank.points}
</p>
) : null}Only render it when state.viewerRankReason is null.
viewerRankReason | Means | Show |
|---|---|---|
null | The fan has joined and has a rank | Their row |
AUTH_REQUIRED | Signed out | Nothing |
NOT_REGISTERED | Signed in, has not joined | Nothing |
That check is not optional. A fan who has not joined has no rank, and showing one would tell them they are placed in an event they are not in.
Who wins what
state.rewards is the prize list, best placing first. Each row says which positions it pays and what they get.
import {
resolveMessage,
resolveQuestEventRewardDisplay,
resolveQuestEventRewardRankLabel,
useQuestEvent,
useResourceTypes,
} from '@xborglabs/fanbase-react'
function PrizeList() {
const { state } = useQuestEvent()
const { data: resourceTypes } = useResourceTypes()
return (
<ol>
{state.rewards.map((reward) => {
const rank = resolveQuestEventRewardRankLabel(reward)
const display = resolveQuestEventRewardDisplay({ reward, resourceTypes })
return (
<li key={reward.rewardId}>
<span>{resolveMessage(rank.key, undefined, rank.values)}</span>
<img src={display.imageSrc} alt="" />
<span>{display.label}</span>
</li>
)
})}
</ol>
)
}Position labels
A prize can be for an exact place, a range of places, or a share of the field.
| Prize is for | String key | Reads like |
|---|---|---|
| One place | Events.ordinalRank | "1st" |
| A range of places | Events.topAbsolute | The top four to ten |
| A percentage | Events.topRankPercent | "Top 5%" |
| A range of percentages | Events.top | "Top 5-10%" |
resolveQuestEventRewardRankLabel picks the right one and hands you the key and its values.
What the prize is
resolveQuestEventRewardDisplay returns { label, imageSrc, itemId? } for any kind of prize: points, a prize, a loot box, a profile item or a wearable. resourceTypes is the community's list of point types from useResourceTypes(), which is how a points prize gets its name and icon.
A wearable is the one that needs a second read. When itemId is set, fetch the item and pass it back in so the label can name it:
const display = resolveQuestEventRewardDisplay({ reward, resourceTypes })
const { data: item } = useInventoryItem({ communityKey: COMMUNITY_SLUG, itemId: display.itemId })
const full = resolveQuestEventRewardDisplay({ reward, resourceTypes, item })The prize pool chip
For a card or a header, state.rewardPairs is the same prizes grouped, so 500 points for first and 250 for second read as one line. Show the first and say how many more there are:
const [first, ...rest] = state.rewardPairs
const display = resolveQuestEventRewardDisplay({ reward: first.reward, sum: first.sum, resourceTypes })
<span>
{resolveMessage('Events.prizePool')}: {display.label}
{rest.length > 0 ? ` ${resolveMessage('Events.rewardAndMore', undefined, { count: rest.length })}` : ''}
</span>Claiming
Rewards appear when the event is COMPLETED and the fan is signed in. Until then state.allocations is empty and there is nothing to claim.
state.claim sums it up.
| Field | Means | Show |
|---|---|---|
claimable | Rewards waiting for this fan | One claim card each |
allClaimed | Everything has been claimed | A banner: Events.allRewardsClaimed |
hasRewardAllocated | At least one is waiting | Nothing extra. It is why the main button reads "Claim Rewards". |
One card per reward
Each reward claims in one of three ways. resolveQuestEventClaimFlow tells you which.
import {
QuestEvent,
getQuestEventPrizeRequirements,
getRequirementFields,
isSubmissionRequired,
resolveMessage,
resolveQuestEventClaimFlow,
toAllocationClaimPayload,
toPrizeRequirementValues,
useQuestEvent,
} from '@xborglabs/fanbase-react'
function ClaimCard({ allocation }) {
const { actions } = useQuestEvent()
const flow = resolveQuestEventClaimFlow(allocation)
if (flow === 'PRIZE_REQUIREMENTS') {
const requirements = getQuestEventPrizeRequirements(allocation).filter(isSubmissionRequired)
return (
<PrizeForm
fields={requirements.flatMap(getRequirementFields)}
onSubmit={(form) =>
actions.claim({
rewardAllocationId: allocation.rewardAllocationId,
payload: toAllocationClaimPayload(toPrizeRequirementValues(requirements, form)),
})
}
/>
)
}
return (
<QuestEvent.Claim
asChild
rewardAllocationId={allocation.rewardAllocationId}
onClaimed={(claimed) =>
flow === 'LOOTBOX_REVEAL'
? openReveal(claimed.rewardAllocationId)
: toast(resolveMessage('Events.claimRewardsSuccess'))
}
onError={() => toast(resolveMessage('Errors.globalErrors.quest_reward_claim_rejected'))}
>
<button type="button">{resolveMessage('Events.claimRewardsButton')}</button>
</QuestEvent.Claim>
)
}QUEST_EVENT_CLAIM_FLOW | When | Steps |
|---|---|---|
CLAIM | Points, items and anything that needs nothing from the fan | Claim, then confirm |
PRIZE_REQUIREMENTS | A prize that needs an email, an address or a wallet | Show the form, then claim with what they entered |
LOOTBOX_REVEAL | A loot box | Claim, then show the reveal |
A prize that needs details
The form is the same one prizes use everywhere. getRequirementFields gives you the fields, toPrizeRequirementValues turns your form's values into the right shape, and toAllocationClaimPayload builds what the claim sends. Prizes and inventory covers the fields and their validation.
A loot box
Claim first, then reveal. The claim answers with what was inside:
import { getQuestEventLootboxSelectedItem } from '@xborglabs/fanbase-react'
const won = getQuestEventLootboxSelectedItem({
rewardAllocationId,
claimed,
allocations: state.allocations,
})Key your reveal by rewardAllocationId, so a fan with two boxes opens the right one. The reveal itself, and the list of what could have been inside, is the same build as for quests: the loot box reveal.
When a claim fails
A failed claim lands on state.claimError and calls onError.
| Error | Means | Do |
|---|---|---|
QuestEventRewardAlreadyClaimedError | Claimed already, or a claim is in flight | Nothing. The rewards refresh and the card goes away. |
UserRequirementError | The prize needed a detail that was not sent | Show the form again |
QuestClaimRejectedError | The claim did not go through | Show Errors.globalErrors.quest_reward_claim_rejected and let them retry |
A claimed wearable shows up in the fan's avatar without anything from you. The claim refreshes it.
On the profile
useQuestEventsParticipatedCount() is how many events the fan has joined, for a stat on their profile.
Components
| Component | Use |
|---|---|
QuestEvent.Provider | Reads the event and everything personal about it |
QuestEvent.Join | Join or pre-register |
QuestEvent.Sync | Refresh a score |
QuestEvent.Claim | Claim one reward |
QuestEvent.LeaderboardNextPage, QuestEvent.LeaderboardPreviousPage | Page the board |
All five buttons take asChild and render your element. Full props in Components.
Upgrading from the old Event exports
Earlier packages exported this feature as Event, useEvent and a set of EVENT_* constants. Those names are gone. An app that still imports one fails to load at all, not only on its event pages, so change every import before you upgrade.
Most of it is a rename: Event to QuestEvent, useEvent to useQuestEvent, EVENT_TAG to QUEST_EVENT_LIST_BUCKET. Three things changed shape:
- The button is
state.cta.kindandstate.ctaLabel, where it wasreason,buttonLabeland a set ofcan*flags - Quests are
state.quests.ongoingandstate.quests.completed actions.claim(id)is nowactions.claim({ rewardAllocationId })
The full old-to-new table, name by name, ships in the package at node_modules/@xborglabs/fanbase-react/event.md, under "Migration from Event". Point your agent at it.
Checklist
- A signed-out fan sees a sign-in prompt where the board would be, and the board is never requested
- The score cell uses
getQuestEventLeaderboardScore - The fan's own row only renders when
viewerRankReasonisnull - Prizes list in order, with the four kinds of position label
- Nothing can be claimed until the event is completed
- A prize that needs details shows the form before it claims
- A loot box claim opens the reveal for that box
- Once everything is claimed, the cards are replaced by a banner