Torrent Gear

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'.

Агрегати: передрозрахункові rollup'и (1m/5m/1h/1d) + on-the-fly.

Ретеншен: cohort-рушій поверх Gold-мартів.

Кеш: 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	унікальні активні гравці за правилами активності

Всі - в UTC із зазначенням валюти і minor units; мультивалютність вирішується конвертацією по зафіксованим FX в Data Lake.

8) Версія, фільтри та сумісність

Шлях: `/v1/...`; нові метрики/поля - optional.

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

Пагінація: cursor-based (`next_cursor`).

Breaking → тільки '/v2'+ Deprecation/Sunset заголовки і changelog.

9) Безпека та доступ

OAuth2 Client Credentials (короткоживучі токени), mTLS для B2B.

RBAC/ABAC: дозволу на метрики/зрізи; фільтр RLS по'brand/region'.

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 с, свіжість rollup'ів: p95 ≤ 2-5 хв від'occurred _ at'.
Метрики: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, запити/скан-байти (OLAP), «freshness lag» по кожному rollup'y.
Логи: структуровані, «trace _ id», фільтри запиту (без PII), рахунок сканів.

11) Кеш, попередні розрахунки, вартість

Rollup-таблиці: 1m/5m/1h/1d за ключовими метриками → швидкі'timeseries'.

Materialized views для важких зрізів/кохорт.

ETag + max-age; інвалідація при пізніх подіях відбувається інкрементально.

Стратегія «hot/cold»: гарячі запити - в OLAP-warehouse; архів - в Lake.

Обмеження «скан-байтів» на запит; підказки планувальнику.

12) Вбудовування (embedded) та експорт

Вбудовані віджети через signed URL/iFrame з RLS-токенами.

Експорт CSV/Parquet за завданнями (job API) з обмеженнями розміру і тимчасовими посиланнями.

Webhook-повідомлення про готовність вивантаження.

13) Чек-листи

Архітектура

Єдина схема подій, semver, registry; дедуп по'event _ id'.
Rollup'и і materialized views під топ-кейси.
RLS/RBAC/ABAC, резидентність, токени короткоживучі.
Кеш (ETag/TTL), rate limits, квоти.

Семантика

Визначення GGR/NGR/RTP/DAU/retention задокументовані.
Валюти - minor units; FX фіксується на момент події.
Retention по UTC з урахуванням бренд-таймзони у відображенні.

Операції

SLO/дашборди свіжості та латентності.
WORM-аудит доступів/експортів.
DR/xaoc-навчання: відставання rollup, шквал запитів, що запізнилися.

14) Анти-патерни (червоні прапори)

«Сирі» OLTP-таблиці віддаються прямо в API.

Неузгоджені визначення метрик між командами.

Відсутність дедупа і watermarks → подвійні/втрачені події.

Безлімітні on-the-fly агрегації без кеша/квот → дорогі і повільні запити.

Крос-регіонна агрегація без політики резидентності.

Повернення PII/деталей гравця в публічні відповіді.

Тихі breaking-changes без '/v2'і Deprecation.

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'( вікно, кроки, фільтри).

Ретеншен/коhortи: `/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 - без спірних трактувань і без ризику витоку або перевантаження сховища.