API სტატისტიკა და ანალიტიკოსები: მოვლენები, აგრეგატები, რეტენჩენი

სტატიის სრული ტექსტი

💡 18+. საინჟინრო და ანალიტიკური მასალა პლატფორმების/ოპერატორებისთვის, სტუდიებისთვის (RGS/live) და BI/CRM გუნდებისთვის. არა თამაშის მოწოდება.

1) რატომ არის გარე API ანალიტიკოსები

პარტნიორები/პროვაიდერები: SLA შინაარსის მონიტორინგი, RTP, ჩართულობა.

მარკეტინგი/CRM: მეტრული დაფუძნებული ტრიგერის კამპანიები (DAU, სადეპოზიტო ძაბრი).

ოპერაციები/ფინანსები: near-real-time GGR/NGR, გადახდების წარმატება, ვებჰუკების ლაგამი.

პროდუქტი: 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, dedup 'event _ id/idempotency _ key'.

დანაყოფები: წინასწარ გაანგარიშებული rollup's (1m/5m/1h/1d) + on-the-fly.

Retenschen: cohort ძრავა Gold-Marts- ის თავზე.

Кэш: 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' - ფსევდონიმი, ფულის ერთეული.

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`
ვერსია - სემვერი; დამატება მხოლოდ 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) აგრეგაციის 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 Srazy/top (ჯგუფი-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 '.

Kash TTL დამოკიდებულია 'granularity' (მაგალითად, 5m TTL 60-120 s).

6) Retenschen და კოჰორტები: წესები და API

6. 1 განმარტება (კონვენცია)

DAU/WAU/MAU: აქტიურია, თუ ეს იყო „ბეტი“. 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	capured/intent (კოეფიციენტი)
Settle lag	t (settled) - t (placed), p95 percentil
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	უნიკალური აქტიური მოთამაშეები საქმიანობის წესების შესაბამისად

ყველაფერი - UTC- ში, ვალუტით და მცირე ერთეულებით; მულტივალენტობა წყდება FX- ის მიერ Data Lake- ში ჩაწერილი კონვერტაციის გზით.

8) ვერსია, ფილტრები და თავსებადობა

გზა: '/v1/... '; ახალი მეტრიკა/ველები - optional.

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

Pagination: cursor-based ('შემდეგი _ cursor').

Breaking არის მხოლოდ '/v2 '+ Deprecation/Sunset სათაურები და changelog.

9) უსაფრთხოება და წვდომა

OAuth2 Client Credentials (ხანმოკლე ნიშნები), mTLS B2B- სთვის.

RBAC/ABAC: მეტრიკის/ნაჭრების ნებართვები; RLS ფილტრი 'brand/region'.

PII: API არ აძლევს PII- ს, საჭიროების შემთხვევაში მხოლოდ დანაყოფებს/ფსევდო-ID.

რეზიდენცია: მოთხოვნის მარშრუტიზაცია რეგიონში; აკრძალულია ჯვარედინი რეგიონალური მონაცემები.

Rate limits და კვოტები, anti abuse; WORM წვდომის აუდიტი.

10) SLO და დაკვირვება

SLO სახელმძღვანელო:

'GET/Timeseries gran = 5m' p95-500-800 ms, 'GET/slice' p95-1-2 s (ტოპები 50-100 პოზიციამდე), 'POST/retention' (თვე) p95-3-5 წმ, rollup's სიახლე: p95-2-5 ocurred _ 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- ში; არქივი - ტბაში.

სკან ბაიტის შეზღუდვა მოთხოვნაზე; მინიშნება გრაფიკის შესახებ.

12) მშენებლობა და ექსპორტი

ჩაშენებული ვიჯეტები signed URL/iFrame- ით RLS ნიშნებით.

CSV/Parquet- ის ექსპორტი დავალებებზე (job API) ზომისა და დროებითი ბმულების შეზღუდვით.

Webhook შეტყობინებები გადმოტვირთვის მზადყოფნის შესახებ.

13) ჩეკის ფურცლები

არქიტექტურა

მოვლენების ერთიანი სქემა, სემვერი, რეგისტრი; dedup 'event _ id'.
Rollup's და materialized views საუკეთესო შემთხვევებისთვის.
RLS/RBAC/ABAC, რეზიდენტობა, ხანმოკლე ნიშნები.
კეში (ETag/TTL), საბაზო ლიმიტები, კვოტები.

სემანტიკა

დოკუმენტირებულია GGR/NGR/RTP/DAU/retention განმარტებები.
ვალუტა - მცირე ერთეულები; FX აღირიცხება ღონისძიების დროს.
Retention UTC- ში, ბრენდის დროსონის გათვალისწინებით.

ოპერაციები

SLO/დაშბორდები ახალი და ლატენტობა.
WORM აუდიტი წვდომის/ექსპორტის შესახებ.
DR/xaoc სწავლებები: rollup- ის ჩამორჩენა, მოთხოვნის აურზაური, დაგვიანებული მოვლენები.

14) ანტი-ნიმუშები (წითელი დროშები)

„ნედლეული“ OLTP ცხრილი პირდაპირ გადაეცემა API- ს.

გუნდებს შორის მეტრიკის არაკოორდინირებული განმარტებები.

ბაბუისა და წყლის არარსებობა ორმაგი/დაკარგული მოვლენაა.

შეუზღუდავი ფრენის აგრეგაცია ქეში/კვოტების გარეშე არის ძვირადღირებული და ნელი მოთხოვნები.

ჯვარედინი რეგიონალური განყოფილება რეზიდენციის პოლიტიკის გარეშე.

მოთამაშის PII/დეტალების დაბრუნება საჯარო პასუხებში.

მშვიდი breaking changes '/v2 'და Deprecation გარეშე.

15) მინი სპეკა (TL; DR)

მოვლენები: '/v1/events: batch '(at-least-once, dedup' event _ id ').

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

ნაჭრები: '/v1/analytics/slice? metric=...&dim=...`.

ძაბვები: '/v1/analytics/funnel '(ფანჯარა, ნაბიჯები, ფილტრები).

Retenschen/cohorty: '/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. ასე რომ, თქვენ მონაცემებს სწრაფად, იაფად და პროგნოზირებულად გადასცემთ - პარტნიორებს, პროდუქტს და BI- ს - სადავო ინტერპრეტაციების გარეშე და შენახვის გაჟონვის ან გადატვირთვის რისკის გარეშე.