İstatistik ve Analitik API'leri: Etkinlikler, Toplamlar, Alıkoyma

Tam makale

💡 18+. Platformlar/operatörler, stüdyolar (RGS/canlı) ve BI/CRM ekipleri için mühendislik analizi. Oynamak için bir çağrı değil.

1) Neden harici bir analitik API'si

Ortaklar/sağlayıcılar: SLA içerik izleme, RTP, katılım.

Pazarlama/CRM: metriklere dayalı kampanyaları tetikler (DAU, para yatırma hunisi).

Operasyonlar/Finans: Neredeyse gerçek zamanlı GGR/NGR, ödeme başarısı, webhook gecikmeleri.

Ürün: Uygulama içi istatistik widget'ları, A/B panelleri.

Amaç, olayları ve kümeleri anlaşılabilir semantik ve SLA'larla güvenli ve öngörülebilir bir şekilde geri vermektir.

2) Parmaklarda mimari


Üreticiler (PAM/Cüzdan/RGS/Ödemeler/Kafka/CDC)
│
Yutma API ──Stream (Kafka/Pulsar) ──Lakehouse (Delta/Iceberg)
│ └─OLAP (ClickHouse/BigQuery/Trino)
└────────────────────────────────────Aggregation/Query API
(önbellek, RBAC/RLS, hız sınırları)

Olaylar: En az bir kez, 'event _ id/idempotency _ key'ile büyükbaba.

Agregalar: Önceden hesaplanmış toplamalar (1m/5m/1h/1d) + anında.

Retenchen: Gold Mart'ın üstünde kohort motoru.

Кэш: CDN/edge + ETag/' Cache-Control ', sunucu tarafı TTL.

3) Olay modeli: minimum standart

3. 1 Ortak alanlar

Json
{
"event_id":"uuid," "event_type":"bet. Yerleşik, "" occurred_at":"2025-10-23T16:21:05Z, "" ingested_at":"2025-10-23T16:21:06Z, "tenant_id":"brand-7," "bölge": "AB", "player_id":"p_19f3, "// псевдо -ID
"trace_id":"tr_a1b2c3," "schema_version":"1. 3. 0", "payload": {...}
}

Kurallar: UTC zaman damgaları, 'player _ id' - takma ad, küçük birimlerde para.

3. 2 Anahtar türleri

'session. Başladı	sona erdi '
'bet. yerleştirilmiş	Yerleşmiş '(stake_minor, win_minor, in_bonus, game_id, provider_id)
'wallet. debit	Kredi '(sebep, reference_id)
'ödeme. niyet	Yetkili
'Bonus. yayınlanan	tüketilen
'rg. limit. Hit	reality_check'
Sürüm oluşturma - semver; Sadece isteğe bağlı ekleme.

4) Yutma API'si (üçüncü taraf kaynaklar için)

Bir grup olay gönderme


POST/v1/events: batch
Başlıklar: X-Idempotency-Key: ev_20251023_001
[
{"event _ id": "...," event _ type ":" bet. placed, "...}, {" event _ id ":"..., "event _ type": "bet. yerleşmiş,"..}
]
^ 202 {'kabul edildi ": 2," kopyalar ": 0," trace_id":"tr_a1b2 "}

Garantiler: en az bir kez; Kopyalar Silver'da 'event _ id'ile filtrelenir.

5) Toplama API'si: zaman serisi ve dilimler

5. 1 Zaman çizelgeleri (zaman metrikleri)


