KPIs

This is the reference for partner and staff KPIs: who sees what, how each KPI is defined, and how comparisons stay anonymous. The decision record is ADR 0033. Definitions are implemented as Cube measures in services/cube/model/ and must match this page.

Status key: ✅ data exists · 🟡 needs the domain event log · 🌍 needs the activity market · ⏳ future (no source table yet).

Visibility tiers

Tier	Audience	Population	Protection
Own	The party itself	Players linked to the party. Operator: active identity_links with audience_party_id = the party. Provider: Accounts reached through its integrations (same scope as studio analytics). Affiliate: attributed players (⏳).	Account floor ≥ 50 per cell; drill-down only by the party's own aliases
Network comparison	The party	Y = your players; R = all active PlayerPal Accounts minus Y; N = all active Accounts	Rest-of-network floor, dominance rule, per-player figures only
Benchmark	The party	Peers of the same party type	Peer floor, dominance rule, statistics only
Network	PlayerPal staff	Everyone	Staff permission reports.aggregate.read; every access is audited

Scope always comes from the authenticated principal. A party_id in the query string or an x-party-id header is ignored on partner routes.

Anonymity rules

They apply to the Network comparison and Benchmark tiers. They are enforced when segments are written and checked again when they are read. Thresholds are configuration; production must not go below these values.

Rule	Value	Config
Account floor	≥ 50 distinct Accounts	BENCHMARK_MIN_ACCOUNTS
Peer floor	≥ 5 other parties of the requester's type	BENCHMARK_MIN_PEERS
Dominance	suppress if one other party > 50 % of the measure	BENCHMARK_DOMINANCE_P
Dominance, top two	suppress if the top two together > 75 %	BENCHMARK_DOMINANCE_P2

• Published: p25, p50, p75, mean and the requester's percentile band (for example p50–p75).
• Never published:
  • min, max or an exact rank
  • per-peer values, names or IDs
  • absolute network totals (network size is shown only as a band, for example "100k+ players")
• Fixed segments only: closed ISO weeks or calendar months, and markets from the catalogue. Arbitrary date ranges are not allowed, so two segments can't be differenced to isolate a peer.
• Fallback: a market segment that fails a rule falls back to global. If global also fails, the response is { "suppressed": true, "reason": "<rule>" }.
• Cross-party KPIs (cmp.share_of_wallet, cmp.overlap_rate, cmp.multi_homing, cmp.market_mix): your players' activity with other parties must come from at least 5 parties and pass the dominance rule.

Market

market is the ISO 3166-1 alpha-2 licensed jurisdiction (uppercase, e.g. MT) that the partner reports on each activity event, in the JSON body or as a market column in uploads.

• A malformed value rejects the whole batch with market_invalid (400).
• If the integration declares markets and the event's market isn't one of them, the event is rejected with market_not_licensed.
• If the event has no market and the integration declares exactly one, that market is used. Otherwise the market stays empty, and the event only counts in global figures.
• The batch idempotency checksum covers market only when it is sent, so replays of batches sent before markets existed still match.

Nothing is stored on the player. A player's market for a day is derived from that day's activity, and a player active in two markets counts in both.

Own-tier KPIs

ID	KPI	Definition	Who	Source	Status
own.linked_players	Linked players	Accounts with an active link at the end of the period	op	identity_links	✅
own.new_links	New links	Links completed in the period	op	identity_links.linked_at	✅
own.unlink_rate	Unlink rate	Links unlinked or revoked in the period ÷ active links at the start of the period	op	identity_links	✅
own.link_funnel	Link funnel	link_intents created → completed; conversion %	op	link_intents	✅
own.active_accounts	Active accounts	Distinct Accounts with ≥ 1 round (DAU / WAU / MAU)	op, prv	analytics_account_*_day	✅
own.stickiness	Stickiness	Mean DAU ÷ MAU	op, prv	as above	✅
own.rounds	Rounds	Σ rounds	op, prv	as above	✅
own.bet_eur / own.win_eur	Turnover / wins	Σ bet_eur, Σ wins (EUR)	op, prv	as above	✅ (🌍 split)
own.ggr	GGR proxy	Σ (bet − win)	op, prv	as above	✅
own.share_of_turnover	Share of linked players' turnover	Provider studio "share of slot turnover" (ADR 0026)	prv	analytics_studio_account_day	✅
own.retention_d7 / _d30	Retention	Of Accounts linked in the cohort week, the share active again on day 7 / 30	op, prv	player_active_day	🟡
own.churn_rate	Monthly churn	Active in P−1 and not in P ÷ active in P−1	op, prv	player_active_day	🟡
own.points_issued	Points issued / funded	Σ ledger credits by campaign	op	points_ledger	✅
own.points_per_player	Points per active account	points issued ÷ active accounts	op	points_ledger	✅
own.qualification_rate	Rewarded-round qualification	Rounds credited ÷ rounds	prv	points_ledger, activity	✅
own.events_accepted	Ingest acceptance	Accepted ÷ received events, by reject_reason	op, prv (own integrations)	activity_events	✅
own.batch_latency	Batch latency	p50 / p95 of completed_at − received_at	op, prv	activity_batches	✅
own.attributed_players	Attributed / activated players	Players attributed to the affiliate; activation %	aff	attribution model	⏳
own.rewards_claimed	Rewards claimed		partner	rewards model	⏳

Network comparison KPIs (cmp.*)

Live in v1 (GET /v1/kpis/compare, see api/kpis.md):

