API estatísticas e analistas: eventos, agregados, retensivo

Texto completo do artigo

💡 18+. Material de engenharia e análise para plataformas/operadoras, estúdios (RGS/live) e comandos BI/CRM. Não um apelo para o jogo.

1) Por que a API externa dos analistas

Parceiros/provedores: monitoramento de conteúdo SLA, RTP, envolvimento.

Marketing/CRM: campanhas de desencadeamento baseadas em métricas (DAU, vórtice de depósito).

Transações/finanças: near-real-time GGR/NGR, sucesso de pagamentos, acervos de webhooks.

Produto: in-app widgets estatísticas, painéis A/B.

O objetivo é entregar eventos e agregados com uma semântica compreensível e SLA de forma segura e previsível.

2) Arquitetura nos dedos


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)

Eventos: at-least-once, deadup por 'event _ id/idempotency _ key'.

Unidades: rollup's pré-cálculo (1m/5m/1h/1d) + on-the-fly.

Retenschen, um motor cohort acima do Gold-Marts.

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

3) Modelo de evento: padrão mínimo

3. 1 Campos gerais

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

Regras: UTC timestams, 'player _ id' - pseudônimo, dinheiro em minor units.

3. 2 Tipos-chave

`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`
Versionização - semver; adicionar apenas optional.

4) Injecção API (para terceiros)

Enviar pacote de eventos


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

Garantias: at-least-once; as duplicações são filtradas no Silver por 'event _ id'.

5) Agregation API: time-series e corte

5. 1 Temporizações (métricas no tempo)


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 Cortes/tops (grupo-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 Vórtices (funtel)


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 Limites e armazenamento em dinheiro

Rate limit per token/brand/region.

'ETag' para as respostas; suporte 'If-None-Match'.

O cachê TTL depende de 'granularity' (por exemplo, 5m → TTL 60-120 s).

6) Retenschen e conectividade: regras e API

6. 1 Definições (convenções)

DAU/WAU/MAU: ativo se 'bet. placed 'ou' wallet. credit (deposit)` или `session. started 'n' N minutos.

Cohort by first deposit (frequentemente para LTV) ou by registration (para envolvimento).

Retenção D1/D7/D30: A parte da banda voltou para a janela do dia +/- permissão para a zona de tempo da marca.

As visitas repetidas são por «player _ id» exclusivo na janela.

6. Kpart 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/cumulativos


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

7) Semântica métricas (para não discutir)

Métrica	Definição (Resumir)
GGR	sum(stake) − sum(win) по `bet. setled 'no período/moeda
NGR	GGR - despesas de bónus - jackpot contribuições - comissões
RTP	sum(win) / sum(stake)
Deposit success	captured/intent (coeficiente)
Settle lag	t (setled) - t (placed), percêntrico p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	Jogadores únicos ativos de acordo com as regras de atividade

Tudo em UTC com a indicação da moeda e minor units; A multivalência é decidida com a conversão de FX fixado em Data Lake.

8) Versiação, filtros e compatibilidade

Caminho: '/v1/... '; novas métricas/campos - optional.

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

Paginação: cursor-based ('next _ cursor').

Breaking → apenas '/v2 '+ Deprecation/Sunset títulos e changelog.

9) Segurança e acesso

O OAUTh2 Clientes Credentals é mTLS para o B2B.

RBAC/ABAC: permissões para métricas/cortes; filtro RLS por 'brand/region'.

PII: A API não dá PII, apenas unidades/pseudo-ID, se necessário.

Residência: localização de solicitações para a região; Dados cruzados-regionais são proibidos.

Rate limits e quotas, anti-abuse; Auditoria WORM de acessibilidade.

10) SLO e observabilidade

SLO orientações:

'GET/timeséries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (tops para 50-100 posições), 'POST/retence' (mês) p95 ≤ 3-5 s, frescor rollup 'ov: p95 ≤ 2-5 min de' occurred _ at '.
Métricas: latency p50/p95/p99, error-rate (4xx/5xx), cachê-hit, consultas/scan-bytes (OLAP), «freshness lag» para cada rollup 'y.
Logi: estruturado, 'trace _ id', filtros de consulta (sem PII), conta de raias.

11) Cash, cálculos preliminares, valor

Tabelas Rollup: 1m/5m/1h/1d em métricas-chave → rápidas 'timeséries'.

Materializante views para cortes pesados/cocort.

ETag + max-age; A deficiência em eventos tardios é aumentada.

Estratégia «hot/cold»: consultas quentes - em OLAP-warehouse; arquivo - em Lake.

Limite de scan-bytes por solicitação; dicas para o planejador.

12) Incorporação (embedded) e exportação

Widgets incorporados por meio de URL/iFrame com torneios RLS.

Exportar CSV/Parquet por tarefa (job API) com limitações de tamanho e links temporários.

Notificações Webhook de que o download está pronto.

13) Folhas de cheque

Arquitetura

Esquema de evento unificado, semver, registry; Dedup por 'event _ id'.
Rollup's e materializações views sob as malas top.
RLS/RBAC/ABAC, residência, tokens de curta duração.
Dinheiro (ETag/TTL), rate limits, quotas.

Semântica

As determinações da GGR/NGR/RTP/DAU/retenção foram documentadas.
Moedas - minor units; O FX é registrado no momento do evento.
Retenção por UTC, considerando os times de marca na exibição.

Operações

SLO/dashboard de frescura e latência.
Auditoria WORM de acessibilidade/exportação.
Dr./xaoc-exercício: atraso no rollup, questionamentos atrasados.

14) Anti-pattern (bandeiras vermelhas)

«Crus» tabelas OLTP são entregues diretamente para API.

Definições de métricas incoerentes entre os comandos.

Falta de dedups e watermarks → eventos duplos/perdidos.

Agregações on-the-fly ilimitadas sem dinheiro/quotas → solicitações caras e lentas.

Agregação cruzada regional sem política de residência.

Restituir PII/detalhes do jogador em respostas públicas.

Breaking-changes silenciosos sem '/v2 'e Deprecation.

15) Mini-especa (TL; DR)

Eventos: '/v1/events: batch '(at-least-once, dedução por' event _ id ').

Timserias: '/v1/analytics/timeséries? metric=...&granularity=...` (rollup + кэш).

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

Vórtices: '/v1/analytics/funnel '(janela, passos, filtros).

Retenschen/cohorts: '/v1/analytics/retence '(+ LTV).

Segurança: OAuth2+mTLS, RLS, tokens per brand/region, auditoria WORM.

SLO: p95 ≤ 0. 5-2 c; frescor ≤ 2-5 min.

A API de estatísticas e analistas não é «SELECT FROM big _ tablet», mas um contrato de métricas: eventos estáveis, unidades pré-lidas e em dinheiro, retensas e cômodos estritamente definidos, segurança (RLS/RBAC) e permanência compreendida pelo SLO. Assim, você entrega os dados de forma rápida, barata e previsível - parceiros, produtos e BI - sem interpretações controversas e sem risco de fuga ou superaquecimento do armazenamento.