Analytics ve Metrics API

1) Neden ayrı bir API katmanı

KPI için tek gerçek: "zoo SQL'i hariç tutun.
Ürün hızı: cepheler, ortak paneller, mobil müşteriler DWH'ye doğrudan erişim olmadan agrega elde eder.
Güvenlik ve uyumluluk: tokenizasyon, maskeler, coğrafi kısıtlamalar, RG/AML filtreleri.
Ölçekleme: önbellek, öncüler, CDN, kararlı sözleşmeler.

2) Taksonomi: metrikler, boyutlar, gerçekler

Gerçekler: bahisler, kazançlar, depozitolar, KYC etkinlikleri, RG müdahaleleri.
Boyutlar: Tarih/saat (takvimler), oyun/sağlayıcı, marka/ülke, kanal/cihaz, oyuncu (belirteç).
Metrikler: GGR, NGR/NET, ARPPU, D1/D7/D30 tutma, depozito sıklığı, sahtecilik karşıtı FPR, RG riski.
Birimler: para birimi (FX), zaman (TZ), hacim/sayaçlar (idempotent!).
KPI semantiği: BI sözleşmelerindeki tanımlar, KPI sürümleri sabittir.

3) Veri ve BI Sözleşmeleri

Şema: alanlar, türler, geçersiz, enum, birimler, para birimleri.
Metriklerin semantiği: formül, kaynaklar, toplama pencereleri, filtreler.
Uyumluluk (SEMVER): MAJOR kesmeleri, MINOR alanları ekler, PATCH düzeltmeleri.
DQ/SLA: tazelik, bütünlük, tutarlılık, tutarsızlık toleransları.
Gizlilik: 'pii: false', 'tokenized: true', detokenizasyon yasağı.

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4) Mimarlık

Sorgu API'si ("altın "/küpler/fichestore üzerinden çevrimiçi toplama).
Ön hesaplama API'si (zamanlanmış öncüller, materyalize görünümler).
Events API (akış sayaçları/sinyalleri).
Dışa aktarma API'si (imzalı yüklemeler, denetim için WORM).
Önbellek: Bellekte - Redis - CDN, key = query hash + version.
Tutarlılık: Son kayıtlar için read-your-writes, agregalar için SLA tazeliği.

5) Arayüz ve istekler

5. 1 Filtreler/toplamalar/pencereler

'filter': tarih aralıkları ('from/to' UTC, timezone aware), ülkeler, markalar, oyunlar, kanallar, cihazlar.
'group _ by': boyutlar.
'metrikler': KPI'ların listesi.
'window': 'DAY' WEEK 'MONTH' ROLLING '7D' ROLLING _ 28D '.
'para birimi': 'raporlama' native ', FX stratejisi:' eod 'gün içi' txn '.
'örnekleme': ağır sorgular için (yalnızca izin verildiğinde).

5. 2 İstek örneği

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5. 3 Yanıt örneği

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6) Sayfalama, sınırlar, sıralama

Sayfalama: 'limit' (≤10k), 'imleç' (opak), boyutlara/tarihe göre sıralama.
Zaman aşımı/kısmi: Yalnızca finansal olmayan KPI'lar için kısmi yanıtlar; Finans - ya P200 ya da P504.
Oran sınırları: global/anahtar/kiracı tarafından; Yanıt 'X-RateLimit-' içerir.

7) Idempotence ve önbellek

Idempotent GET/POST 'Idempotency-Key'ile (vücut ile) okuyun.
Önbellek anahtarı = hash (parametreler + şema sürümü + rol/kiracı/geo).
TTL: KPI bağımlı (örn. Gelir için 'PT15M', olaylar için 'PT5M'), yeni anlık görüntü ile sıfırlanır.

8) Tutarlılık ve zamanın para birimi

Geriye dönük raporlar için zaman yolculuğu bayrağı (veri sürümleri).
Kesme kuralları (gün/hafta kapanış).
FX: Stratejiyi, cevaptaki kurs tarihini düzeltiriz.
Saat: Tüm zaman damgaları ISO-8601, TZ gereklidir.

9) Güvenlik ve gizlilik

