API статистика жана аналитика: окуялар, агрегаттар, retenshen

Макаланын толук тексти

💡 18+. Платформалар/операторлор, студиялар (RGS/live) жана BI/CRM командалары үчүн инженердик-аналитикалык материал. оюнга чакыруу эмес.

1) Эмне үчүн тышкы API аналитика

Өнөктөштөр/провайдерлер: SLA мазмунуна мониторинг жүргүзүү, RTP, тартуу.

Маркетинг/CRM: Метрикага негизделген триггер кампаниялары (DAU, депозиттик воронка).

Операциялар/финансы: near-real-time GGR/NGR, төлөмдөрдүн ийгилиги, веб-хук лагдары.

Продукт: in-app widget статистика, 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.

Retenshen: Алтын-март үстүнөн 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: убакыт сериясы жана кесилген

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) Retenshen жана Cogorts: эрежелери жана 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; көп акча Data Lake белгиленген FX которуу менен чечилет.

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: метрика/кесүү үчүн уруксат; RLS чыпкасы 'brand/region'.

PII: API PII бербейт, керек болсо гана агрегаттар/psevdo 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 мин from 'occurred _ ат'.
Метриктер: latency p50/p95/p99, error-rate (4xx/5xx), cache-хит, суроолор/сканер-байттар (OLAP), ар бир rollub 'y үчүн "freshness lag".
Логи: структураланган, 'trace _ id', сурам чыпкалары (PII жок), сканер эсеби.

11) Кэш, алдын ала эсептешүүлөр, наркы

Rollub-таблицалар: 1m/5m/1h/1d негизги көрсөткүчтөр боюнча → тез 'timeseries'.

Materialized views үчүн оор кесип/кохорт.

ETag + max-age; кийинки окуяларда майып болуу инкременталдуу болот.

"Hot/cold" стратегиясы: ысык суроолор - жылы OLAP-сактоо; архив - Lake.

Суроо-талапка "сканер-байттарды" чектөө; пландаштыруучуга.

12) киргизүү (embedded) жана экспорт

RLS-белгилер менен URL/iFrame белгиси аркылуу орнотулган виджеттер.

CSV/Parquet милдеттерди экспорттоо (job API) өлчөмдөрү жана убактылуу шилтемелер менен.

жүктөө даяр Webhook-эскертмелер.

13) Чек-баракчалар

Архитектура

окуялардын бирдиктүү схемасы, semver, каттоо; дедуп 'event _ id'.
Rollup's жана Top Cases боюнча 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) Mini Specy (TL; DR)

Окуялар: '/v1/events: batch '(at-least-once, дедуп' event _ id ').

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

Тилкелер: '/v1/analytics/slice? metric=...&dim=...`.

Воронкалар: '/v1/analytics/funnel '(терезе, кадамдар, чыпкалар).

Retenshen/кохорттор: '/v1/analytics/retention '(+ LTV).

Коопсуздук: OAuth2 + mTLS, RLS, токендер per brand/аймак, WORM аудит.

SLO: p95 ≤ 0. 5-2 с; сергектик ≤ 2-5 мүнөт.

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