Events Lifecycle

Overview

Joining an event requires understanding its lifecycle, which consists of three main stages:

• Pre-register

• Ongoing

• Ended

Each stage has unique characteristics affecting how users can interact with the event.

Event Stages

Pre-register Stage

During this stage, the event is published but hasn't started yet.

Key States:

• isRegistrationOpen: Determines if users can join the event

• alreadyRegistered: Indicates if the user has already registered

Characteristics:

• Users can register if the registration period is open

Most of the time, if an admin wants to allow users to join the event while the event is ongoing, the registration periods ends when the event ends. If the registration date ends when the event starts for exemple, it means that users won't be able to join the event after it has started.

Ongoing Stage

The event is live and active during this stage.

Key States:

• isLive: Indicates that the event is active and ongoing

• isJoinAllowed: Determines if the user can participate

• eventStarted: Confirms that the event has begun

• maxParticipationReached: Indicates if the event has reached its participant limit

Characteristics:

• Users can participate if registered and meeting requirements

Ended Stage

The event has concluded in this stage.

Key States:

• eventEnded: Indicates that the event is over

• isParticipating: Confirms if the user was a participant

Characteristics:

• Users can no longer join

• Rewards and results may be available (depending on event type)

Event States: Implementation

JoinStates Type

Use the JoinStates type to programmatically determine an event's state:

typescriptCopytype JoinStates<T extends SingleEventType | undefined> =
  T extends SingleEventType
    ? {
        isLive: boolean;                  // Indicates if the event is ongoing
        isJoinAllowed: boolean;           // Whether the user can join the event
        alreadyRegistered: boolean;       // Whether the user has already registered
        eventStarted: boolean;            // Whether the event has started
        eventEnded: boolean;              // Whether the event has ended
        maxParticipationReached: boolean; // Whether the maximum participant count is reached
        isParticipating: boolean;         // Whether the user is participating
        isRegistrationOpen: boolean;      // Whether registration is currently open
      }
    : undefined;

Fetching Join States

Use the getJoinStates function to check event states:

typescriptCopyimport { getJoinStates } from '@xborglabs/ui-shared'

const joinStates = getJoinStates(event);

if (joinStates?.isRegistrationOpen) {
  console.log("Registration is open!");
}

if (joinStates?.isLive) {
  console.log("The event is live!");
}

if (joinStates?.eventEnded) {
  console.log("The event has ended.");
}

Joining an Event

🔍 Quick Note: The main function for joining events is useMutateParticipateEvent. See example code snippets below for usage details.

Step 1: Event Joining Function

Use the useMutateParticipateEvent hook to handle user registration:

typescriptCopyimport { useMutateParticipateEvent } from '@xborglabs/ui-shared/dist/client';

const mutateJoinEvent = useMutateParticipateEvent();

function joinEvent() {
  mutateJoinEvent.mutate(eventId, {
    onSuccess: () => {
      console.log(`Successfully joined the event: ${event.title}`);
    },
    onError: (err) => {
      console.error("Error joining event:", err);
    },
  });
}

Function Overview:

• Purpose: Joins a user to an event via backend API

• Input: Takes eventId to identify the event

• Success Handling: Can trigger UI updates, notifications, or state invalidations

• Error Handling: Catches errors like unmet requirements or social bindings

Step 2: Handling Event Requirements

Events may have specific requirements users must meet before joining. These requirements are:

• Defined in the event object

• Validated by the backend

• Enforced to ensure only eligible users can participate

➡️ For more details about requirement schema, client-side validation, and handling, refer to the dedicated Event Requirements documentation.

Step 3: Handling Ongoing Events

Check participation eligibility for ongoing events:

typescriptCopyif (joinStates?.isLive && joinStates?.isJoinAllowed) {
  console.log("You can participate in this event!");
}

Summary

The event joining process involves:

1. Checking the event's current stage

2. Verifying user eligibility

3. Handling any specific requirements

4. Managing state transitions

5. Providing appropriate user feedback

For detailed implementation examples and best practices, refer to the code snippets above and ensure proper error handling for all scenarios.