mTLS/TLS1. 3, istek/yanıt gövdesinin HMAC imzası (MITM/tekrar oynatma koruması).
RBAC/ABAC/ReBAC: rol + ülke + marka + amaç; varsayılan maskeler.
Çok kiracılı - Şemaları/anahtarları/kotaları izole edin.
Tanımlayıcıların tokenizasyonu; Yanıtlarda PII yasağı.
Denetim: değişmez istek günlükleri (WORM), 'trace _ id'/' actor'/' purpose'.
Onay/DSAR: pazarlama niteliklerine ilişkin filtreler; "Konu silindi" bayrağı.

10) RG/AML/Kısıtlama antifrode

RG-politikaları: Yüksek riskli segmentler için "agresif" göstergelerin yayınlanmasının yasaklanması; Birimler güvende.
AML/Antifraud: hassas KPI'lara sınırlı erişim, role göre imar; Araştırmalar için ayrı uç noktalar.
Açıklanabilirlik: Destek için KPI/sinyallerin açıklamalarının sözlüğü.

11) Gözlemlenebilirlik ve SLO API

SLO: p95 gecikme (örneğin, önbellek isabetleri için ≤ 300 ms; ağır için ≤ 2 s), başarı oranı ≥ 99. 5%.
DQ: tazelik/bütünlük/bütünlük; Yanıtta etiketler.
Kullanım: QPS, önbellek isabet oranı, kısayol tuşları, doğrulama hataları.
Uyarılar: Tazeliğin bozulması, büyüme 4xx/5xx, KPI'ya göre anormallikler (beklenmeyen sıfırlar/zirveler).
İzleme: 'trace _ id' DWH/fichestore için uçtan uca.

12) Sürüm oluşturma ve uyumluluk

Yollar:'/v1 ','/v2'; Geçiş penceresi ile değer düşüklüğü.
Şemalar: 'schema _ version' yanıt olarak; MAJOR - çift okuma, geçiş kılavuzları.
KPI sürümleri: 'kpi _ definitions' yanıtında dizinde bir bağlantı ile; Gizli formül değişikliklerini önleyin.

13) Hatalar ve durumlar

'400' validasyonu (mevcut olmayan metrik/ölçüm/filtre kombinasyonu).
'401/403' kimlik doğrulama/yetkilendirme.
'409' dönüşümü/politika uyumsuzluğu.
'42-' ayrıcalık/rıza ihlali.
'429' alıntıları.
'5xx' plaka formu arızaları (trace_id ve yeniden deneme seq.).

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) Entegrasyonlar ve arayüzler

BI: önceden tanımlanmış anlamsal modeller, konektörler (Looker/Power BI/Tableau) - Kaynak olarak API.
ML: özellik birimleri için hafif uç noktalar (PII olmadan, zaman içinde nokta).
Ortaklar: sınırlı anahtarlar/kotalar, coğrafi filtreler, raporlar yalnızca toplu bloklarda.
Webhook/Push: bildirimler "anlık görüntü hazır", "kırık SLO/KPI aralığı".

15) Kaynak bitiş noktaları örnekleri

15. 1 Gelir/Getiri

'POST/v2/metrics/revenue' - GGR/NGR, bahisler/kazançlar, 'tarih, marka, ülke, sağlayıcı, oyun'ile ölçülür.

15. 2 Tutma ve huniler

'POST/v2/metrics/retention' - когорты D1/D7/D30, 'group _ by = [cohort _ week, brand, country]'.

15. 3 Ödemeler

'POST/v2/metrics/payments' - para yatırma/çekme, ortalama çek, ters ibraz oranı.

15. 4 Sorumlu oyun

POST/v2/metrics/rg: Müdahale sayısı, yüksek risk oranı, ortalama reaksiyon süresi.

15. 5 Antifraud

'POST/v2/metrics/antifraud' - FPR/TPR, vakalar, kayıplar önlendi.

16) Test ve kalite

Sözleşme testleri: enum/nullable/type, para birimi/saat dilimi tutarlılığı.
DQ testleri: aralıkların kontrolü, monotonluk ve bütünlük.
Regresyon: Toleranslarda v1/v2 karşılaştırması.
Yükleme: zirve profilleri (turnuvalar/sağlayıcı etkinlikleri).
Güvenlik: imzalar, anti-replay, belirsiz istekler, günlüklerde Sıfır-PII.

