Statistika va tahlillar API: voqealar, agregatlar, retenshen

Maqolaning to’liq matni

💡 18+. Platformalar/operatorlar, studiyalar (RGS/live) va BI/CRM jamoalari uchun muhandislik-tahliliy material. O’yinga chaqirish emas.

1) Nima uchun tashqi API tahlillari

Hamkorlar/provayderlar: SLA kontent monitoringi, RTP, jalb qilish.

Marketing/CRM: metrik trigger kampaniyalari (DAU, depozit hunisi).

Operatsiyalar/moliya: near-real-time GGR/NGR, to’lovlar muvaffaqiyati, vebxuk laglari.

Mahsulot: in-app statistika vidjetlari, A/B panellari.

Maqsad - tushunarli semantika va SLA bilan hodisalar va agregatlarni xavfsiz va oldindan aytib bo’ladigan tarzda berish.

2) Barmoqlardagi arxitektura


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)

Voqealar: at-least-once, dedup’event _ id/idempotency _ key’.

Agregatlar: hisoblashdan oldingi rolruplar (1m/5m/1h/1d) + on-the-fly.

Retenshen: Gold-mart ustidagi cohort-dvigatel.

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

3) Voqealar modeli: minimal standart

3. 1 Umumiy maydonlar

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

Qoidalar: UTC timestamps,’player _ id’- taxallusi, pul minor units.

3. 2 Asosiy turlari

`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`
Version - semver; faqat optional qoʻshish.

4) Ingestion API (uchinchi tomon manbalari uchun)

Voqealarni joʻnatish


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

Kafolatlar: at-least-once; dublikatlar’event _ id’bo’yicha Silver filtrlanadi.

5) Aggregation API: time-series va kesmalar

5. 1 Taymseriya (vaqt boʻyicha metrika)


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 Kesmalar/toplar (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 Huni (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 Limitlar va kesh

Rate limit per token/brand/region.

«ETag» ga javoblar; ’If-None-Match’ ni qo’llab-quvvatlash.

TTL keshi’granularity’ga bog’liq (masalan, 5m → TTL 60-120 s).

6) Retenshen va kogortlar: qoidalar va API

6. 1 Ta’riflar (konvensiyalar)

DAU/WAU/MAU: Agar’bet’boʻlsa aktiv. placed’yoki’wallet. credit (deposit)` или `session. started’≥ N daqiqa.

Cohort by first deposit (ko’pincha LTV uchun) yoki by registration (jalb qilish uchun).

Retention D1/D7/D30: kogortaning ulushi kunning oynasiga qaytdi +/- brendning taym-zonasiga kirish.

Takroriy tashriflarni oynadagi noyob’player _ id’bilan hisoblaymiz.

6. 2 API kogortalar


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/kumulyativ


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

7) Metriklarning semantikasi (bahslashmaslik uchun)

