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 type | The middle of the page |
|---|---|
BASIC | The event's quests |
COLLABORATIVE | The event's quests, and one shared progress bar |
SCORE | A scoring table and a refresh button |
Quests inside an event
state.quests is the event's quests, split in two.
| List | Holds |
|---|---|
state.quests.ongoing | Quests the fan can still work on |
state.quests.completed | Quests 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 reason | Means | Show |
|---|---|---|
EVENT_GUEST | The fan has not joined the event | A prompt to join first |
EVENT_JOIN_NOT_ALLOWED | The fan has not joined, and joining is closed | That it is too late to take part |
EVENT_PARTICIPATION_NOT_POSSIBLE | The fan has joined, but the event has not started yet | A disabled quest, and when it opens |
EVENT_FINISHED | The event ended or was cancelled | A 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 empty | Strings |
|---|---|
| Ongoing | Events.noQuestsTitle and Events.noQuests: the fan has done everything, and more may arrive |
| Completed | Events.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>
)
}| Field | Means |
|---|---|
amount | Points for doing the task once |
achieved | How many times the fan has done it |
myPoints | Points 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.
syncStatus | Means |
|---|---|
NONE | Nothing running. A refresh can start. |
SYNCING | A refresh is in progress |
SYNCED | The 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>
)
}| Field | Means |
|---|---|
completed | Quests the community has finished between them |
target | The number they are aiming for |
percent | Progress from 0 to 100 |
state | Where it stands. See below. |
labelKey | The string for that state |
state | When | Default copy |
|---|---|---|
IN_PROGRESS | Target not reached, event still running | "Achieve Quests with the community and receive your reward" |
COMPLETED | Target reached | "Congrats! The community goal has been reached successfully." |
FAILED | Event 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 followsstate