GET/v1/analytics/zaman çizelgeleri
? metrik = gr//gr, ngr, dau, deposits_success, rtp
& granülerlik = 5m//1m/5m/1h/1d
& itibaren = 2025-10-22T00: 00: 00Z & için = 2025-10-23T00: 00: 00Z
& filters = region: EU, brand _ id: brand-7, provider _ id: studio _ x
& group _ by = brand _ id
→ 200 {
"metrik":" gr", "granülarite":" 5m", "seri": [
{"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 Dilimler/üstler (grup bazında)


GET/v1/analytics/slice
? metric = rtp & dim = game _ id & from = 2025-10-22 & to = 2025-10-23
& limit = 50 & order = -value
^ 200 {"öğeler ": [{"game _ id":" g _ 01"," değer": 0. 956},...] }

5. 3 Huni


POST/v1/analytics/huni
{
"adımlar": [
{'olay ":" ödeme. Niyet "}, {'olay": "ödeme. Yetkili "}, {'olay": "ödeme. Yakalanan"}, {"event ":" wallet. Kredi," "sebep ": "depozito"}
], "window_sec": 3600 ", filters ": {"region ": "EU"," brand _ id":" brand-7 "}
}
→ 200 {
"toplam": 12450, "adımlar": [
{"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 Sınırlar ve önbellek

Belirteç/marka/bölge başına oran sınırı.

Yanıtlara 'ETag'; 'If-None-Match' desteği.

TTL önbellek, tanecikliğe bağlıdır (örneğin, 5m> TTL 60-120 s).

6) Tutma ve kohortlar: kurallar ve API

6. 1 Tanımlar (sözleşmeler)

DAU/WAU/MAU: if 'bet ise etkindir. yerleştirilmiş'ya da "cüzdan. Kredi (depozito) 'или' oturumu. 'N dakika ≥ başladı.

İlk depozito (genellikle LTV için) veya kayıt (katılım için) ile kohort.

Tutma D1/D7/D30: kohorttan günlük pencereye +/- marka saat dilimine göre toleransa geri dönen oran.

Penceredeki benzersiz 'player _ id'tarafından tekrarlanan ziyaretleri göz önünde bulunduruyoruz.

6. 2 API kohortu


POST/v1/analytics/retention
{
"kohort": "first _ deposit", "start_date":"2025-09-01," end_date":"2025-09-30, "return_event":"bet". Yerleştirilmiş" "günler ": [1,7,14,30], "filtreler ": {"bölge ": "AB"," marka _ id":" marka-7 "}
}
→ 200 {
"kohort ": "first _ deposit", "rows": [
{"kohort _ tarih":" 2025-09-01 ", "boyut ": 1820," d1": 0. 36, "d7": 0. 22, "d14": 0. 18, "d30": 0. 12}, {"kohort _ tarih":" 2025-09-02 ", "boyut ": 1714," d1": 0. 35, "d7": 0. 23, "d14": 0. 19, "d30": 0. 13}
]
}

6. 3 LTV/Kümülatif


GET/v1/analytics/ltv? Kohort = first _ deposit & currency = EUR & horizon = 90d
^ 200 {"kohortlar ": [{" tarih":" 2025-09-01 ", "ltv _ minor ": [0,150,230,280,...]}}

7) Metrik semantik (tartışmamak)

Metrikler	Tanım (kısa)
GGR	Sum (bahis) − sum (kazanç) по 'bahsi. yerleşmiş 'dönem/para birimi
NGR	GGR − Bonus Gider − İkramiye Katkıları − Komisyonu
RTP	sum (kazan )/sum (bahis)
Depozito başarısı	yakalanan/niyet (faktör)
Yerleşme gecikmesi	t (yerleşmiş) − t (yerleştirilmiş), yüzdelik p95
Webhook gecikmesi	t (yutuldu) − t (meydana geldi), p95
DAU/WAU/MAU	Aktivite kurallarına göre benzersiz aktif oyuncular

Hepsi - para birimi ve küçük birimlerle UTC'de; Çok para birimi, sabit FX'i Data Lake'e dönüştürerek çözülür.

8) Sürüm, filtreler ve uyumluluk

Yol:'/v1/... '; yeni metrikler/alanlar - isteğe bağlı.

Фильтры: 'brand _ id, region, provider_id, game_id, method, currency, device, geo'.

Sayfalama: imleç tabanlı ('next _ cursor').

Breaking - sadece'/v2 '+ Reddetme/Günbatımı başlıkları ve changelog.

9) Güvenlik ve erişim

OAuth2 İstemci Kimlik Bilgileri (kısa ömürlü belirteçler), B2B için mTLS.

RBAC/ABAC: metrik/dilim izinleri; RLS filtresi 'marka/bölge'ye göre.

PII: API, PII vermez, yalnızca gerekirse/pseudo-ID'yi toplar.

İkamet: talepleri bölgeye yönlendirmek; bölgeler arası veri - izin verilmez.

Oran limitleri ve kotaları, suistimal karşıtı; Erişimlerin WORM denetimi.

10) SLO ve gözlemlenebilirlik

SLO kriterleri:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (50-100 pozisyona kadar), 'POST/retention' (kohortların ayı) p95 ≤ 3-5 s, tazelik toplaması: p95 ≤ 2-5 dk.
Metrikler: gecikme p50/p95/p99, hata oranı (4xx/5xx), önbellek isabeti, istekler/tarama baytları (OLAP), her rollup'y için tazelik gecikmesi.
Günlükler: yapılandırılmış, 'trace _ id', sorgu filtreleri (PII olmadan), tarama sayısı.

11) Nakit, ön hesaplamalar, maliyet

Toplama tabloları: Anahtar metriklere göre 1m/5m/1h/1d - hızlı 'zaman çizelgeleri'.

Ağır bölümler/kohortlar için materyalize edilmiş görüşler.

ETag + max-age; Geç olaylarda sakatlık aşamalı olarak gerçekleşir.

Strateji "sıcak/soğuk": sıcak sorgular - OLAP-depoda; Arşiv - Gölde.

İstek başına "tarama baytlarının" kısıtlanması; zamanlayıcıya ipucu verir.

12) Gömülü ve dışa aktarma

