Statistika we seljeriş API-leri: wakalar, agregatlar, retenşen

Makalanyň doly teksti

💡 18+. Platformalar/operatorlar, studiýalar (RGS/live) we BI/CRM toparlary üçin in engineeringenerçilik-seljeriş materialy. Oýnamaga çagyryş ýok.

1) Näme üçin daşarky API analitikleri

Hyzmatdaşlar/üpjün edijiler: SLA mazmunyna gözegçilik, RTP, gatnaşygy.

Marketing/CRM: metrik esasly trigger kampaniýalary (DAU, depozit hunisi).

Amallar/Maliýe: near-real-time GGR/NGR, tölegleriň üstünligi, webhuk laglary.

Önüm: in-app statistika widjetleri, A/B panelleri.

Maksat düşnükli semantika we SLA bilen wakalary we agregatlary howpsuz we öňünden aýdyp boljak görnüşde bermek.

2) Barmaklarda binagärlik


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)

Wakalar: at-least-once, dedup by 'event _ id/idempotency _ key'.

Agregatlar: hasapdan öňki rolruplar (1m/5m/1h/1d) + on-the-fly.

Retenshen: Gold Martyň üstündäki cohort hereketlendirijisi.

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

3) Wakalaryň modeli: iň pes standart

3. 1 Umumy meýdanlar

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

Düzgünler: UTC timestamps, 'player _ id' - lakam, pul minor units.

3. 2 Esasy görnüşleri

`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`
Wersiýa - semver; diňe optional.

4) Ingestion API (üçünji tarap çeşmeleri üçin)

Bir topar wakany ibermek


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

Kepillikler: at-least-once; dublikatlar 'event _ id' boýunça Silver-a süzülýär.

5) Aggregation API: time-series we dilimler

5. 1 Wagt seriýasy (wagt metrikleri)


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ölekler/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 Huniler (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 Çäkler we nagt pul

Rate limit per token/brand/region.

Jogaplara 'ETag'; goldaw 'If-None-Match'.

TTL keşi 'granularity' -e baglydyr (mysal üçin 5m → TTL 60-120 s).

6) Retenşen we kogortlar: düzgünler we API

6. 1 Kesgitnamalar (konwensiýalar)

DAU/WAU/MAU: bet bar bolsa işjeň. placed 'ýa-da' wallet. credit (deposit)` или `session. started '≥ N minut.

Cohort by first deposit (köplenç LTV üçin) ýa-da by registration (gatnaşmak üçin).

Retention D1/D7/D30: kogortanyň paýy günüň penjiresine gaýdyp geldi +/- markanyň wagt zolagy boýunça giriş.

Gaýtalanýan saparlary penjirede özboluşly 'player _ id' boýunça hasaplaýarys.

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/jemleýji


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

7) Metrikleriň semantikasy (jedel etmezlik üçin)

