Bieg torrent

Statystyki i analizy API: Wydarzenia, agregaty, retencja

Pełny artykuł

💡 18+. Analiza inżynieryjna dla platform/operatorów, studiów (RGS/live) i zespołów BI/CRM. Ani telefonu do zabawy.

1) Dlaczego API analityki zewnętrznej

Partnerzy/dostawcy: monitorowanie zawartości SLA, RTP, zaangażowanie.

Marketing/CRM: kampanie spustowe oparte na metrykach (DAU, deposit lejek).

Operacje/Finanse: niemal w czasie rzeczywistym GGR/NGR, sukces płatniczy, opóźnienia w haku internetowym.

Produkt: widżety statystyki w aplikacji, panele A/B.

Celem jest bezpieczne i przewidywalne przywrócenie zdarzeń i agregatów o zrozumiałej semantyce i SLA.

2) Architektura na palcach


Producenci (PAM/Portfel/RGS/Payments/Kafka/CDC)
│
Połknięcie API   Stream (Kafka/Pulsar)  Lakehouse (Delta/Góra Lodowa)
└─OLAP (ClickHouse/Query/Trino)
└────────────────────────────────────Aggregation/Query API
(pamięć podręczna, RBAC/RLS, limity stawek)

Wydarzenia: co najmniej raz, dziadek przez 'event _ id/idempotence _ key'.

Kruszywa: wstępnie obliczone rollups (1m/5m/1h/1d) + on-the-fly.

Siatkówka: silnik kohortowy na szczycie Gold Marts.

Ekran: CDN/edge + ETag/' Cache-Control ', serwer-side TTL.

3) Model zdarzenia: minimalny standard

3. 1 Pola wspólne

json
{
"event_id":"uuid," "event_type":"bet. osiadły, „” occurred_at":"2025-10-23T16:21:05Z, „” ingested_at":"2025-10-23T16:21:06Z, „tenant_id":"brand-7,” „region”: „UE”, „player_id":"p_19f3, ”//бсевда-ID
"trace_id":"tr_a1b2c3," "schema_version":"1. 3. 0", "ładunek użytkowy": {...}
}

Zasady: znaczniki czasu UTC, 'player _ id' - alias, pieniądze w małych jednostkach.

3. 2 Typy kluczowych

"sesja. rozpoczęty	zakończone "
'bet. umieszczone	osiadły "(stake_minor, win_minor, in_bonus, game_id, provider_id)
'portfel. debet	kredyt "(powód, reference_id)
"płatność. zamiar	autoryzowany
'bonus. wydane	spożywane
'rg. limit. trafienie	reality_check'
Wersioning - semver; dodanie tylko opcjonalne.

4) Ingestion API (dla źródeł zewnętrznych)

Wysyłanie partii wydarzeń


POST/v1/zdarzenia: partia
Nagłówki: X-Idempotency-Key: ev_20251023_001
[
{„event _ id':”... „,” event _ type „:” bet. placed, "...}, {" event _ id': "...", "event _ type": "bet. osiadły,"..}
]
→ 202 {„przyjęte”: 2, „duplikaty”: 0, „trace_id":"tr_a1b2”}

Gwarancje: przynajmniej raz; duplikaty są filtrowane w Silver przez 'event _ id'.

5) Agregacja API: seria czasowa i plasterki

5. 1 Timeseries (metryki czasu)


GET/v1/analytics/timeseries
? metric = ggr//ggr, ngr, dau, deposits_success, rtp
& granularity = 5m//1m/5m/1h/1d
od = 2025-10-22T00: 00: 00Z & do = 2025-10-23T00: 00: 00Z
& filtry = region: UE, marka _ id: marka-7, provider _ id: studio _ x
& group _ by = marka _ id
→ 200 {
„metryczne”:” ggr”, „ziarnistość”:” 5m”, „seria”: [
{"ts':" 2025-10-22T00: 00: 00Z "," marka _ id': "marka-7", "wartość _ mniejsza": 120030}, {"ts':" 2025-10-22T00: 05: 00Z "," marka _ id': "marka-7", "value _ minor" ": 98020}
] ", next_cursor":null
}

