Статистика және талдаудың API: оқиғалар, агрегаттар, ретеншен

Мақаланың толық мәтіні

💡 18+. Платформалар/операторлар, студиялар (RGS/live) және BI/CRM командалары үшін инженерлік-талдамалық материал. Ойынға шақыру емес.

1) Неге сыртқы API талдаулар

Серіктестер/провайдерлер: SLA контент мониторингі, RTP, қатысу.

Маркетинг/CRM: метрика базасындағы триггерлік науқандар (DAU, депозиттік құйғыш).

Операциялар/қаржы: near-real-time GGR/NGR, төлемдердің табысы, веб-хук лагтары.

Өнім: in-app статистика виджеттері, A/B панельдері.

Мақсаты - түсінікті семантикасы мен SLA бар оқиғалар мен агрегаттарды қауіпсіз және болжамды беру.

2) Саусақтардағы сәулет


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)

Оқиғалар: at-least-once, дедуп бойынша 'event _ id/idempotency _ key'.

Агрегаттар: алдын ала есептелген rollub's (1m/5m/1h/1d) + on-the-fly.

Ретеншен: Gold-наурыз үстіндегі cohort-қозғалтқыш.

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

3) Оқиғалар моделі: ең төменгі стандарт

3. 1 Ортақ өрістер

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

Ережелер: UTC timestamps, 'player _ id' - бүркеншік аты, minor units-тағы ақша.

3. 2 Негізгі түрлері

`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`
Нұсқалау - semver; тек optional қосу.

4) Ingestion API (бөгде көздер үшін)

Оқиғалар бумасын жіберу


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

Кепілдіктер: at-least-once; көшірмелер Silver бағдарламасында 'event _ id' бойынша сүзіледі.

5) Aggregation API: time-series және кесінділер

5. 1 Таймсериялар (уақыт өлшемдері)


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 Кесінділер/топтар (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 Құйғыштар (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 Лимиттер мен кэш

Rate limit per token/brand/region.

жауаптарға 'ETag'; қолдау 'If-None-Match'.

TTL кэші 'granularity' байланысты (мысалы, 5m → TTL 60-120 s).

6) Ретеншен және когорттар: ережелер және API

6. 1 Анықтамалар (конвенциялар)

DAU/WAU/MAU: 'bet' болса белсенді. placed 'немесе' wallet. credit (deposit)` или `session. started '≥ N минут.

Cohort by first deposit (көбінесе LTV үшін) немесе by registration (тарту үшін).

Retention D1/D7/D30: когортаның үлесі күн терезесіне +/- брендтің тайм-аймағы бойынша рұқсатқа оралды.

Қайталап келуді терезедегі бірегей 'player _ id' бойынша санаймыз.

6. 2 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/жиынтық


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

7) Метрика семантикасы (таласпау үшін)

