API statistika və analitiklər: hadisələr, aqreqatlar, retenshen

Məqalənin tam mətni

💡 18+. Platformalar/operatorlar, studiyalar (RGS/live) və BI/CRM komandaları üçün mühəndis-analitik material. Oyuna çağırış deyil.

1) Niyə xarici API analitikləri

Partnyorlar/provayderlər: SLA content monitorinqi, RTP, cəlb.

Marketinq/CRM: metrik əsaslı trigger kampaniyaları (DAU, depozit hunisi).

Əməliyyatlar/maliyyə: near-real-time GGR/NGR, ödənişlərin müvəffəqiyyəti, vebhuk laqları.

Məhsul: in-app statistika widget, A/B panelləri.

Məqsəd aydın semantika və SLA ilə hadisələri və aqreqatları təhlükəsiz və proqnozlaşdırıla bilən şəkildə verməkdir.

2) Barmaqlarda memarlıq


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)

Hadisələr: at-least-once, dedup by 'event _ id/idempotency _ key'.

Aqreqatlar: əvvəlcədən hesablanmış rolruplar (1m/5m/1h/1d) + on-the-fly.

Retenshen: Gold Mart üzərində cohort mühərriki.

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

3) Hadisə modeli: minimum standart

3. 1 Ümumi sahələr

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

Qaydalar: UTC timestamps, 'player _ id' - təxəllüs, minor units pul.

3. 2 Əsas növləri

`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; yalnız optional əlavə.

4) Ingestion API (üçüncü tərəf mənbələri üçün)

Bir paket hadisə göndərilməsi


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

Zəmanət: at-least-once; dublikatlar Silver-da 'event _ id' ilə süzülür.

5) Aggregation API: time-series və kəsiklər

5. 1 Time Series (vaxt göstəriciləri)


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 Bölmə/Top (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 Limitlər və Cache

Rate limit per token/brand/region.

'ETag' cavabları; dəstək 'If-None-Match'.

TTL cache 'granularity' asılıdır (məsələn, 5m → TTL 60-120 s).

6) Retenshen və kohorts: qaydaları və API

6. 1 Təriflər (konvensiyalar)

DAU/WAU/MAU: 'bet' varsa aktiv. placed 'və ya' wallet. credit (deposit)` или `session. started '≥ N dəqiqə.

Cohort by first deposit (çox vaxt LTV üçün) və ya by registration (cəlb üçün).

Retention D1/D7/D30: koqortanın payı günün pəncərəsinə qayıtdı +/- brendin vaxt zonasına daxil olmaq.

Təkrar səfərləri pəncərədə unikal 'player _ id' hesab edirik.

6. 2 API kohortlar


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/məcmu


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

7) Metrik semantika (mübahisə etməmək üçün)

Metrika	Tərif (qısa)
GGR	sum(stake) − sum(win) по `bet. settled 'dövrü/valyutada
NGR	GGR − bonus xərcləri − cekpot haqları − komissiya
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (əmsal)
Settle lag	t (settled) − t (placed), persentil p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	fəaliyyət qaydalarına görə unikal aktiv oyunçular

Hamısı - valyuta və minor units ilə UTC; multivalyutası Data Lake sabit FX konvertasiyası ilə həll edilir.

8) Versiyası, filtrlər və uyğunluq

Yol: '/v1/... '; yeni metriklər/sahələr - optional.

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

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

Breaking → yalnız '/v2 '+ Deprecation/Sunset başlıqları və changelog.

9) Təhlükəsizlik və giriş

OAuth2 Client Credentials, B2B üçün mTLS.

RBAC/ABAC: metrik/kəsik icazələri; 'brand/region' tərəfindən RLS filter.

PII: API PII vermir, yalnız lazım olduqda aqreqatlar/psevdo-ID.

Rezidentlik: regiona sorğuların marşrutlaşdırılması; kross-regional məlumatlar - qadağandır.

Rate limits və kvotalar, anti-sui-istifadə; WORM-giriş auditi.

10) SLO və müşahidə