5. 2 plasterki/blaty (grupa-by)


GET/v1/analytics/slice
? metric = rtp & dim = gra _ id & od = 2025-10-22 & do = 2025-10-23
& limit = 50 & order = -value
→ 200 {"pozycje": [{"gra _ id':" g _ 01 "," wartość ": 0. 956},...] }

5. 3 Lejki


POST/v1/analytics/lejek
{
„kroki”: [
{"event ":" płatność. intent”}, {„event „:” płatność. autoryzowany”}, {„event „:” płatność. captured”}, {„event „:” portfel. kredyt „,” powód „:” depozyt'}
], „window_sec": 3600”, filtry „: {” region „:” UE „,” marka _ id': „marka-7”}
}
→ 200 {
„razem”: 12450, „kroki”: [
{„nazwa „:” 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 Limity i pamięć podręczna

Limit stawki na token/marka/region.

odpowiedzi "ETag 'to; Wsparcie dla If-None-Match.

Pamięć podręczna TTL zależy od ziarnistości (na przykład 5m → TTL 60-120 s).

6) Zatrzymanie i kohorty: zasady i API

6. 1 Definicje (konwencje)

DAU/WAU/MAU: aktywny, jeśli 'bet. umieszczony 'lub' portfel. sesja kredytowa (depozytowa) „ила”. rozpoczął się '≥ N minut.

Kohorta przez pierwszy depozyt (często dla LTV) lub przez rejestrację (do udziału).

D1/D7/D30 retencji: proporcja z kohorty powróciła do okna dziennego +/- tolerancja według strefy czasowej marki.

Rozważamy wielokrotne wizyty przez unikalny 'player _ id' w oknie.

6. 2 kohorty API


POST/v1/analityka/retencja
{
"kohorta": "first _ deposit", "start_date":"2025-09-01," end_date":"2025-09-30, "return_event":"bet. umieszczone „,” dni „: [1,7,14,30],” filtry „: {” region „:” UE „,” marka _ id': „marka-7”}
}
→ 200 {
„kohorta „: „first _ deposit”, „wiersze”: [
{„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/Cumulative


GET/v1/analytics/ltv? kohorta = first _ deposit & currency = EUR & horizon = 90d
→ 200 {„kohorty „: [{” data”:” 2025-09-01 „, „ltv _ minor „: [0,150,230,280,...]}}

7) Semantyka metryczna (bez argumentu)

Mierniki	Definicja (krótka)
GGR	suma (stawka) − suma (wygrana) zakład. rozliczane "w okresie/walucie
NGR	GGR − Koszty bonusowe − Składki na jackpot − Komisja
RTP	suma (wygrana )/suma (stawka)
Powodzenie depozytu	wychwytywane/zamierzone (współczynnik)
Rozliczenie opóźnienia	t (osiadły) − t (umieszczony), percentyl p95
Opóźnienie Webhook	t (spożyty) − t (wystąpił), p95
DAU/WAU/MAU	unikalnych aktywnych graczy według zasad aktywności

Wszystkie - w UTC z walutą i małymi jednostkami; wielokrotność jest rozwiązywana poprzez konwersję stałej FX do Data Lake.

8) Wersja, filtry i kompatybilność

Ścieżka: '/v1/... '; nowe metryki/pola - opcjonalnie.

Милстра: 'brand _ id, region, provider_id, game_id, metoda, waluta, urządzenie, geo'.

Paginacja: oparta na kursorze ('next _ cursor').

Łamanie → tylko '/v2 '+ Odrzucenie/Zachód słońca nagłówki i changelog.

9) Bezpieczeństwo i dostęp

OAuth2 poświadczenia klienta (tokeny krótkotrwałe), mTLS dla B2B.

RBAC/ABAC: uprawnienia metryczne/plasterkowe; Filtr RLS według „marki/regionu”.

PII: API nie podaje PII, w razie potrzeby tylko agregaty/pseudo-ID.

Miejsce zamieszkania: routing wniosków do regionu; dane międzyregionalne - niedozwolone.

limity stawek i kwoty, przeciwdziałanie nadużyciom; Audyt dostępu WORM.

10) SLO i obserwowalność

Wartości odniesienia SLO:

„GET/timeseries gran = 5m 'p95 ≤ 500-800 ms,” GET/slice' p95 ≤ 1-2 s (wierzchołki do 50-100 pozycji), „POST/retention” (miesiąc kohort) p95 ≤ 3-5 s, świeżość rollup: p95 ≤ 2-5 min od „occurred _ at”.
Metryki: opóźnienie p50/p95/p99, szybkość błędów (4xx/5xx), cache-hit, żądania/skanowanie bajtów (OLAP), świeżość opóźnienia dla każdego rollup'y.
Dzienniki: ustrukturyzowane, 'trace _ id', filtry zapytań (bez PII), liczba skanów.

11) Gotówka, wstępne obliczenia, koszt

Tabele Rollup: 1m/5m/1h/1d według kluczowych mierników → fast 'timeseries'.

Zmaterializowane widoki dla ciężkich sekcji/kohort.

ETag + maksymalny wiek; niepełnosprawność w późnych zdarzeniach występuje stopniowo.

Strategia „gorący/zimny”: gorące zapytania - w magazynie OLAP; archiwum - w jeziorze.

Ograniczenie „skanowania bajtów” na żądanie; Wskazówki dla grafika.

12) Wbudowane i eksportowane

Wbudowane widżety za pomocą podpisanego adresu URL/iFrame z tokenami RLS.

Eksport CSV/Parkiet według zadania (job API) z ograniczeniami wielkości i tymczasowymi odniesieniami.

Powiadomienia Webhook o gotowości przesyłania.

13) Listy kontrolne

Architektura

Ujednolicony schemat zdarzeń, semver, rejestr; dziadek przez 'event _ id'.
Poglądy Rollupa i zmaterializowane dla najlepszych przypadków.
RLS/RBAC/ABAC, rezydencja, tokeny krótkotrwałe.
Cache (ETag/TTL), limity stawek, kwoty.

Semantyka

Definicje GGR/NGR/RTP/DAU/retencji są udokumentowane.
Waluty - jednostki niewielkie; FX jest ustalany w czasie zdarzenia.
Zatrzymanie przez UTC, biorąc pod uwagę timezon marki na wyświetlaczu.

Operacje

Deski rozdzielcze SLO/świeżości i latencji.
Kontrola dostępu/wywozu WORM.
Ćwiczenia DR/xaoc: rollup lag, skurcz wniosków, późne zdarzenia.

14) Anty-wzory (czerwone flagi)

„Surowe” tabele OLTP są podane bezpośrednio do API.

Niespójne definicje metryczne między komendami.

Brak deduplikacji i znaków wodnych → podwójne/utracone zdarzenia.

Nieograniczone agregacje on-the-fly bez pamięci podręcznej/kwot → drogie i powolne wnioski.

Agregacja międzyregionalna bez polityki pobytu.

Zwróć dane PII/gracza do publicznych odpowiedzi.

Ciche zmiany bez '/v2'i deprecacji.

15) Mini-spec (TL; DR)

Zdarzenia: '/v1/events: batch '(co najmniej raz, dedup by' event _ id').

Timeseries: '/v1/analytics/timeseries? Metric =... & granularity =... '(rollup + ки).

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

Lejki: '/v1/analytics/lejek '(okno, kroki, filtry).

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

Bezpieczeństwo: OAuth2 + mTLS, RLS, na tokeny marki/regionu, audyt WORM.

SLO: p95 ≤ 0. 5-2 s; świeżość ≤ 2-5 min.

Statystyki i analityka API nie są „SELECT FROM”, big_table, ale kontrakt metryki: stabilne zdarzenia, wstępnie odczytane i buforowane agregaty, ściśle określone zatrzymywanie i kohorty, bezpieczeństwo (RLS/RBAC) i rezydencja zrozumiałe przez SLO. Dajesz więc dane szybko, tanio i przewidywalnie - partnerom, produktom i BI - bez kontrowersyjnych interpretacji i bez ryzyka wycieku lub przeciążenia magazynu.