Events

Playing an event

Quests inside an event, the scoring table for score events, and the community progress bar.

What sits in the middle of the event page. It depends on the event's type.

Event typeThe middle of the page
BASICThe event's quests
COLLABORATIVEThe event's quests, and one shared progress bar
SCOREA scoring table and a refresh button

Quests inside an event

state.quests is the event's quests, split in two.

ListHolds
state.quests.ongoingQuests the fan can still work on
state.quests.completedQuests that are finished, failed or abandoned

Render each one with the quest components you already have, and hand the event to the quest provider:

import { Quest, useQuestEvent } from '@xborglabs/fanbase-react'

function EventQuests() {
  const { state } = useQuestEvent()

  return state.quests.ongoing.map((quest) => (
    <Quest.Provider
      key={quest.questId}
      questId={quest.questId}
      quest={quest}
      fetchRewards
      event={state.event}
    >
      <QuestCard />
    </Quest.Provider>
  ))
}

event={state.event} is the part that matters. With it, the quest knows it belongs to an event and refuses in the right way when the event does not allow it.

Quest reasonMeansShow
EVENT_GUESTThe fan has not joined the eventA prompt to join first
EVENT_JOIN_NOT_ALLOWEDThe fan has not joined, and joining is closedThat it is too late to take part
EVENT_PARTICIPATION_NOT_POSSIBLEThe fan has joined, but the event has not started yetA disabled quest, and when it opens
EVENT_FINISHEDThe event ended or was cancelledA read-only finished state

These arrive the same way as every other quest reason, on the quest's own state. Quest detail has the pattern.

There is nothing to refresh by hand. A fan submitting an event quest refreshes the event, its leaderboard, their rank and the community progress.

Empty lists

List is emptyStrings
OngoingEvents.noQuestsTitle and Events.noQuests: the fan has done everything, and more may arrive
CompletedEvents.completeSomeQuests

Score events

A SCORE event has no quests to submit. Its quests are scoring rules: do this in the game, earn that many points each time.

state.scoringRows is the table.

function Scoring() {
  const { state } = useQuestEvent()

  return (
    <table>
      <thead>
        <tr>
          <th>{resolveMessage('Events.task')}</th>
          <th>{resolveMessage('Events.points')}</th>
          <th>{resolveMessage('Events.achieved')}</th>
          <th>{resolveMessage('Events.my points')}</th>
        </tr>
      </thead>
      <tbody>
        {state.scoringRows.map((row) => (
          <tr key={row.questId}>
            <td>{row.title}</td>
            <td>+{row.amount} {row.resourceName}</td>
            <td>{row.achieved > 0 ? `x${row.achieved}` : '·'}</td>
            <td>{row.myPoints > 0 ? row.myPoints : '·'}</td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}
FieldMeans
amountPoints for doing the task once
achievedHow many times the fan has done it
myPointsPoints the fan has from this row

The key for the last column is Events.my points, with a space in it. That is the real key.

Refreshing a score

Scores come from the fan's linked account, and the platform reads them when asked. A fan who has joined a SCORE event gets the SYNC button, labelled "Refresh".

<QuestEvent.Sync asChild>
  <button type="button" />
</QuestEvent.Sync>

Confirm it with Quests.questsSynced, which takes your noun as {quest}: "Quest log synced".

One thing to know about the result: the refresh request succeeding does not mean the score was read. The platform only starts a refresh for an event that is live, and only when one is not already running. To know what happened, read state.event.participation.syncStatus after the refresh.

syncStatusMeans
NONENothing running. A refresh can start.
SYNCINGA refresh is in progress
SYNCEDThe latest scores are in

Refreshing on its own

Refreshing when the fan opens the page saves them a press. If you do it, limit it yourself, because nothing else will. The SDK has the rule ready: at most once every five minutes, and only when nothing is running.

import { getQuestEventSyncStorageKey, shouldSyncQuestEvent, useQuestEvent } from '@xborglabs/fanbase-react'

const { state, actions } = useQuestEvent()

useEffect(() => {
  if (state.cta?.kind !== 'SYNC') return

  const key = getQuestEventSyncStorageKey(state.eventId)
  const ok = shouldSyncQuestEvent({
    lastSyncedAt: localStorage.getItem(key),
    syncStatus: state.event?.participation?.syncStatus,
  })
  if (!ok) return

  void actions.sync().finally(() => localStorage.setItem(key, new Date().toISOString()))
}, [state.cta?.kind, state.eventId])

Where you keep the timestamp is up to you. localStorage is the plain choice.

Collaborative events

Everyone works towards one number. state.collaborative has it.

function CommunityProgress() {
  const { state } = useQuestEvent()
  const c = state.collaborative
  if (!c) return null

  return (
    <section>
      <h3>{resolveMessage('Events.collabProgressTitle')}</h3>
      <progress max={100} value={c.percent} />
      <p>{c.completed} / {c.target}</p>
      <p>{resolveMessage(c.labelKey, undefined, { quests: 'Quests', reward: rewardLabel })}</p>
    </section>
  )
}
FieldMeans
completedQuests the community has finished between them
targetThe number they are aiming for
percentProgress from 0 to 100
stateWhere it stands. See below.
labelKeyThe string for that state
stateWhenDefault copy
IN_PROGRESSTarget not reached, event still running"Achieve Quests with the community and receive your reward"
COMPLETEDTarget reached"Congrats! The community goal has been reached successfully."
FAILEDEvent ended short of the target"Objective failed. None reward distributed."

The default wording for a failed goal is blunt. This is a good string to replace with your own through the i18n adapter.

On a collaborative event the leaderboard ranks fans by how many quests they completed, not by points. Results shows the one helper that handles it.

Checklist

  • Event quests are rendered with event={state.event}
  • A fan who has not joined sees a prompt to join on each quest, not a submit button
  • Submitting an event quest updates the page without a manual refresh
  • A score event shows the scoring table and no quest list
  • After a refresh, the result is read from syncStatus
  • Any automatic refresh is limited with shouldSyncQuestEvent
  • The community progress bar reads percent, and its copy follows state

On this page