Event Management

Overview

The SDK supports two primary event types:

• Normal Events: Standard quest-based events focusing on task completion

• Score-Based Events: Competitive events with point-based leaderboards

Normal Events

Normal Events are standard events where users can complete one or more quests to earn rewards. These events do not track a cumulative score for participants but focus on task completion.

Type Definition

type NormalEvent = BasicEventType & {
  type: QUEST_EVENT_TYPE.BASIC; // 1
  quests: QuestDetailsType[];
};

Score-Based Events

Score-Based Events involve quests where participants earn points to compete on a leaderboard. These events are commonly used for competitive scenarios where scoring determines ranking or rewards.

Type Definition

type ScoreBasedEvent = BasicEventType & {
  type: QUEST_EVENT_TYPE.SCORE; // 2
  quests: ScoreQuest[];
};

The type field identifies the event as a SCORE quest event, while the quests array contains ScoreQuest objects that define tasks contributing to the participant's total score.

Event Data Structure

All event types inherit from the BasicEventType, which provides the foundation for handling event data in the UI. This includes essential information like dates, participation status, requirements, and rewards.

Type Definition

type BasicEventType = {
  containerId: string;                // ID of the container or community hosting the event
  createdAt: FlexDate;               // Timestamp for when the event was created
  createdBy: string;                 // Creator of the event
  description: string | ParsableContent[]; // Description of the event
  summary?: string | ParsableContent[]; // Shorter description for main event view
  endDate: FlexDate;                 // Date when the event ends
  eventId: string;                   // Unique identifier for the event
  maxParticipants: number;           // Maximum number of participants allowed
  registrationEndDate: FlexDate;     // End date for registrations
  registrationStartDate: FlexDate;   // Start date for registrations
  startDate: FlexDate;               // Date when the event begins
  title: string;                     // Event title
  totalParticipants: number;         // Total number of current participants
  updatedAt: FlexDate;               // Timestamp for the last update to the event
  updatedBy: string;                 // User who last updated the event
  rewards?: EventRewardType[];       // Optional array of rewards for the event
  status: QUEST_EVENT_STATUS;        // Current status of the event
  slug: string;                      // Slug for URL or identification
  participation?: {                  // Participant-specific details
    isParticipating: boolean;        // Whether the current user is participating
    status: string;                  // Participant's current status in the event
    syncStatus: ParticipantSyncStatusType; // Backend sync status for the participant
  };
  requirements?: Array<EventRequirementType>; // Optional array of requirements for joining the event
  images?: {                         // Optional image assets
    coverImageUrl: string;           // URL for the event's cover image
    displayImageUrl?: string;        // A secondary image
    iconImageUrl?: string;           // Icon for event
  };
};

Key Fields Explained

General Information

• containerId: Identifies the hosting community or group

• title: The name of the event

• description: Detailed information about the event, either as plain text or parsed content

Timelines

• startDate and endDate: Define the active period of the event

• registrationStartDate and registrationEndDate: Define when users can register for the event

Participants and Capacity

• maxParticipants: Maximum number of users allowed to join

• totalParticipants: Current number of registered users

Rewards

• rewards: Defines the rewards available for participating or completing quests in the event

Participation Details

• participation: Includes fields to track whether the current user is participating, their status, and the synchronization status with the backend

Requirements

• requirements: Specifies any conditions that users must meet to join the event (e.g., completed quests or prior achievements)

Visuals

• images: Contains optional media assets such as a cover image for the event

Metadata

• createdAt, createdBy, updatedAt, updatedBy: Provide audit information about the event's creation and last modification

Deep Dive: BasicEventType Options

Status

The status field of BasicEventType reflects the current state of the event. Common statuses include:

• DRAFT: The event has been created but isn't published yet (not visible in community UI)

• PUBLISHED: The event has been created and is visible in the UI

• RESOLVING: The event is currently active

• COMPLETED: The event has concluded

• CANCELLED: The event has been canceled

Rewards

The rewards field is an optional array of rewards associated with the event:

type EventRewardType = {
  eventRewardId: string;
  name: string;
  resolutionType: QuestEventRewardResolutionType;
  resolutionValueRange: ResolutionValueType;
  rewardId: string;
  reward: EventGiveResourcesReward | EventGiveAssetsReward;
  rewardHandlerArgs: EventGiveResourcesRewardHandler | EventGiveAssetsRewardHandler;
  eventId: string;
  createdAt: Date;
  updatedAt: Date;
};

Participation

The participation object tracks the user's involvement in the event. Example usage:

{
  isParticipating: true,               // User has joined the event
  status: "COMPLETED",                 // User's progress (e.g., "IN_PROGRESS", "COMPLETED")
  syncStatus: "SYNCED",                // Sync status of participation
}

Requirements

The requirements field defines prerequisites for event participation. Example:

requirements: [
  {
    name: 'quest_completed',
    requirementId: "quest-123",
    requirementArgs: {
      outcome: 1,
      questId: "quest-1234"
    },
    data: {
      id: "abc",
      title: "Some quest"
    }
  }
];