Joining an event
One button with ten states, and what to show for each way a join can be refused.
An event page has one main button. What it says and does depends on who is looking and when, and the SDK works that out for you.
The button
state.cta is the button to show right now. Switch on kind.
import { QUEST_EVENT_CTA, QuestEvent, buildBindUrl, useQuestEvent } from '@xborglabs/fanbase-react'
function EventButton() {
const { state } = useQuestEvent()
const cta = state.cta
if (!cta) return null
switch (cta.kind) {
case QUEST_EVENT_CTA.LOGIN:
return <a href={loginUrl}>{state.ctaLabel}</a>
case QUEST_EVENT_CTA.GET_MEMBERSHIP:
return <a href="/membership">{state.ctaLabel} ({cta.membership?.requiredTierName})</a>
case QUEST_EVENT_CTA.BIND_SOCIAL:
return (
<a
href={buildBindUrl({
oauthProxyUrl,
provider: cta.social!.toLowerCase(),
redirectUrl: `${bindCallback}?accountType=${cta.social}`,
})}
>
{state.ctaLabel}
</a>
)
case QUEST_EVENT_CTA.JOIN:
case QUEST_EVENT_CTA.PRE_REGISTER:
return (
<QuestEvent.Join asChild>
<button type="button" />
</QuestEvent.Join>
)
case QUEST_EVENT_CTA.CLAIM_REWARDS:
return <a href="?tab=rewards">{state.ctaLabel}</a>
case QUEST_EVENT_CTA.SEE_RESULTS:
return <a href="?tab=leaderboard">{state.ctaLabel}</a>
case QUEST_EVENT_CTA.SYNC:
return (
<QuestEvent.Sync asChild>
<button type="button" />
</QuestEvent.Sync>
)
default:
return <button type="button" disabled>{state.ctaLabel}</button>
}
}state.ctaLabel is the label, already in English. An empty <button /> inside QuestEvent.Join or QuestEvent.Sync is filled with that label for you. Put your own text in the button and yours wins.
- LOGINNo
- GET_MEMBERSHIPNo
- BIND_SOCIALNo
- JOINMatches
- PRE_REGISTERNot reached
- CLAIM_REWARDSNot reached
- SEE_RESULTSNot reached
- ENDEDNot reached
- SYNCNot reached
- JOINEDNot reached
The ten states
The first row that matches wins, top to bottom.
QUEST_EVENT_CTA | Shown when | Default label | What it is |
|---|---|---|---|
LOGIN | The fan is signed out | "Join Now" | A link to your sign-in |
GET_MEMBERSHIP | The event needs a tier the fan is not on | "Get Membership" | A link to your membership page. cta.membership names the tier. |
BIND_SOCIAL | A SCORE event, and a join was refused for a missing account | "Link Account" | A link that starts linking for cta.social |
JOIN | Not joined, and the event has started | "Join Event" | QuestEvent.Join |
PRE_REGISTER | Not joined, and the event has not started | "Pre-registration" | QuestEvent.Join |
CLAIM_REWARDS | The event ended and a reward is waiting | "Claim Rewards" | A link to your rewards tab |
SEE_RESULTS | The event ended and the fan took part | "See Results" | A link to your leaderboard tab |
ENDED | The event ended and the fan did not take part | "Event ended" | A disabled button |
SYNC | Joined a SCORE event | "Refresh" | QuestEvent.Sync. See Playing. |
JOINED | Joined | "Joined" | A disabled button |
Two things in that order are worth knowing. A signed-out fan always gets LOGIN, never a live join button. And the membership row wins even after the event ends, so a free fan looking at a finished Premium event is still told what it needed.
Join that cannot be pressed
JOIN and PRE_REGISTER carry cta.disabled. It is true when registration has not opened, has closed, or the event is full. QuestEvent.Join disables itself in those cases. If you render your own button, read the flag.
Joining
QuestEvent.Join joins the fan. It takes no input. When it succeeds, everything about the event refreshes: the button becomes JOINED or SYNC, the participant count goes up, and the fan's rank starts loading.
Confirm it. Events.participate_event_success is the string: "Your registration for the Event has been confirmed."
If you need the action without the component, actions.join() from useQuestEvent() does the same thing and rejects with the same error.
When a join is refused
A refused join lands on state.joinError. Its reason says why.
const { state, actions } = useQuestEvent()
useEffect(() => {
const err = state.joinError
if (!err) return
if (err.reason === 'REQUIREMENT_NOT_MET' && err.requirement?.name === 'membership_tier') {
toast(resolveMessage('Events.participate_event_rejected_membership', undefined, { event: 'Event' }))
} else if (err.reason === 'REQUIREMENT_NOT_MET' && err.requirement?.name === 'quest_completed') {
toast(
resolveMessage('Events.completeQuestFirstDescription', undefined, {
title: err.requirement.data?.title ?? '',
event: 'Event',
}),
{ action: { label: resolveMessage('Events.completeQuestFirst'), href: `/quests?qid=${err.requirement.data?.id}` } },
)
} else if (err.reason === 'SOCIAL_NOT_LINKED') {
toast.error(resolveMessage('Events.participate_event_rejected_bind_social', undefined, { event: 'Event' }))
} else {
toast.error(resolveMessage('Events.participate_event_rejected', undefined, { event: 'Event' }))
}
actions.clearJoinError()
}, [state.joinError])reason | Why | What to show |
|---|---|---|
REQUIREMENT_NOT_MET | The event has a requirement the fan does not meet | For a tier: the membership string and a link to your membership page. For a quest: the quest's title and a link to it. Otherwise the general refusal. |
SOCIAL_NOT_LINKED | The event needs a linked account | Events.participate_event_rejected_bind_social, and a way to link it |
EVENT_FULL | The participant cap was reached | Events.participate_event_rejected |
REGISTRATION_NOT_OPEN | Joining has not opened yet | Events.participate_event_rejected |
REGISTRATION_CLOSED | Joining has closed | Events.participate_event_rejected |
EVENT_CLOSED | The event was completed or cancelled | Events.participate_event_rejected |
JOIN_FAILED | Anything else, like a dropped connection | Events.participate_event_rejected, and let them retry |
For the four timing refusals, the event refreshes itself, so the button catches up with reality without anything from you.
Joining twice is harmless. A fan who is already in, or who double-taps, is treated as joined and sees no error.
Which requirement failed
When an event has a requirement and the join is refused for it, the platform says a requirement failed but not which one. err.requirement is the event's first requirement, offered as a hint. It is right whenever an event has one requirement, which is nearly always. With two, treat it as a best guess and fall back to the general message if it does not fit.
Events that need a linked account
A refusal for a missing account sets state.requiredSocial to the account type, when the platform names one.
On a SCORE event the button then becomes BIND_SOCIAL on its own, and the code at the top of this page handles it.
On a BASIC or COLLABORATIVE event the button stays JOIN, and pressing it again fails the same way. Show your own link next to it:
{state.requiredSocial && state.cta?.kind !== QUEST_EVENT_CTA.BIND_SOCIAL ? (
<a
href={buildBindUrl({
oauthProxyUrl,
provider: state.requiredSocial.toLowerCase(),
redirectUrl: `${bindCallback}?accountType=${state.requiredSocial}`,
})}
>
{resolveMessage('Events.required_social')}
</a>
) : null}state.requiredSocial survives actions.clearJoinError(), so dismissing the toast does not lose the link. It clears when the fan tries to join again.
Linking accounts covers the round trip and its errors.
Membership
When an event asks for a tier, the provider works out the gate with the same rule as everywhere else: the fan's rank has to be at or above the one required. The result is on state.membershipGate, and the GET_MEMBERSHIP button names the tier in cta.membership.requiredTierName.
You fetch nothing for this. Membership has the rule.
Checklist
- Every one of the ten states renders something
- A signed-out fan sees a sign-in link and no join button
- A full or closed event shows a disabled join button
- A successful join is confirmed, and the button changes without a reload
- Each refusal reason has copy
- A tier-gated event names the tier
- An event that needs a linked account offers the link on every event type