API Statistiques et Analyses : Événements, agrégats, Retenshen

Texte intégral de l'article

💡 18+. Matériel d'ingénierie et d'analyse pour plates-formes/opérateurs, studios (RGS/live) et équipes BI/CRM. Pas un appel au jeu.

1) Pourquoi l'API analytique externe

Partenaires/fournisseurs : Surveillance du contenu SLA, RTP, implication.

Marketing/CRM : campagnes de déclenchement basées sur des métriques (DAU, entonnoir de dépôt).

Opérations/finances : RGG/RGG en temps réel, succès des paiements, tarifs des webhooks.

Produit : widgets de statistiques in-app, panneaux A/B.

L'objectif est de donner des événements et des agrégats de manière sûre et prévisible avec une sémantique compréhensible et un SLA.

2) L'architecture sur les doigts


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)

Événements : at-least-once, dedup par 'event _ id/idempotency _ key'.

Agrégats : rollup's (1m/5m/1h/1d) + on-the-fly.

Retenshen : moteur cohort au-dessus des marts d'or.

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

3) Modèle d'événement : norme minimale

3. 1 Champs communs

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":{...}
}

Règles : timestamps UTC, 'player _ id' est un pseudonyme, argent en unités mineures.

3. 2 types clés

`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 ; ajouts uniquement optional.

4) API d'ingestion (pour les sources tierces)

Envoyer un paquet d'événements


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" }

Garanties : at-least-once ; les doublons sont filtrés dans Silver par 'event _ id'.

5) API d'aggregation : time-series et tranches

5. 1 Temps (métriques temporelles)


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 Tranches/tops (groupe-par)


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 Entonnoirs (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 Limites et cache

Rate limit per token/brand/region.

« ETag » aux réponses ; prise en charge de « If-None-Match ».

Le cache TTL dépend de « granularity » (par exemple, 5m → TTL 60-120 s).

6) Rettenschen et cohortes : règles et API

6. 1 Définitions (conventions)

DAU/WAU/MAU : actif s'il y avait 'bet. placed 'ou' wallet. credit (deposit)` или `session. started' ≥ N minutes.

Cohort par first deposit (souvent pour LTV) ou par registration (pour l'engagement).

Retraite D1/D7/D30 : la proportion de la cohorte est revenue à la fenêtre du jour +/- la zone temporelle de la marque.

Les visites répétées sont comptées par l'unique 'player _ id' dans la fenêtre.

6. 2 API de cohorte


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/cumulatifs


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

7) Métriques sémantiques (à ne pas argumenter)

Métrique	Définition (brève)
GGR	sum(stake) − sum(win) по `bet. settled 'en période/monnaie
NGR	GGR − frais de prime − contributions au jackpot − commissions
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (coefficient)
Settle lag	t (settled) − t (placed), percentile p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	joueurs actifs uniques selon les règles d'activité

Tous - en UTC avec la monnaie et les unités mineures ; la multivalence est décidée par conversion sur les FX fixes en Data Lake.

8) Versification, filtres et compatibilité

Chemin : '/v1/... '; les nouvelles métriques/champs sont optionnels.

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

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

Breaking → uniquement les titres '/v2 '+ Deprecation/Sunset et changelog.

9) Sécurité et accès

OAuth2 Client Credentials (jetons à courte durée de vie), mTLS pour B2B.

RBAC/ABAC : permis métriques/tranches ; filtre RLS par 'brand/region'.

PII : L'API ne donne pas PII, seulement les agrégats/pseudo-ID si nécessaire.

Résidence : acheminement des demandes vers la région ; données transrégionales - interdites.

Limites de taux et quotas, anti-abysse ; Audit WORM des accès.

10) SLO et observabilité

SLO repères :

'GET/timeseries gran = 5m'p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (tops jusqu'à 50-100 positions), 'POST/retraite' (mois de cohortes) p95 ≤ 3-5 s, fraîcheur rollup's : p95 ≤ 2-5 min de 'occurred _ at'.
Métriques : latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, requêtes/scan-octets (OLAP), « freshness lag » pour chaque rollup 'y.
Logs : structurés, 'trace _ id', filtres de requête (sans PII), compte de scans.

11) Cache, calculs préliminaires, coût

Tables rollup : 1m/5m/1h/1d sur les métriques clés → rapides 'timeseries'.

Vues materialized pour tranches lourdes/cochort.

ETag + max-age; l'invalidité en cas d'événements tardifs est incrémentale.

La stratégie "hot/cold' : les demandes chaudes - dans OLAP-warehouse ; les archives sont à Lake.

Limiter les « scan-octets » à la requête ; des indices pour le planificateur.

12) Incorporation (embedded) et exportation

Widgets intégrés via l'URL signée/iFrame avec des tokens RLS.

Exporte CSV/Parquet par tâche (job API) avec des restrictions de taille et des références temporaires.

Notifications Webhook de disponibilité de déchargement.

13) Chèques-feuilles

Architecture

Schéma unique des événements, semver, registry ; dedup par 'event _ id'.
Rollup's et materialized views sous le top case.
RLS/RBAC/ABAC, résidence, tokens à courte durée de vie.
Cache (ETag/TTL), taux limites, quotas.

La sémantique

Les définitions de GGR/NGR/RTP/DAU/rétention sont documentées.
Monnaies - unités mineures ; FX est fixé au moment de l'événement.
Retentation par UTC, compte tenu des timesons de marque dans l'affichage.

Opérations

SLO/dashboards de fraîcheur et de latence.
Audit WORM des accès/exportations.
DR/xaoc-exercice : rollup en retard, flot de demandes, événements tardifs.

14) Anti-modèles (drapeaux rouges)

Les tables OLTP « crues » sont données directement dans l'API.

Définitions incohérentes des métriques entre les commandes.

L'absence de dedup et de watermarks → les événements doubles/perdus.

Безлимитные on-the-fly les aggrégations sans cache/quotas → les demandes chères et lentes.

Agrégation intersectorielle sans politique de résidence.

Retour PII/détails du joueur dans les réponses publiques.

Breaking-changes silencieux sans '/v2 'et Deprecation.

15) Mini-Speck (TL ; DR)

Événements : '/v1/events : batch '(at-least-once, dedup par' event _ id ').

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

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

Entonnoir : '/v1/analytics/funnel '(fenêtre, étapes, filtres).

Retenshen/cohortes : '/v1/analytics/retentation '(+ LTV).

Sécurité : OAuth2 + mTLS, RLS, tokens per brand/region, audit WORM.

SLO: p95 ≤ 0. 5-2 s ; fraîcheur ≤ 2-5 min.

API les statisticiens et les analystes sont non "SELECT FROM big_table", et le contrat des actes de naissance : les événements stables, précompté et кэшируемые les groupes de machines, strictement défini ретеншен et les cohortes, la sécurité (RLS/RBAC) et резидентность, clair SLO. C'est ainsi que vous donnez les données rapidement, à moindre coût et de manière prévisible - partenaires, produits et BI - sans interprétations controversées et sans risque de fuite ou de surcharge de stockage.