Canonical event catalog
These are the event types PlaylogiQ actively consumes for financial derivation, lifecycle, analytics, and gamification. Your PAM’s raw types are translated to these via the mapping engine — you are not required to emit these names verbatim.
Financial & account lifecycle
| Canonical type | Meaning |
|---|---|
registration | Player account created. |
login / logout | Session start / end (auth level). |
deposit | Successful deposit. Key payload field: amount. |
deposit_failed | A deposit attempt that failed. |
withdrawal_request | A withdrawal was requested (not yet settled). |
withdrawal | A withdrawal that settled (money left the wallet). |
verification | A generic verification step. |
kyc_verified | KYC identity approved. |
status_changed | Account status changed at the PAM (the new status rides in the payload). |
limit_set | Player set a responsible-gaming limit. |
self_exclusion | Player self-excluded. |
cooling_off | Player entered a cooling-off period. |
Gameplay
| Canonical type | Meaning |
|---|---|
bet | Real-money bet (casino). Payload: amount. |
win | Real-money win. Payload: amount. |
bet_bonus / win_bonus | Bet / win with bonus funds. |
bet_sport / win_sport | Sportsbook bet / win. |
game_session_start | A game session started. |
game_session_end | A game session ended. |
Bonuses
| Canonical type | Meaning |
|---|---|
bonus_granted | Operator/PAM granted a bonus to the player. |
bonus_claimed | Player claimed a bonus. |
bonus_completed | A bonus completed its wagering. |
bonus_expired | A bonus expired. |
Custom events
Any type prefixed custom. is stored verbatim in your own namespace (e.g.
custom.newsletter_opened). Custom events are never treated as “unknown”; use
them for brand-specific signals you want in segments/journeys without polluting
the canonical set.
Common payload fields
Canonical consumers read a small set of well-known fields (produce them with the payload field map):
| Field | Used by |
|---|---|
amount | Deposits, withdrawals, bets, wins — revenue derivation. |
currency | Currency of the amount. |
method | Payment method (deposits) — powers “deposits by payment method”. |
game / category | Gameplay attribution. |
Recommended payload per event
These fields are what the platform uses. The PAM sends its own field names; the operator maps them to these canonical names. Nothing is strictly required (an event with no payload is still stored), but mapping the recommended fields is what makes revenue, lifecycle, and analytics work.
| Canonical event | Recommended canonical fields | Why |
|---|---|---|
registration | player identity via the player field map: email, first_name, last_name, country, registration_date | Populates the CRM record on first contact. |
deposit | amount, currency, method | Deposit totals (total_deposits, deposit_count, last_deposit_at) + deposits-by-method. |
withdrawal | amount, currency | Settled-withdrawal totals (total_withdrawals, withdrawal_count). |
bet / bet_sport / bet_bonus | amount, currency, game/category | Wagering & GGR, game attribution, last_bet_at. |
win / win_sport / win_bonus | amount, currency | Wagering & GGR. |
bonus_granted / bonus_claimed | amount, currency | Bonus-cost analytics / ROI (NGR). |
status_changed | status (map PAM codes via enum:{…}) | Mirrors PAM account status onto the player. |
kyc_verified | — | Marks KYC complete for compliance/lifecycle. |
game_session_start / game_session_end | session_id (top-level field), game/category | Session analytics. |
Send amounts in a consistent unit and tell the operator whether it’s major
units or minor units (cents) — the mapping applies cents_to_units when needed.
See Recipes & scenarios for worked examples.
How financials are derived
A background worker folds the event stream into the player’s financial profile incrementally — each event is processed exactly once and its delta is added:
| Profile field | Derived from |
|---|---|
total_deposits, deposit_count, last_deposit_at | deposit events |
total_withdrawals, withdrawal_count | withdrawal (settled) events |
total_wagered, total_ggr | bet / bet_sport (stakes) − win / win_sport (payouts) |
total_ngr, lifetime_value | GGR − bonus cost (bonus_claimed / win_bonus) |
favorite_category, last_bet_at | bet events |
So a deposit event moves the deposit totals (not GGR), a bet/win pair
moves wagering/GGR, and so on — exactly what you’d expect. Derivation is
asynchronous (a few seconds after ingest), so the profile updates shortly after
the event lands.
Events vs snapshot — avoid double-counting. These totals are computed by incrementing from events.
POST /playerscan also SET absolute baselines (handy to import a player’s history in one shot). Use events for ongoing activity, and the snapshot only as a one-time baseline — don’t send both an event and a snapshot for the same money, or the totals will double-count.
Built-in aliases
Even without a mapping, these legacy/SDK forms normalize automatically:
player.<x>→<x>when<x>is canonical (e.g.player.login→login).player.withdrawal→withdrawal_request,player.withdrawal_settled→withdrawal,player.bonus_grant→bonus_granted,player.kyc→kyc_verified,player.status_change→status_changed, …
An explicit event type map always takes precedence over these built-in aliases.