API statistica e analisi: eventi, aggregazioni, retenschen

Testo completo dell'articolo

💡 18+. Materiale di ingegneria e analisi per piattaforme/operatori, studi (RGS/live) e comandi BI/CRM. Non una chiamata al gioco.

1) Perché l'API esterna degli analisti

Partner/provider: monitoraggio dei contenuti SLA, RTP, coinvolgimento.

Marketing/CRM - Campagne di trigger basate su metriche (DAU, vortice di deposito).

Transazioni/finanza: near-real-time GGR/NGR, successo dei pagamenti, lage-hook.

Prodotto: in-app widget statistiche, pannelli A/B.

L'obiettivo è quello di dare in modo sicuro e prevedibile eventi e aggregazioni con SLA e semantica comprensibile.

2) Architettura sulle dita


Producers (PAM/Wallet/RGS/Payments/Kafka/CDC)
│
Ingestion API ──Stream (Kafka/Pulsar) ──Lakehouse (Delta/Iceberg)
│                 └─OLAP (ClickHouse/BigQuery/Trino)
└────────────────────────────────────Aggregation/Query API
(cache, RBAC/RLS, rate limits)

Eventi: at-least-once, dedotto dì event _ id/idempotency _ key ".

Unità: rollup predefiniti (1m/5m/1h/1d) + on-the-fly.

Retenschen: motore cohort sopra Gold-mart.

Кэш: CDN/edge + ETag/`Cache-Control`, server-side TTL.

3) Modello di eventi: standard minimo

3. 1 Campi comuni

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "ingested_at":"2025-10-23T16:21:06Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",   // псевдо-ID
"trace_id":"tr_a1b2c3",  "schema_version":"1. 3. 0",  "payload":{...}
}

Regole: UTC timestams, 'player _ id' - alias, denaro in minor units.

3. 2 Tipi chiave

`session. started	ended`
`bet. placed	settled` (stake_minor, win_minor, in_bonus, game_id, provider_id)
`wallet. debit	credit` (reason, reference_id)
`payment. intent	authorized
`bonus. issued	consumed
`rg. limit. hit	reality_check`
Versioning - semver; Aggiungere solo optional.

4) Ingestione API (per terze parti)

Invia pacchetto eventi


POST /v1/events:batch
Headers: X-Idempotency-Key: ev_20251023_001
[
{"event_id":"...","event_type":"bet. placed",...},  {"event_id":"...","event_type":"bet. settled",...}
]
→ 202 { "accepted":2, "duplicates":0, "trace_id":"tr_a1b2" }

Garanzie: at-least-once; i duplicati vengono filtrati in Silver per «event _ id».

5) Agregation API: time-series e tagli

5. 1 Timeserie (metriche nel tempo)


GET /v1/analytics/timeseries
?metric=ggr    // ggr, ngr, dau, deposits_success, rtp
&granularity=5m  // 1m/5m/1h/1d
&from=2025-10-22T00:00:00Z&to=2025-10-23T00:00:00Z
&filters=region:EU,brand_id:brand-7,provider_id:studio_x
&group_by=brand_id
→ 200 {
"metric":"ggr",  "granularity":"5m",  "series":[
{"ts":"2025-10-22T00:00:00Z","brand_id":"brand-7","value_minor":120030},   {"ts":"2025-10-22T00:05:00Z","brand_id":"brand-7","value_minor":98020}
],  "next_cursor":null
}

5. 2 Tagli/top (group-by)


GET /v1/analytics/slice
?metric=rtp &dim=game_id &from=2025-10-22&to=2025-10-23
&limit=50&order=-value
→ 200 { "items":[{"game_id":"g_01","value":0. 956},...] }

5. 3 Vortici (funnel)


POST /v1/analytics/funnel
{
"steps":[
{"event":"payment. intent"},   {"event":"payment. authorized"},   {"event":"payment. captured"},   {"event":"wallet. credit", "reason":"deposit"}
],  "window_sec": 3600,  "filters":{"region":"EU","brand_id":"brand-7"}
}
→ 200 {
"total": 12450,  "steps": [
{"name":"intent", "count":12450, "rate":1. 0},   {"name":"authorized", "count":11020, "rate":0. 885},   {"name":"captured", "count":10110, "rate":0. 811},   {"name":"credited", "count":10050, "rate":0. 807}
]
}

5. 4 Limiti e cache

Rate limit per token/brand/region.

«ETAG» alle risposte; supporto dì If-None-Match '.

La cache TTL dipende da «granularity» (ad esempio 5m → TTL 60-120 s).

6) Retensshen e coorti: regole e API

6. 1 Definizioni (convenzioni)

DAU/WAU/MAU è attivo se è stato 'bet. placed'o'wallet. credit (deposit)` или `session. started' ≥ N minuti.

Cohort by first deposit (spesso per LTV) o by registration (per l'inclusione).

Ritorno D1/D7/D30 - La quota della coorte è tornata dalla finestra del giorno +/- la tolleranza nella zona temporale del marchio.

Le visite ripetute sono basate su un'player _ id "univoco nella finestra.

6. 2 coorti API


POST /v1/analytics/retention
{
"cohort":"first_deposit",  "start_date":"2025-09-01",  "end_date":"2025-09-30",  "return_event":"bet. placed",  "days":[1,7,14,30],  "filters":{"region":"EU","brand_id":"brand-7"}
}
→ 200 {
"cohort":"first_deposit",  "rows":[
{"cohort_date":"2025-09-01","size":1820,"d1":0. 36,"d7":0. 22,"d14":0. 18,"d30":0. 12},   {"cohort_date":"2025-09-02","size":1714,"d1":0. 35,"d7":0. 23,"d14":0. 19,"d30":0. 13}
]
}

6. 3 LTV/cumulativi


GET /v1/analytics/ltv? cohort=first_deposit&currency=EUR&horizon=90d
→ 200 { "cohorts":[{"date":"2025-09-01","ltv_minor":[0,150,230,280,...]}] }

7) Semantica delle metriche (per non discutere)

