Core concepts
A small vocabulary covers the whole integration surface.
Project
A project is your tenant. It holds branding, the active template or game for Play (play_mechanic; see Lobby), allowed_origins, game_mode, optional webhook_url, fraud config and API keys. You create and manage projects in the admin dashboard.
game_mode controls how strict rewards and anti-fraud are:
game_mode | Use case | Rewards |
|---|---|---|
free_play | Engagement only (streaks, quizzes) | none |
promo_rewards | Coupons, trial extensions | server-confirmed |
in_game_economy | Points/credits spend & grant | server-authoritative |
Session token
A short-lived token that authorizes a player session. For identified users, your backend requests it from POST /v1/server/session-token using a server API key with the session:issue scope, then passes it to the widget. The request includes the project id, external_user_id and optional TTL.
For anonymous free-play, mount the widget without a token. No-write preview requires an authenticated owner in admin.
Events
Legacy templates drive progression by emitting events to POST /v1/events with the session token. Common types:
| Event | Meaning |
|---|---|
preview.impression | Widget shown (no progression) |
play.session_start | A play session began |
streak.ui_ack | Streak day acknowledged |
score.action | Incremental score in a score game |
level.complete | Level finished (score reconciled server-side) |
quiz.answer, scratch.reveal, wheel.spin, ... | Per-template actions |
play.session_end | Session finished |
Reward-bearing confirmations come from your backend via POST /v1/server/events authenticated with an API key, never from the browser.
Progression
Modern GameRun and level results are authoritative in Postgres. Legacy PlayerProgress uses Dragonfly hot storage with a durable Postgres cold copy. Read common progress via GET /v1/progress/state. The widget renders progress; it does not own it.
Rewards
Game-run rewards use server-confirmed game_won, optionally filtered by mechanic and level; see Game runs.
Campaigns map a trigger (for example streak_complete, outcome_id, level_complete, or game_won for a game run) to a reward (promo_code, trial_extension, ...). When a trigger fires under the right game_mode, the backend checks eligibility, caps, cooldowns and fraud flags, records a claim (idempotent), and dispatches a signed webhook.
Anti-fraud
Every ingress passes through the FraudGate: origin checks, rate limits, score velocity, idempotency and replay protection, plus custom rules. Decisions are Allow, Flag or Block; blocks include 403 or 429 depending on the rule. See security.
Modern game runs accept commands and compute results on the server. Wheel R1 uses /v1/wheel/spins, not the legacy wheel.spin event. R1 awards tickets/resources; material wheel prizes and their fulfilment are outside R1.