Metrika	Kesgitleme (gysgaça)
GGR	sum(stake) − sum(win) по `bet. settled 'periodda/walýutada
NGR	GGR − bonus çykdajylary − jekpot tölegleri − komissiýasy
RTP	sum(win) / sum(stake)
Deposit success	captured/intent
Settle lag	t (settled) − t (placed), persentil p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	işjeňlik düzgünleri boýunça özboluşly işjeň oýunçylar

Hemme zat - walýuta we minor units görkezilen UTC-de; köp walýuta hasaba alnan FX-ni Data Lake-e öwürmek arkaly çözülýär.

8) Wersiýa, süzgüçler we gabat gelmek

Ýol: '/v1/... '; täze metrler/meýdanlar - optional.

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

Paginasiýa: cursor-based ('next _ cursor').

Breaking → diňe '/v2 '+ Deprecation/Sunset sözbaşylary we changelog.

9) Howpsuzlyk we elýeterlilik

OAuth2 Client Credentials, B2B üçin mTLS.

RBAC/ABAC: metrikler/bölekler üçin rugsatlar; RLS süzgüç 'brand/region'.

PII: API PII bermeýär, diňe zerur bolan agregatlar/psevdo-ID.

Rezidentlik: sebite haýyşlary ugrukdyrmak; kross-sebit maglumatlary - gadagan.

Rate limits we kwotalar, hyýanatçylyga garşy; WORM-giriş barlagy.

10) SLO we synlamak

SLO görkezmeleri:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (toplar 50-100 pozisiýa çenli), 'POST/retention' (aý kogorty) p95 ≤ 3-5 s, rollup täzeligi: p95 ≤ 2-5 min -dan 'occurred _ at'.
Metrikler: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, soraglar/skan-baýtlar (OLAP), her rollup 'y boýunça "freshness lag".
Loglar: gurluş, 'trace _ id', süzgüçler (PII-siz), skanlar hasaby.

11) Nagt pul, deslapky hasaplaşyklar, bahasy

Rollub-tablisalar: 1m/5m/1h/1d açar metrleri boýunça → çalt 'timeseries'.

Materialized views/kohort.

ETag + max-age; giç hadysalarda maýyplyk inkremental bolup geçýär.

"Hot/cold" strategiýasy: gyzgyn soraglar - OLAP-warehouse; arhiw - Lake.

Soraga "skan-baýtlary" çäklendirmek; meýilnamalaşdyryja maslahatlar.

12) Ýerleşdirmek (embedded) we eksport

RLS bellikleri bilen signed URL/iFrame arkaly gurlan widjetler.

CSV/Parquet meselelerini (job API) ululyk çäklendirmeleri we wagt baglanyşyklary bilen eksport ediň.

Webhook-çykarmaga taýynlyk bildirişleri.

13) Çek-listler

Arhitektura

Wakalaryň ýeke-täk shemasy, semver, registry; 'event _ id'.
Rollup 'y we materialized views iň ýokary ýagdaýlara.
RLS/RBAC/ABAC, rezidentlik, gysga ömürli bellikler.
Nagt pul (ETag/TTL), rate limits, kwotalar.

Semantika

GGR/NGR/RTP/DAU/retention kesgitlemeleri resminamalaşdyryldy.
Walýutalar - minor units; FX waka bolan pursatda ýazylýar.
UTC Retention, ekranda brend wagtyny göz öňünde tutýar.

Amallar

SLO/täzelik we gizlinlik dashbordlary.
WORM-giriş/eksport barlagy.
DR/xaoc-maşklar: rollup yza galmak, soraglaryň köpelmegi, gijä galan wakalar.

14) Anti-pattern (gyzyl baýdaklar)

"Çig" ALTP-tablisalar göni API-e berilýär.

Toparlaryň arasyndaky metrikleriň utgaşdyrylmadyk kesgitlemeleri.

Atanyň ýoklugy we watermarks → goşa/ýitirilen wakalar.

Keş/kwota bolmazdan çäksiz on-the-fly agregasiýalar → gymmat we haýal soraglar.

Rezidentlik syýasaty bolmazdan kross-sebit agregasiýasy.

PII/oýunçynyň jikme-jikliklerini köpçüligiň jogabyna gaýtarmak.

Sessiz breaking-changes '/v2 'we Deprecation.

15) Mini-speka (TL; DR)

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

Wagt seriýasy: '/v1/analytics/timeseries? metric=...&granularity=...` (rollup + кэш).

Dilimler: '/v1/analytics/slice? metric=...&dim=...`.

Huniler: '/v1/analytics/funnel '(penjire, ädimler, süzgüçler).

Retenşen/kohortlar: '/v1/analytics/retention '(+ LTV).

Howpsuzlyk: OAuth2 + mTLS, RLS, per brand/region, WORM-audit bellikleri.

SLO: p95 ≤ 0. 5-2 s; täzelik ≤ 2-5 minut.

Statistika we analitikleriň API-leri "SELECT FROM big_table" däl-de, eýsem metrik şertnama: durnukly wakalar, öňünden hasaplanan we kesilen agregatlar, berk kesgitlenen retenşen we kogortlar, howpsuzlyk (RLS/RBAC) we SLO-lara düşnükli rezidentlik. Şeýlelik bilen, siz maglumatlary çalt, arzan we öňünden aýdyp boljak - hyzmatdaşlara, önüme we BI - jedelli düşündirişler bolmazdan we ammar syzmak ýa-da artykmaç ýüklemek howpy bolmazdan berýärsiňiz.