SLO göstərişlər:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (top 50-100 mövqe qədər), 'POST/retention' (ay kohort) p95 ≤ 3-5 s, təzə rolup's: p95 ≤ 2-5 dəq 'occurred _ at'.
Metriklər: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, sorğular/skan-baytlar (OLAP), hər rollup 'y üçün «freshness lag».
Log: strukturlaşdırılmış, 'trace _ id', sorğu filtrləri (PII olmadan), skan hesabı.

11) Cash, əvvəlcədən hesablaşmalar, dəyəri

Rollub cədvəllər: 1m/5m/1h/1d açar metrik → sürətli 'timeseries'.

Materialized views ağır kəsiklər/kohort üçün.

ETag + max-age; gec hadisələr zamanı əlillik inkrementaldır.

«Hot/cold» strategiyası: isti sorğular - OLAP-warehouse; arxiv - Lake.

Sorğu üçün «skan-baytların» məhdudlaşdırılması; planlayıcıya məsləhətlər.

12) Gömrük (embedded) və ixrac

RLS işarəli URL/iFrame vasitəsilə daxili widget.

CSV/Parquet tapşırıqları ixrac (job API) ölçü məhdudiyyətləri və vaxt linkləri ilə.

Download hazır Webhook bildirişlər.

13) Çek vərəqləri

Memarlıq

Vahid hadisə sxemi, semver, registry; dedup 'event _ id'.
Rollup 's və top cases altında materialized views.
RLS/RBAC/ABAC, rezidentlik, qısa tokenlər.
Cash (ETag/TTL), rate limits, kvotalar.

Semantika

GGR/NGR/RTP/DAU/retention tərifləri sənədləşdirilmişdir.
Valyutalar - minor units; FX hadisə zamanı qeyd olunur.
Retention UTC ekran marka-taymzon nəzərə alaraq.

Əməliyyatlar

SLO/təravət və gizlilik daşbordları.
WORM-audit giriş/ixrac.
DR/xaoc-təlimlər: rollup gecikməsi, sorğular, gecikmiş hadisələr.

14) Anti-nümunələr (qırmızı bayraqlar)

«Xam» OLTP cədvəlləri birbaşa API-yə verilir.

Komandalar arasında razılaşdırılmamış metrik təriflər.

No deadup və watermarks → cüt/itirilmiş hadisələr.

Cache/kvota olmadan limitsiz on-the-fly aqreqasiya → bahalı və yavaş sorğular.

Rezidentlik siyasəti olmadan kross-regional aqreqasiya.

PII/oyunçu detallarının ictimai cavablara qaytarılması.

'/v2 'və Deprecation olmadan sakit breaking-changes.

15) Mini speka (TL; DR)

Hadisələr: '/v1/events: batch '(at-least-once, dedup by' event _ id ').

Time Series: '/v1/analytics/timeseries? metric=...&granularity=...` (rollup + кэш).

Dilimlər: '/v1/analytics/slice? metric=...&dim=...`.

Hunilər: '/v1/analytics/funnel '(pəncərə, addımlar, filtrlər).

Retenshen/kohorts: '/v1/analytics/retention '(+ LTV).

Təhlükəsizlik: OAuth2 + mTLS, RLS, per brand/region tokenləri, WORM auditi.

SLO: p95 ≤ 0. 5-2 s; təravət ≤ 2-5 dəqiqə.

Statistika və analitiklərin API-ləri "SELECT FROM big_table" deyil, metrik müqavilədir: sabit hadisələr, əvvəlcədən hesablanmış və keşləşdirilmiş aqreqatlar, ciddi şəkildə müəyyən edilmiş retenşen və koqortlar, təhlükəsizlik (RLS/RBAC) və SLO-nun başa düşülən rezidentliyi. Beləliklə, siz məlumatları tez, ucuz və proqnozlaşdırıla bilən şəkildə - tərəfdaşlara, məhsula və BI-yə - mübahisəli şərhlər olmadan və anbarın sızması və ya həddindən artıq yüklənməsi riski olmadan verirsiniz.