Метрика	Анықтама (қысқаша)
GGR	sum(stake) − sum(win) по `bet. кезеңдегі/валютадағы settled '
NGR	GGR − бонустық шығыстар − джекпот жарналары − комиссия
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (коэффициент)
Settle lag	t (settled) − t (placed), перцентиль p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	белсенділік ережелері бойынша бірегей белсенді ойыншылар

Барлығы - валюта және minor units көрсетілген UTC-де; мультивалюталылық тіркелген FX бойынша Data Lake-ке айырбастау арқылы шешіледі.

8) Нұсқасы, сүзгілер және үйлесімділік

Жол: '/v1/... '; жаңа метриктер/өрістер - optional.

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

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

Breaking → тек '/v2 '+ Deprecation/Sunset тақырыптары және changelog.

9) Қауіпсіздік және қол жетімділік

OAuth2 Client Credentials (қысқа мерзімді токендер), B2B үшін mTLS.

RBAC/ABAC: өлшемдерге/кесіктерге рұқсаттар; 'brand/region' бойынша RLS сүзгісі.

PII: API PII бермейді, қажет болған жағдайда тек агрегаттар/псевдо-ID.

Резиденттілік: өңірге сұрау салуларды бағыттау; кросс-өңірлік деректер - тыйым салынады.

Rate limits және квоталар, анти-абьюз; WORM-қатынау аудиті.

10) SLO және бақылау

SLO бағдарлары:

'GET/timeseries gran = 5m' p95 ≤ 500-800 мс, 'GET/slice' p95 ≤ 1-2 с (топтар 50-100 позицияға дейін), 'POST/retention' (ай когорт) p95 ≤ 3-5 с, жас ролуб 'ов: p95 ≤ 2-5 мин' occurred _ at '.
Метриктер: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, сұраулар/скан-байттар (OLAP), әрбір rollup 'y бойынша «freshness lag».
Логтар: құрылымдалған, 'trace _ id', сұрау сүзгілері (PII), сканер шоты.

11) Кэш, алдын ала есеп айырысу, құны

Rollub-кестелер: 1m/5m/1h/1d кілт өлшемдері бойынша → жылдам 'timeseries'.

Ауыр қималар/кохорт үшін Materialized views.

ETag + max-age; кейінгі оқиғалар кезінде мүгедектік инкрементальды болады.

«Hot/cold» стратегиясы: ыстық сұраулар - OLAP-warehouse; мұрағат - Lake.

Сұрау салуға «скан-байттарды» шектеу; жоспарлаушыға көмек.

12) Кірістіру (embedded) және экспорт

RLS-токендері бар signed URL/iFrame арқылы орнатылған виджеттер.

CSV/Parquet тапсырмаларын (job API) өлшем шектеулерімен және уақыт сілтемелерімен экспорттау.

Түсіру дайындығы туралы Webhook хабарламалары.

13) Чек парақтары

Сәулет

Оқиғалардың бірыңғай схемасы, semver, registry; 'event _ id' дедупы.
Rollup's және materialized views топ-кейстерге.
RLS/RBAC/ABAC, резиденттік, қысқа мерзімді токендер.
Кэш (ETag/TTL), rate limits, квоталар.

Семантика

GGR/NGR/RTP/DAU/retention анықтамалары құжатталған.
Валюталар - minor units; FX оқиға кезінде тіркеледі.
Көрсетілімдегі бренд-таймзонды ескере отырып, UTC бойынша Retention.

Операциялар

Жас және жасырын SLO/дашборд.
WORM-қатынас/экспорт аудиті.
DR/xaoc-жаттығулар: rollup артта қалуы, сұраулар шоғыры, кешігіп қалған оқиғалар.

14) Қарсы үлгілер (қызыл жалаулар)

«Шикі» OLTP-кестелер тікелей API-ге беріледі.

Командалар арасындағы метрикалардың келісілмеген анықтамалары.

Дедуптың жоқтығы және watermarks → қос/жоғалған оқиғалар.

Кэшсіз/квотасыз лимитсіз on-the-fly агрегациялары → қымбат және баяу сұраулар.

Резиденттік саясатынсыз кросс-өңірлік агрегация.

Ойыншының PII/бөлшектерін көпшілік жауаптарға қайтару.

'/v2 'және Deprecation жоқ тыныш breaking-changes.

15) Шағын спека (TL; DR)

Оқиғалар: '/v1/events: batch '(at-least-once, дедуп бойынша' event _ id ').

Таймсериялар: '/v1/analytics/timeseries? metric=...&granularity=...` (rollup + кэш).

Қималар: '/v1/analytics/slice? metric=...&dim=...`.

Құйғыштар: '/v1/analytics/funnel '(терезе, қадамдар, сүзгілер).

Ретеншен/кохорттар: '/v1/analytics/retention '(+ LTV).

Қауіпсіздік: OAuth2 + mTLS, RLS, per brand/region, WORM-аудит.

SLO: p95 ≤ 0. 5-2 с; ашықтығы ≤ 2-5 мин.

Статистика мен талдаудың API - бұл "SELECT FROM big_table" емес, ал келісімшарт метрикалық: тұрақты оқиғалар, алдын ала есептелген және кэшталған агрегаттар, қатаң белгіленген ретеншен және когорттар, қауіпсіздік (RLS/RBAC) және SLO-ға түсінікті резиденттік. Осылайша, сіз деректерді тез, арзан және болжамды түрде - серіктестерге, өнімге және BI - даулы түсіндірулерсіз және қойманың ағып кету немесе артық жүктелу қаупі жоқ.