API-uri de statistică și analiză: evenimente, agregate, retenție

Articol complet

💡 18+. Analiza ingineriei pentru platforme/operatori, studiouri (RGS/live) și echipe BI/CRM. Nu este un apel pentru a juca.

1) De ce un API de analiză externă

Parteneri/furnizori: SLA content monitoring, RTP, engagement.

Marketing/CRM: campanii de declanșare bazate pe valori (DA, pâlnie de depozit).

Operațiuni/Finanțe: aproape în timp real GGR/NGR, succes de plată, lag-uri de cârlig web.

Produs: widget-uri statistice în aplicație, panouri A/B.

Scopul este de a reda în siguranță și previzibil evenimentele și agregatele cu semantică și SLA-uri ușor de înțeles.

2) Arhitectura pe degete


Producători (PAM/Portofel/RGS/Plăți/Kafka/CDC)
│
Ingestie API ──Stream (Kafka/Pulsar) ──Lakehouse (Delta/Iceberg)
│ └─OLAP (ClickHouse/BigQuery/Trino)
└────────────────────────────────────Aggregation/Query API
(cache, RBAC/RLS, limite de rată)

Evenimente: cel puțin o dată, bunicul prin 'event _ id/idempotency _ key'.

Agregate: rulouri pre-calculate (1m/5m/1h/1d) + on-the-fly.

Retenchen: motor de cohortă deasupra Gold Marts.

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

3) Modelul evenimentului: standard minim

3. 1 Câmpuri comune

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," regiune ":" EU "," player_id":"p_19f3, "// псевдо -ID
"trace_id":"tr_a1b2c3," "schema_version":"1. 3. 0", "sarcină utilă": {...}
}

Reguli: marcaje de timp UTC, 'player _ id' - alias, bani în unități minore.

3. 2 Tipuri de taste

"sesiune. a început	ended '
"bet. plasat	settled '( , , , )
"umed. debit	credit "(motiv, reference_id)
"plata. intenţie	autorizat
"bonus. emise	consumate
"rg. limită. hit	reality_check'
Versioning - semver; adăugarea numai opțional.

4) API de ingestie (pentru surse terțe)

Trimiterea unui lot de evenimente


POST/v1/evenimente: lot
Anteturi: X-Idempotency-Key: ev_20251023_001
[
{"event _ id':"..., "event _ type": "bet. plasat, „...}, {” event _ id': „...,” event _ type „:” bet. settled,"..}
]
→ 202 {„acceptat”: 2 „, duplicate”: 0 „, trace_id":"tr_a1b2”}

Garanții: cel puțin o dată; duplicatele sunt filtrate în Silver prin 'event _ id'.

5) API de agregare: serii de timp și felii

5. 1 Timeseries (măsurarea timpului)


GET/v1/analytics/timeseries
? metric = grg//ggr, ngr, dat, deposits_success, rtp
& granularitate = 5m//1m/5m/1h/1d
& from = 2025-10-22T00: 00: 00Z & to = 2025-10-23T00: 00: 00Z
& filtre = regiune: EU, brand _ id: brand-7, provider _ id: studio _ x
& grup _ by = brand _ id
→ 200 {
„metric”:” gr”, „granularitate”:” 5m”, „serie”: [
{„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 felii/topuri (de grup)


GET/v1/analytics/felie
? metric = rtp & dim = game _ id & from = 2025-10-22 & to = 2025-10-23
& limită = 50 & comandă = -valoare
→ 200 {„items': [{” game _ id': „g _ 01”, „value”: 0. 956},...] }

5. 3 Pâlnii


POST/v1/analytics/pâlnie
{
„pași”: [
{"eveniment ":" plată. intenție”}, {„eveniment „:” plată. autorizat”}, {„eveniment „:” plată. capturat”}, {„eveniment „:” portofel. credit", "motiv ": "depozit"}
], „window_sec": 3600”, filtre „: {” regiune „:” EU „,” brand _ id': „brand-7”}
}
→ 200 {
„total”: 12450, „pași”: [
{„nume „:” intenție”, „număr „: 12450, „rată”: 1. 0}, {„nume „: „autorizat”, „număr „: 11020, „rată”: 0. 885}, {„nume „: „capturat”, „numărat „: 10110, „rată”: 0. 811}, {„nume „: „creditat”, „număr „: 10050, „rată”: 0. 807}
]
}

5. 4 Limite și memorie cache

Limita ratei per jeton/brand/regiune.

"ETag 'la răspunsuri; Suport „If-None-Match”.

Memoria cache TTL depinde de granularitate (de exemplu, 5m → TTL 60-120 s).

6) Retenție și cohorte: reguli și API

6. 1 Definiții (convenții)

DA/WAU/MAU: activ if was 'bet. plasat „sau” portofel. credit (depozit) „или” sesiune. a început "≥ N minute.

Cohorta prin primul depozit (de multe ori pentru LTV) sau prin înregistrare (pentru implicare).

D1/D7/D30 de retenție: proporția din cohortă a revenit la fereastra de zi +/- toleranță în funcție de fusul orar al mărcii.

Considerăm vizite repetate de către "player _ id' unic în fereastra.

6. 2 cohorte API


