The event model
Three kinds of event, the clock they run on, and what joining changes.
What an event is made of, and the vocabulary the other four pages use.
An event
A competition with a start and an end. Fans join, compete for a fixed period, and are paid by where they finish or by what the community achieved together.
A quest is something one fan does. An event is something a crowd does at the same time, which is why it comes with a clock, a participant count and its own leaderboard.
Events are created in the Hub: the type, the window, the quests inside and the prizes. Events in the Hub docs covers that side. This section is about rendering what your team built.
Three types
QUEST_EVENT_TYPE | What fans do | How it is decided |
|---|---|---|
BASIC | Complete the event's quests | Points from those quests rank the leaderboard |
SCORE | Play a linked game or platform | Points are read from the linked account and ranked |
COLLABORATIVE | Complete quests towards one shared target | The whole community wins or loses together |
The type decides what the middle of your event page shows. A BASIC or COLLABORATIVE event has a quest list. A SCORE event has a scoring table instead, because its quests are scoring rules rather than things to submit.
The clock
Every event carries up to four dates.
| Field | Means |
|---|---|
registrationStartDate | When fans can start joining. Before startDate, joining is pre-registration. |
startDate | When the event goes live |
registrationEndDate | The last moment to join. When it is absent, fans can join until the end. |
endDate | When the event stops |
You never compare these to the current time yourself. The SDK derives a time badge, a join deadline and three timeline tiles from them, and tells you which state each is in. The event page shows how.
Statuses
QUEST_EVENT_STATUS | Means | Where it lists |
|---|---|---|
DRAFT | Not published | Nowhere. The list never returns drafts. |
PUBLISHED | Open to fans | Upcoming, live or finished, by its dates |
RESOLVING | Ended, results being worked out | Finished |
COMPLETED | Ended and resolved. Rewards can be claimed. | Finished |
CANCELLED | Called off | Finished |
Rewards exist only once an event is COMPLETED. An event that has passed its end date but is still PUBLISHED or RESOLVING has ended for fans, and has nothing to claim yet.
Joining
A fan who has joined is REGISTERED. That one status unlocks everything personal about the event: their quests count, their rank loads, and the event shows on their profile.
participation.status | Treated as |
|---|---|
REGISTERED | Joined |
UNREGISTERED, DROPPED, CANCELLED | Not joined |
There is no leave button in the SDK. Joining is one way.
An event can ask for something before a fan joins:
| Requirement | What it asks for |
|---|---|
membership_tier | A membership tier. A Premium fan passes a Premium gate; a free fan does not. Membership. |
quest_completed | One named quest finished first |
A SCORE event can also need a linked account, because that is where the score comes from. Joining covers each refusal and what to show for it.
What the SDK gives you
One provider for an event page, QuestEvent.Provider, and hooks for the list. The provider reads the event, the fan's participation, the leaderboard, their rank and their rewards, and hands you one state object that already says which button to show.
The compound is called QuestEvent, not Event. Event is the browser's own global, and shadowing it breaks unrelated code.
There is no separate request for an event's quests. They arrive inside the event.
The four pages
| Page | Covers |
|---|---|
| The event page | Listing events, mounting one, the header, tabs and timeline |
| Joining | The one button, its ten states, and every refusal |
| Playing | Quests inside an event, the scoring table, community progress |
| Results and rewards | The leaderboard, the fan's rank, prize distribution and claims |