17) Varsayılan olarak gizlilik

"Minimum N kayıt" eşiğine sahip kümeler (k-anonimlik).
Ham tanımlayıcılar yok; Yalnızca belirteçler/kategoriler.
DSAR: Ayrıcalıklı bir döngü yoluyla token ile boşaltma/silme için API.

18) Başarı Metrikleri (API KPIs)

Benimseme: Doğrudan SQL yerine API kullanan raporların/widget'ların oranı.
Tutarlılık - BI ve tolerans ≤ API arasındaki tutarsızlık.
SLO: gecikme/başarı/tazelik ile uyumluluk.
Güvenlik: Yanıtlarda/günlüklerde sıfır PII durumu.
Maliyet: Önbelleğin isabet oranı, isteğin maliyeti, hazırlayanların %'si.

19) RACI (örnek)

Ürün/Analiz (A) - KPI tanımları, gereksinimleri.
Veri Platformu (R) - uygulama, önbellek, SLA, gözlemlenebilirlik.
Alan Sahipleri (R) - Kaynaklar/Sözleşmeler.
Güvenlik/DPO (A/R) - gizlilik, erişim, denetimler.
SRE (R) - kotalar, otomatik ölçek, olaylar.
Finans (C), GGR/NGR/NET'in finansal anlambilimidir.

20) Uygulama Yol Haritası

0-30 gün (MVP)

1. 3-5 KPI seçin (GGR, mevduat, D7 tutma).
2. Sözleşmeleri ve KPI semantiğini tanımlamak; DQ/SLA'yı etkinleştir.
3. '/v1 'Sorgusu API + önbellek + mTLS/HMAC'yi uygulayın.
4. SLO panoları (gecikme/başarı/tazelik), denetim/trace _ id.

30-90 gün

1. Popüler vitrinleri, CDN önbelleğini önceden hesaplayın.
2. '/v2 'sürümü, çift okuma, geçiş kılavuzu.
3. API'leri imzalı yüklemelerle ve WORM'lerle dışa aktarın.
4. BI/ML ile entegrasyon; kotalar/kiracılar/coğrafi izolatörler.

3-6 ay

1. KPI taksonomisini ve widget kütüphanesini tamamlayın.
2. Akıllı ipuçları/otomatik tamamlama filtreleri, sorgu linter.
3. Otomatik Sürüm Notları KPI, toleransların kontrolü v1/v2.
4. Kısıtlı anahtarlar ve RG ilkeleriyle harici ortak döngüsü.

21) Anti-desenler

Gizli KPI formülü yeni bir sürüm ve sürüm notları olmadan değişir.
Kümeler/belirteçler yerine PII/hammaddeleri döndürün.
Önbellek/prerender eksikliği - pahalı ve yavaş.
Belirli bir veritabanına zor bağlanma (katman soyutlaması yok).
Tutarsız TZ/FX - farklı sayılar.
Hiçbir oran limitleri/kotalar - "DDOS kendi".

22) Şablonlar (kullanıma hazır)

22. 1 SLO API İlkesi (snippet)

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22. 2 OpenAPI (snippet)

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22. 3 Sürüm kontrol listesi

• KPI semantiği güncellendi ve sürüm yükseltildi
• Katalogda sözleşme/şema; DQ/regresyon testleri yeşil
• Önbellek anahtarları/TTL, prerenders yapılandırılmış
• Dokümantasyon ve Örnek İstekler/Yanıtlar
• SLO ve Kota Uyarıları Dahil
• Test edilen RG/AML kısıtlamaları

23) İlgili bölümler

DataOps Uygulamaları, Denetim ve Sürüm Oluşturma, Güvenlik ve Şifreleme, Erişim Kontrolü, Veri Tokenizasyonu, Saklama Politikaları, Veri Kaynağı ve Yolu, MLOps: Model Kullanımı, Veri Etiği.

Toplam

Analytics ve metrics API'leri, altın verilere ve KPI'lara sözleşmeli, güvenli ve hızlı bir erişim katmanıdır. Tek tip semantiği, kararlı sürümleri, varsayılan gizliliği ve ürün düzeyinde performansı garanti eder - dahili panolardan ortak panellere ve ML'ye kadar.