Events

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.

viewerRankReasonMeansShow
nullThe fan has joined and has a rankTheir row
AUTH_REQUIREDSigned outNothing
NOT_REGISTEREDSigned in, has not joinedNothing

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 forString keyReads like
One placeEvents.ordinalRank"1st"
A range of placesEvents.topAbsoluteThe top four to ten
A percentageEvents.topRankPercent"Top 5%"
A range of percentagesEvents.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.

FieldMeansShow
claimableRewards waiting for this fanOne claim card each
allClaimedEverything has been claimedA banner: Events.allRewardsClaimed
hasRewardAllocatedAt least one is waitingNothing 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_FLOWWhenSteps
CLAIMPoints, items and anything that needs nothing from the fanClaim, then confirm
PRIZE_REQUIREMENTSA prize that needs an email, an address or a walletShow the form, then claim with what they entered
LOOTBOX_REVEALA loot boxClaim, 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.

ErrorMeansDo
QuestEventRewardAlreadyClaimedErrorClaimed already, or a claim is in flightNothing. The rewards refresh and the card goes away.
UserRequirementErrorThe prize needed a detail that was not sentShow the form again
QuestClaimRejectedErrorThe claim did not go throughShow 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

ComponentUse
QuestEvent.ProviderReads the event and everything personal about it
QuestEvent.JoinJoin or pre-register
QuestEvent.SyncRefresh a score
QuestEvent.ClaimClaim one reward
QuestEvent.LeaderboardNextPage, QuestEvent.LeaderboardPreviousPagePage 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.kind and state.ctaLabel, where it was reason, buttonLabel and a set of can* flags
  • Quests are state.quests.ongoing and state.quests.completed
  • actions.claim(id) is now actions.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 viewerRankReason is null
  • 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

On this page