Statistik und Analyse API: Ereignisse, Aggregate, Retention

Vollständiger Artikel

💡 18+. Engineering und analytisches Material für Plattformen/Betreiber, Studios (RGS/live) und BI/CRM-Teams. Kein Aufruf zum Spiel.

1) Warum eine externe Analyse-API

Partner/Anbieter: SLA Content Monitoring, RTP, Engagement.

Marketing/CRM: Metrikbasierte Triggerkampagnen (DAU, Deposit Funnel).

Betrieb/Finanzen: Near-Real-Time GGR/NGR, Zahlungserfolg, Webhook-Lags.

Produkt: In-App-Statistik-Widgets, A/B-Panels.

Ziel ist es, Ereignisse und Aggregate mit verständlicher Semantik und SLA sicher und vorhersehbar zu verschenken.

2) Architektur an den Fingern


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)

Veranstaltungen: at-least-once, dedup durch 'event _ id/idempotency _ key'.

Einheiten: Pre-Countdown Rollups (1m/5m/1h/1d) + on-the-fly.

Rethenschen: Cohort-Engine über Gold-Marts.

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

3) Ereignismodell: Mindeststandard

3. 1 Allgemeine Felder

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

Regeln: UTC-Zeitstempel, 'player _ id' - Alias, Geld in kleineren Einheiten.

3. 2 Schlüsseltypen

`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`
Versionierung - semver; nur optional hinzufügen.

4) Ingestion API (für Drittquellen)

Senden eines Ereignispakets


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

Garantien: at-least-once; Duplikate werden in Silver nach 'event _ id' gefiltert.

5) Aggregation API: Zeitreihen und Schnitte

5. 1 Zeitreihen (Zeitmetriken)


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 Slices/Tops (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 Trichter (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 Limits und Cache

Rate limit per token/brand/region.

„ETag“ für die Antworten; Unterstützung für „If-None-Match“.

Der TTL-Cache hängt von „granularity“ ab (z. B. 5m → TTL 60-120 s).

6) Retenschen und Kohorten: Regeln und APIs

6. 1 Definitionen (Konventionen)

DAU/WAU/MAU: aktiv, wenn 'bet. placed 'oder' wallet. credit (deposit)` или `session. started '≥ N Minuten.

Cohort durch erste Einzahlung (oft für LTV) oder durch Registrierung (für Engagement).

Retention D1/D7/D30: Der Anteil aus der Kohorte ist wieder im Tagesfenster +/- Eintritt in die Zeitzone der Marke.

Wiederholte Besuche zählen durch das einzigartige' player _ id 'im Fenster.

6. 2 Kohorten-APIs


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


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

7) Semantik der Metriken (um nicht zu streiten)