Metrica	Definizione (breve)
GGR	sum(stake) − sum(win) по `bet. settled'nel periodo/valuta
NGR	GGR - spese bonus - jackpot contributi - commissione
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (coefficiente)
Settle lag	t (settled) - t (placed), percento p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	Giocatori unici attivi in base alle regole di attività

Tutti in UTC con moneta e minor units; La multivalenza è decisa dalla conversione FX fissata in Data Lake.

8) Versione, filtri e compatibilità

Percorso: '/v1/... '; nuove metriche/campi - optional.

Фильтры: `brand_id, region, provider_id, game_id, method, currency, device, geo`.

Paginazione: cursor-based ('next _ cursor').

Breaking solo '/v2 '+ Deprecation/Sunset titoli e changelog.

9) Sicurezza e accesso

OAUTh2 Client Credentials (token a breve vita), mTLS per B2B.

RBAC/ABAC: autorizzazioni per metriche/tagli; filtro RLS per «brand/region».

PII: L'API non dà PII, solo unità/pseudo-ID se necessario.

Residenza: instradamento delle richieste nella regione Dati crocifissi - vietati.

Rate limits e quote, anti-abuse; Controllo WORM delle disponibilità.

10) SLO e osservabilità

Punti di riferimento SLO:

"GET/timeserie gran = 5m'p95" 500-800 mc, "GET/slice" p95 "1-2 s (top a 50-100 posizioni)," POST/retrazione "(mese) p95-3-5 c, freschezza rollup'a: p95-2-5 min da" occurred _ at ".
Metriche: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, interrogazioni/scan-byte (OLAP), «freshness lag» per ogni rollup'y.
I loghi sono strutturati, 'trace _ id', filtri di query (senza PII), conto scene.

11) Cache, calcoli preliminari, costo

Tabelle Rollup: 1m/5m/1h/1d per metriche chiave «timeserie» veloci.

Materialization views per tagli pesanti/cocort.

ETag + max-age; la disabilità in casi di eventi recenti è incrementale.

Strategia hot/cold: richieste hot - in OLAP-warehouse; l'archivio è a Lake.

Limitazione degli scan byte alla richiesta suggerimenti al pianificatore.

12) Incorporazione (embedded) ed esportazione

Widget incorporati tramite signed URL/iFrame con i token RLS.

Esporta l'API CSV/Parquet con vincoli di quota e riferimenti temporanei.

Notifiche di avvio webhook.

13) Assegno fogli

Architettura

Un unico schema di eventi, semver, registry; Dedotto dì event _ id ".
Rollup's e materialization views sotto la top valige.
RLS/RBAC/ABAC, residenza, token a breve vita.
Cache (ETag/TTL), rate limits, quote.

Semantica

Le definizioni GGR/NGR/RTP/DAU/retention sono documentate.
Valute - minor units; FX viene registrato al momento dell'evento.
Ritenzione UTC, tenendo conto dei timsons di marca nella visualizzazione.

Operazioni

SLO/dashboard di freschezza e latitanza.
Controllo WORM delle disponibilità/esportazioni.
DR./xaoc-esercitazione: ritardo rollup, ondata di richieste, eventi in ritardo.

14) Anti-pattern (bandiere rosse)

Le tabelle OLTP crude vengono assegnate direttamente all'API.

Definizioni di metriche incoerenti tra i comandi.

L'assenza di deduplo e watermarks è un evento doppio/perduto.

Aggregazioni illimitate on-the-fly senza cache/quote sono costose e lente.

Aggregazione crociata-regionale senza politica di residenza.

Restituisce PII/dettagli del giocatore alle risposte pubbliche.

Breaking-changes silenziosi senza «/v2 »e Deprecation.

15) Mini speck (TL; DR)

Eventi: '/v1/events: batch '.

Timeserie: '/v1/analytics/timeserie? metric=...&granularity=...` (rollup + кэш).

Tagli: '/v1/analytics/slice? metric=...&dim=...`.

Vortici: '/v1/analytics/funnel '(finestra, passi, filtri).

Retenschen/cohort: '/v1/analytics/retention '(+ LTV).

Sicurezza: OAuth2+mTLS, RLS, token per brand/region, controllo WORM.

SLO: p95 ≤ 0. 5-2 c; Freschezza di 2-5 minuti.

L'API delle statistiche e degli analisti non è «SELECT FROM big _ table», ma un contratto di metriche: eventi stabili, aggregazioni preconfezionate e memorizzate nella cache, retensing e coorti rigorosamente definiti, sicurezza (RLS/RBAC) e residenza comprensibili da SLO. In questo modo i dati vengono forniti in modo rapido, economico e prevedibile ai partner, al prodotto e alla BI, senza interpretazioni controverse e senza rischi di perdita o sovraccarico del deposito.