Events

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.

Which button does this fan see?Try it
The fan
The event
And
The button
JOIN
QuestEvent.Join. The event has started and the fan is not in it.
Checked in this order
  1. LOGINNo
  2. GET_MEMBERSHIPNo
  3. BIND_SOCIALNo
  4. JOINMatches
  5. PRE_REGISTERNot reached
  6. CLAIM_REWARDSNot reached
  7. SEE_RESULTSNot reached
  8. ENDEDNot reached
  9. SYNCNot reached
  10. JOINEDNot reached
The first state that matches wins, top to bottom. Example event.

The ten states

The first row that matches wins, top to bottom.

QUEST_EVENT_CTAShown whenDefault labelWhat it is
LOGINThe fan is signed out"Join Now"A link to your sign-in
GET_MEMBERSHIPThe event needs a tier the fan is not on"Get Membership"A link to your membership page. cta.membership names the tier.
BIND_SOCIALA SCORE event, and a join was refused for a missing account"Link Account"A link that starts linking for cta.social
JOINNot joined, and the event has started"Join Event"QuestEvent.Join
PRE_REGISTERNot joined, and the event has not started"Pre-registration"QuestEvent.Join
CLAIM_REWARDSThe event ended and a reward is waiting"Claim Rewards"A link to your rewards tab
SEE_RESULTSThe event ended and the fan took part"See Results"A link to your leaderboard tab
ENDEDThe event ended and the fan did not take part"Event ended"A disabled button
SYNCJoined a SCORE event"Refresh"QuestEvent.Sync. See Playing.
JOINEDJoined"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])
reasonWhyWhat to show
REQUIREMENT_NOT_METThe event has a requirement the fan does not meetFor 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_LINKEDThe event needs a linked accountEvents.participate_event_rejected_bind_social, and a way to link it
EVENT_FULLThe participant cap was reachedEvents.participate_event_rejected
REGISTRATION_NOT_OPENJoining has not opened yetEvents.participate_event_rejected
REGISTRATION_CLOSEDJoining has closedEvents.participate_event_rejected
EVENT_CLOSEDThe event was completed or cancelledEvents.participate_event_rejected
JOIN_FAILEDAnything else, like a dropped connectionEvents.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

On this page