Metrika	Taʼrif (qisqacha)
GGR	sum(stake) − sum(win) по `bet. davrdagi/valyutadagi settled ’
NGR	GGR − bonus xarajatlari − − komissiyasining jekpot badallari
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (koeffitsiyent)
Settle lag	t (settled) − t (placed), persentil p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	faollik qoidalari bo’yicha noyob faol o’yinchilar

Hammasi - valyuta va minor units ko’rsatilgan holda UTCda; multivalyutalik qayd etilgan FX bo’yicha Data Lake ga konvertatsiya qilish orqali hal qilinadi.

8) Versiya, filtrlar va muvofiqlik

Yoʻl: ’/v1/...’; yangi metriklar/maydonlar - optional.

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

Paginatsiya: cursor-based (’next _ cursor’).

Breaking → faqat ’/v2’+ Deprecation/Sunset sarlavhalari va changelog.

9) Xavfsizlik va foydalanish

OAuth2 Client Credentials (qisqa yashovchi tokenlar), B2B uchun mTLS.

RBAC/ABAC: metrik/kesish uchun ruxsatnomalar; ’brand/region’ uchun RLS filteri.

PII: API PII bermaydi, faqat agregatlar/psevdo-ID kerak bo’lganda.

Rezidentlik: hududga so’rovlarni yo’naltirish; kross-mintaqaviy ma’lumotlar - taqiqlangan.

Rate limits va kvotalar, anti-abyuz; WORM-kirish auditi.

10) SLO va kuzatish

SLO koʻrsatkichlari:

’GET/timeseries gran = 5m’ p95 ≤ 500-800 ms,’GET/slice’p95 ≤ 1-2 s (50-100 pozitsiyagacha bo’lgan guruhlar),’POST/retention’(oy kogortasi) p95 ≤ 3-5 s, rolup’larning yangiligi: p95 ≤ 2-5 min’occurred’dan _ at’.
Metriklar: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, so’rovlar/skan-baytlar (OLAP), har bir rollup’y bo’yicha «freshness lag».
Loglar: strukturalangan,’trace _ id’, soʻrov filterlari (PIIsiz), skanlar hisobi.

11) Kesh, dastlabki hisob-kitoblar, qiymati

Rollub-jadvallar: 1m/5m/1h/1d asosiy metriklar bo’yicha → tezkor’timeseries’.

Materialized views uchun ogʻir kesmalar/kohort.

ETag + max-age; kech hodisalarda nogironlik inkremental tarzda sodir bo’ladi.

«hot/cold» strategiyasi: issiq so’rovlar - OLAP-warehouse; arxiv - Lake.

So’rov uchun «skan-baytlar» ni cheklash; rejalashtiruvchiga ko’rsatmalar.

12) Integratsiya (embedded) va eksport

RLS tokenlari bilan signed URL/iFrame orqali oʻrnatilgan vidjetlar.

Vazifalar boʻyicha CSV/Parquet eksport qilish (job API)

Yuklashga tayyorligi haqida Webhook xabarnomalari.

13) Chek-varaqlar

Arxitektura

Yagona voqealar sxemasi, semver, registry; dedup’event _ id’.
Rollup’lar va materialized views ostida top-keys.
RLS/RBAC/ABAC, rezidentlik, qisqa jonli tokenlar.
Kesh (ETag/TTL), rate limits, kvotalar.

Semantika

GGR/NGR/RTP/DAU/retention taʼriflari hujjatlashtirilgan.
Valyutalar - minor units; FX hodisa paytida qayd etiladi.
Retention UTC bo’yicha brend taymzonini hisobga olgan holda.

Operatsiyalar

SLO/yangilik va yashirin dashbordlar.
Kirish/eksport WORM auditi.
DR/xaoc-mashqlar: rollup orqada qolish, so’rovlar ko’tarilishi, kechiktirilgan voqealar.

14) Anti-patternlar (qizil bayroqlar)

«Xom» OLTP jadvallari to’g «ridan to’g» ri APIga beriladi.

Jamoalar o’rtasidagi metrikalarning kelishilmagan ta’riflari.

Dedupning yo’qligi va watermarks → ikki marta/yo’qotilgan voqealar.

Kesh/kvotasiz limitsiz on-the-fly agregatsiyalar → qimmat va sekin so’rovlar.

Rezidentlik siyosatisiz kross-mintaqaviy agregatsiya.

O’yinchining PII/tafsilotlarini ommaviy javoblarga qaytarish.

Jim breaking-changes ’/v2’va Deprecation.

15) Mini-speka (TL; DR)

Hodisalar: ’/v1/events: batch’(at-least-once, dedup’event _ id’).

Taym seriyasi: ’/v1/analytics/timeseries? metric=...&granularity=...` (rollup + кэш).

Kesmalar: ’/v1/analytics/slice? metric=...&dim=...`.

Hunilar: ’/v1/analytics/funnel’(oyna, qadamlar, filtrlar).

Retenshen/kohortlar: ’/v1/analytics/retention’(+ LTV).

Xavfsizlik: OAuth2 + mTLS, RLS, per brand/region tokenlari, WORM-audit.

SLO: p95 ≤ 0. 5-2 s; yangiligi ≤ 2-5 daqiqa.

API statistikasi va tahlillari "SELECT FROM big_table" emas, balki kontrakt metriklari: barqaror voqealar, oldindan hisoblab chiqilgan va keshlangan agregatlar, qat’iy belgilangan retenshen va kogortlar, xavfsizlik (RLS/RBAC) va SLO tushunarli rezidentlik. Shunday qilib, siz ma’lumotlarni tezda, arzon va oldindan aytib bo’ladigan tarzda berasiz - sheriklar, mahsulot va BI - bahssiz va omborning chiqib ketishi yoki ortiqcha yuklanishi xavfi yo’q.