• active_days, rounds_per_player, bet_per_player, ggr_per_player, points_per_player
• avg_stake, payout_ratio, churn_rate, link_conversion
• multi_homing, overlap_rate, share_of_wallet

The other rows below are planned.

How "the network" is measured:

• Per-player KPIs compare the median of your players with the distribution over the players of other parties of your type, one unit per (player, party) relationship.
• Ratio KPIs compare your ratio with the distribution of other parties' ratios.

Populations for a period P (closed week or month) and an optional market M:

• Y: Accounts in the party's reach on at least one day in P.
• R: all active PlayerPal Accounts (players.status = 'active') that were active in P, minus Y. R is the default baseline.
• N: all active Accounts, including Y. Shown as a secondary figure.

Response fields:

• you: the value over Y
• network: the value over R, plus network_all over N
• index: you ÷ network × 100
• band: where your players' median sits in the network's per-player distribution
• network_dist: {p25, p50, p75}
• suppressed, plus reason when it is

Per-player measures are computed per Account first and then aggregated, so the figures report medians as well as means.

ID	KPI	Definition (for Y and for R)	Who	Source	Status
cmp.active_rate	Active rate	Active Accounts ÷ Accounts in the population at the start of P	op, prv, aff	player_active_day, party_reach_day	🟡
cmp.active_days	Active days per active player	Median / mean of distinct active days per Account	op, prv	player_active_day	✅
cmp.stickiness	Stickiness	Mean DAU ÷ MAU	op, prv	player_active_day	✅
cmp.rounds_per_player	Rounds per active player	Median / mean of rounds per Account	op, prv	analytics_account_day	✅
cmp.bet_per_player	Turnover per active player	Median / mean of bet_eur per Account	op, prv	analytics_account_day	✅
cmp.ggr_per_player	GGR proxy per active player	Median / mean of (bet − win) per Account	op, prv	analytics_account_day	✅
cmp.avg_stake	Average stake	Σ bet_eur ÷ Σ rounds	op, prv	analytics_account_day	✅
cmp.payout_ratio	Observed payout ratio	Σ win ÷ Σ bet	op, prv	analytics_account_day	✅
cmp.retention_d7 / _d30	New-player retention	Of Accounts that joined in the cohort week (Y: linked to you; R: activated on PlayerPal), the share active again 7 / 30 days later	op, prv	player_active_day, identity_links, players.activated_at	🟡
cmp.churn_rate	Monthly churn	Active in P−1 and not in P ÷ active in P−1	op, prv	player_active_day	🟡
cmp.reactivation_rate	Reactivation	Active in P after ≥ 30 inactive days ÷ Accounts that were inactive	op, prv	player_active_day	🟡
cmp.tenure	Player tenure	Median days from players.activated_at to the end of P, over active Accounts	op, prv, aff	players	✅
cmp.points_per_player	Points earned per active player	Median / mean of ledger credits per Account	op	points_ledger	✅
cmp.redemption_rate	Redemption rate	Points redeemed ÷ points earned	op	rewards model	⏳
cmp.multi_homing	Operators per player	Median / mean of active operator links per Account	op, prv	identity_links	✅
cmp.overlap_rate	Overlap	Share of Y also active with ≥ 1 other party of your type (count only, never which)	op, prv	party_reach_day, activity	✅
cmp.share_of_wallet	Share of your players' turnover	Y's bet_eur with you ÷ Y's total bet_eur across PlayerPal. The network figure is the median share across parties of your type.	op, prv	analytics_account_*_day	✅ (op 🌍)
cmp.market_mix	Market mix	Share of bet_eur per market, Y vs R	op, prv	activity market	🌍
cmp.link_conversion	Link conversion	Completed ÷ created link_intents in P	op	link_intents	✅
cmp.time_to_first_play	Time to first play	Median hours from link completed to the first round with that party	op, prv	identity_links, activity	✅
cmp.game_mix	Game-category mix	Share of bet_eur by game category, Y vs R	op, prv	game category metadata	⏳

Benchmark KPIs

Any KPI marked benchmarkable in the catalogue: the per-party value of an Own-tier or cmp.* KPI, compared across peers of the same type. Response: peer {p25, p50, p75, mean}, the requester's band, peers shown as a band (e.g. "5–10"), or suppressed.

Staff-only KPIs (Network tier)

KPI	Source	Status
Signups and signup funnel by method	player_registrations, players	✅
Network DAU / WAU / MAU, stickiness	player_active_day	🟡
Network turnover, GGR, points liability	activity rollups, points_ledger	✅
Login success / failure by method	domain_events	🟡
Recovery-code use, account merges, deletions	recovery_attempt_log, player_account_merges, domain_events	✅ / 🟡
Connected parties by type, integrations by status	parties, integrations	✅
Ingest health across all integrations	activity_events, activity_batches	✅
KPI API usage per party and client	domain_events (kpi.api.accessed)	🟡

Domain events

Append-only domain_events, written in the same transaction as the change. No PII. Delete Account nulls player_id and keeps the event.

Group	Event types
Player	player.registered, player.activated, player.deleted
Auth	auth.login.succeeded (a session was issued; scope), auth.login.failed (method, reason), auth.session.revoked (actor player or staff)
Linking	link.intent_created (led), link.completed (proof_type), link.unlinked (cascaded), alias.issued / alias.revoked (alias_type); party_id is the audience
Planned	account.merged, auth.method.added / auth.method.revoked, auth.recovery.used
Ingest	batch.received (events), batch.completed (state, events, rejected, latency_ms); party_id is the provider
Data access	kpi.api.accessed
Partner credentials	partner.credential.created, partner.credential.rotated, partner.credential.revoked