RLS belirteçleri ile imzalanmış URL/iFrame aracılığıyla yerleşik widget'lar.

CSV/Parquet'i boyut kısıtlamaları ve geçici referanslarla göreve göre (iş API'si) dışa aktarın.

Webhook yükleme hazırlığı hakkında bildirimler.

13) Kontrol listeleri

Mimari

Birleştirilmiş olay şeması, semver, kayıt defteri; 'event _ id'ile büyükbaba.
Üst vakalar için Rollup ve somutlaştırılmış görünümler.
RLS/RBAC/ABAC, ikamet, kısa ömürlü belirteçler.
Önbellek (ETag/TTL), oran limitleri, kotalar.

Semantik

GGR/NGR/RTP/DAU/tutma tanımları belgelenmiştir.
Para birimleri - küçük birimler; FX olay anında sabittir.
UTC ile tutma, ekrandaki marka zaman dilimini dikkate alarak.

Operasyonlar

SLO/tazelik ve gecikme panoları.
WORM erişim/ihracat denetimi.
DR/xaoc egzersizleri: rollup lag, istek telaşı, geç olaylar.

14) Anti-desenler (kırmızı bayraklar)

"Raw" OLTP tabloları doğrudan API'ye verilir.

Komutlar arasında tutarsız metrik tanımlar.

Veri tekilleştirme ve filigran yok - çift/kayıp olaylar.

Önbellek/kotalar olmadan sınırsız on-the-fly toplama - pahalı ve yavaş istekleri.

İkamet politikası olmadan bölgeler arası toplama.

PII/oyuncu ayrıntılarını genel yanıtlara döndürün.

'/v2've Kullanımdan Kaldırılma olmadan sessiz kırılma değişiklikleri.

15) Mini spec (TL; DR)

Events:'/v1/events: batch '(en az bir kez, dedup by' event _ id ').

Zaman çizelgeleri:'/v1/analitik/zaman çizelgeleri? metrik =... & ayrıntılı =... '(toplama + кэш).

Dilimler:'/v1/analytics/dilim? metrik =... & dim =... '.

Huniler:'/v1/analytics/huni '(pencere, adımlar, filtreler).

Tutma/kohortlar:'/v1/analytics/retention '(+ LTV).

Güvenlik: OAuth2 + mTLS, RLS, marka/bölge belirteçleri başına, WORM denetimi.

SLO: p95 ≤ 0. 5-2 s; Tazelik ≤ 2-5 dk.

İstatistik ve analitik API'ler "SELECT FROM big_table'değil, bir metrik sözleşmesidir: kararlı olaylar, önceden okunmuş ve önbelleğe alınmış toplamlar, kesinlikle tanımlanmış saklama ve kohortlar, güvenlik (RLS/RBAC) ve SLO tarafından anlaşılabilir ikamet. Böylece, verileri hızlı, ucuz ve öngörülebilir bir şekilde - ortaklara, ürüne ve BI'ye - tartışmalı yorumlar olmadan ve sızıntı veya aşırı depolama yükü riski olmadan verirsiniz.