POST/v1/analytics/retenţie
{
"cohortă ": "first _ deposit", "start_date":"2025-09-01," "end_date":"2025-09-30," return_event":"bet ". plasat, "zile": [1,7,14,30], "filtre": {"regiune": "EU", "brand _ id':" brand-7 "}
}
→ 200 {
„cohortă „: „first _ deposit”, „rânduri”: [
{„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/Cumulativ


GET/v1/analytics/ltv? cohort = first _ deposit & valute = EUR & orizont = 90d
→ 200 {„cohorte „: [{” date”:” 2025-09-01 „, „ltv _ minor „: [0,150,230,280,...]]]}

7) Semantică metrică (pentru a nu argumenta)

Măsurători	Definiție (scurtă)
RGG	suma (miza) − suma (win) по 'pariu. decontate "în perioadă/valută
NGR	Cheltuieli GGR − Bonus − Contribuții Jackpot − Comisie
RTP	sumă (câștig )/sumă (miză)
Succesul depozitului	capturat/intenție (factor)
Reglați decalajul	t (stabilit) − t (plasat), percentila p95
Webhook lag	t (ingerat) − t (a avut loc), p95
DA/WAU/MAU	jucători activi unici după regulile de activitate

Toate - în UTC cu valută și unități minore; multicurrency este rezolvată prin conversia FX fix la Data Lake.

8) Versiune, filtre și compatibilitate

Cale: '/v1/... '; noi metrici/câmpuri - opțional.

Фильтры: 'brand _ id, regiune, provider_id, game_id, metodă, monedă, dispozitiv, geo'.

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

Breaking → numai '/v2 '+ Respingere/Apus de soare antete și changelog.

9) Securitate și acces

OAuth2 Client Acreditări (jetoane de scurtă durată), mTLS pentru B2B.

RBAC/ABAC: permisiuni metrice/felii; Filtru RLS după „marcă/regiune”.

PII: API nu dă PII, numai agregate/pseudo-ID, dacă este necesar.

Rezidență: cereri de rutare în regiune; date transversale - nu este permis.

Limitele și cotele de rată, anti-abuz; Auditul WORM al acceselor.

10) SLO și observabilitate

Criterii de referință SLO:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms,' GET/felie 'p95 ≤ 1-2' s (cel mult 50-100 poziții), 'POST/retenție' (luna cohortelor) p95 ≤ 3-5's, prospețime rollup: p95 ≤ 2-5 min from 'a apărut _ at'.
Metrica: latenta p50/p95/p99, rata de eroare (4xx/5xx), cache-hit, cereri/scanare octeti (OLAP), lag de prospetime pentru fiecare rollup 'y.
Jurnale: structurat, 'trace _ id', filtre de interogare (fără PII), număr de scanare.

11) Numerar, calcule preliminare, cost

Tabele Rollup: 1m/5m/1h/1d de măsurători cheie → fast 'timeseries'.

Vizualizări materializate pentru secțiuni/cohorte grele.

ETag + max-age; handicap în evenimentele tardive apare treptat.

Strategia „cald/rece”: interogări la cald - în depozitul OLAP; arhivă - în Lacul.

Restricționarea „octeților de scanare” la cerere; sugestii pentru programator.

12) Încorporat și export

Widget-uri încorporate prin URL/iFrame semnat cu jetoane RLS.

Exportați CSV/Parchet după sarcină (API de locuri de muncă) cu constrângeri de dimensiune și referințe temporare.

Webhook notificări despre disponibilitatea de încărcare.

13) Liste de verificare

Arhitectură

Schema de evenimente unificate, semver, registru; bunicul prin 'event _ id'.
Rollup și vizualizări materializate pentru cazurile de top.
RLS/RBAC/ABAC, rezidență, jetoane de scurtă durată.
Cache (ETag/TTL), limite de rată, cote.

Semantică

Definițiile GGR/NGR/RTP/DA/retenție sunt documentate.
Valute - unități minore; FX este fixat la momentul evenimentului.
Reținerea de către UTC, ținând cont de fusul orar al mărcii în afișaj.

Operațiuni

Tablouri de bord SLO/prospețime și latență.
Auditul WORM al acceselor/exporturilor.
DR/xaoc exerciții: rollup lag, flurry de cereri, evenimente târzii.

14) Anti-modele (steaguri roșii)

Tabelele OLTP „raw” sunt date direct API.

Definiții metrice inconsecvente între comenzi.

Fără deduplicare și filigrane → evenimente duble/pierdute.

Agregări nelimitate în timpul zborului fără cache/cote → solicitări costisitoare și lente.

Agregarea transregională fără politici de rezidență.

Return PII/player detalii la răspunsurile publice.

Schimbări de rupere liniștite fără „/v2 ”și depreciere.

15) Mini-specificaţii (TL; DR)

Evenimente: '/v1/events: lot '(cel puțin o dată, dedup by' event _ id').

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

Felii: '/v1/analytics/felie? metric =... & dim =... '.

Pâlnii: '/v1/analytics/pâlnie '(fereastră, pași, filtre).

Retenție/cohorte: „/v1/analytics/retention ”(+ LTV).

Securitate: OAuth2 + mTLS, RLS, token-uri de marcă/regiune, audit WORM.

SLO: p95 ≤ 0. 5-2 s; prospețime ≤ 2-5 min.

Statisticile și API-urile de analiză nu sunt "SELECT FROM big_table, ci un contract de valori: evenimente stabile, agregate pre-citite și cache, retenție și cohorte strict definite, securitate (RLS/RBAC) și rezidență ușor de înțeles de SLO. Deci, oferiți date rapid, ieftin și previzibil - partenerilor, produsului și BI - fără interpretări controversate și fără riscul de scurgere sau suprasarcină de stocare.