Metrik	Definition (kurz)
GGR	sum(stake) − sum(win) по `bet. settled 'in Periode/Währung
NGR	GGR − Bonuskosten − Jackpot-Beiträge − Provisionen
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (Koeffizient)
Settle lag	t (settled) − t (placed), Perzentil p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	einzigartige aktive Spieler nach Aktivitätsregeln

Alle - in UTC mit Angabe der Währung und minor units; Multi-Currency wird durch die Konvertierung von fixierten FX in Data Lake gelöst.

8) Version, Filter und Kompatibilität

Pfad: „/v1/... “; neue Metriken/Felder - optional.

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

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

Breaking → nur '/v2'+ Deprecation/Sunset Header und changelog.

9) Sicherheit und Zugang

OAuth2 Client Credentials (kurz lebende Token), mTLS für B2B.

RBAC/ABAC: Berechtigungen für Metriken/Abschnitte; RLS-Filter nach 'Marke/Region'.

PII: Die API gibt keine PII, nur Aggregate/Pseudo-IDs, falls erforderlich.

Wohnsitz: Weiterleitung von Anfragen in die Region; Cross-regionale Daten sind verboten.

Rate Limits und Quoten, Anti-Missbrauch; WORM-Audit der Zugriffe.

10) SLO und Beobachtbarkeit

SLO-Richtlinien:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (tops zu 50-100 Positionen), 'POST/retention' (Monat der Kohorten) p95 ≤ 3-5 s, Frische rollup's: p95 ≤ 2-5 min von 'occurred _ at'.
Metriken: Latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, requests/scan-bytes (OLAP), „freshness lag“ pro rollup 'y.
Protokolle: strukturiert, 'trace _ id', Abfragefilter (ohne PII), Scankonto.

11) Cache, vorläufige Berechnungen, Kosten

Rollup-Tabellen: 1m/5m/1h/1d für Schlüsselmetriken → schnelle' timeseries'.

Materialisierte Ansichten für schwere Schnitte/Kohort.

ETag + max-age; Behinderung mit späten Ereignissen tritt inkrementell auf.

Strategie „heiß/kalt“: heiße Anfragen - im OLAP-Lager; Archiv ist in Lake.

Beschränkung der „Scan-Bytes“ auf die Anforderung; Hinweise an den Planer.

12) Einbettung (embedded) und Export

Eingebaute Widgets über signierte URLs/iFrames mit RLS-Token.

CSV/Parkett nach Aufgaben exportieren (Job API) mit Größenbeschränkungen und Zeitreferenzen.

Webhook-Benachrichtigungen über Upload-Bereitschaft.

13) Checklisten

Architektur

Einzelereignisschema, semver, registry; dedup von 'event _ id'.
Rollups und materialisierte Ansichten unter den Top-Fällen.
RLS/RBAC/ABAC, Wohnsitz, Token kurz lebendig.
Cache (ETag/TTL), Ratenlimits, Quoten.

Semantik

Die Definitionen von GGR/NGR/RTP/DAU/retention sind dokumentiert.
Währungen - minor units; FX wird zum Zeitpunkt des Ereignisses festgelegt.
Retention durch UTC unter Berücksichtigung der Marke Zeitzonen in der Anzeige.

Operationen

SLO/Dashboards für Frische und Latenz.
WORM-Audit Zugriffe/Exporte.
DR/xaoc-Übungen: Rollup-Verzögerung, Flut von Anfragen, verspätete Ereignisse.

14) Anti-Muster (rote Fahnen)

„Rohe“ OLTP-Tabellen werden direkt an die API übergeben.

Inkonsistente Definitionen von Metriken zwischen Teams.

Keine Deduplizierung und Wasserzeichen → doppelte/verlorene Ereignisse.

Unbegrenzte On-the-Fly-Aggregationen ohne Cache/Kontingente → teure und langsame Anfragen.

Überregionale Aggregation ohne Residenzpolitik.

Rückgabe von PII/Spielerdetails an öffentliche Antworten.

Stille Breaking-Changes ohne '/v2 'und Deprecation.

15) Mini-Speck (TL; DR)

Ereignisse: '/v1/events: batch'(at-least-once, dedup by 'event _ id').

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

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

Trichter: '/v1/analytics/funnel'(Fenster, Schritte, Filter).

Rethenschen/kohorty: '/v1/analytics/retention'(+ LTV).

Sicherheit: OAuth2 + mTLS, RLS, Token pro Marke/Region, WORM-Audit.

SLO: p95 ≤ 0. 5-2 s; Frische ≤ 2-5 min.

Die Statistik und Analyse-API ist kein "SELECT FROM big_table", sondern ein Metrikvertrag: stabile Ereignisse, vorlesbare und zwischengespeicherte Aggregate, streng definierte Retenschen und Kohorten, Sicherheit (RLS/RBAC) und Wohnsitz, die von SLOs verstanden werden. So geben Sie Daten schnell, günstig und vorhersehbar - an Partner, Produkt und BI - ohne strittige Interpretationen und ohne das Risiko von Leckagen oder Speicherüberlastung.