API de estadísticas y análisis: eventos, agregados, retenshen

Texto completo del artículo

💡 18+. Material de análisis de ingeniería para plataformas/operadores, estudios (RGS/live) y comandos BI/CRM. No es una llamada al juego.

1) Por qué análisis de API externa

Socios/proveedores: monitoreo de contenido SLA, RTP, participación.

Marketing/CRM: campañas de activación basadas en métricas (DAU, embudo de depósito).

Operaciones/Finanzas: near-real-time GGR/NGR, éxito de pagos, lagunas de webhooks.

Producto: widgets de estadísticas in-app, paneles A/B.

El objetivo es dar eventos y agregados de forma segura y previsible con una semántica y SLA comprensibles.

2) Arquitectura en los 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, dedoop por 'event _ id/idempotency _ key'.

Agregados: rollup's predeterminados (1m/5m/1h/1d) + on-the-fly.

Retenshen: motor cohort encima de las Martas de Oro.

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

3) Modelo de eventos: estándar mínimo

3. 1 Campos comunes

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

Reglas: timestamps UTC, 'player _ id' es un alias, dinero en unidades menores.

3. 2 Tipos clave

`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`
Versioning - semver; agregar sólo optional.

4) API de ingeniería (para fuentes de terceros)

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

Garantías: at-least-once; los duplicados se filtran en Silver por 'event _ id'.

5) Aggregation API: series de tiempo y cortes

5. 1 Crimseries (métricas de tiempo)


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 (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 Embudos (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 Límites y caché

Rate limit per token/brand/region.

'ETag' a las respuestas; soporte 'If-None-Match'.

La caché TTL depende de 'granularity' (por ejemplo, 5m → TTL 60-120 s).

6) Retencion y cohortes: reglas y API

6. 1 Definiciones (convenios)

DAU/WAU/MAU: activo si había 'bet. placed 'o' wallet. credit (deposit)` или `session. started '≥ N minutos.

Cohort by first deposite (a menudo para LTV) o por registration (por compromiso).

Retention D1/D7/D30: la fracción de la cohorte ha vuelto a la ventana del día +/- tolerancia en la zona de tiempo de la marca.

Las visitas repetidas cuentan por el único 'player _ id' en la ventana.

6. 2 cohortes 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/acumulativos


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

7) Métricas semánticas (para no discutir)

Métrica	Definición (breve)
GGR	sum(stake) − sum(win) по `bet. settled 'en el período/moneda
NGR	GGR − gastos de bonificación − contribuciones del premio mayor − comisiones
RTP	sum(win) / sum(stake)
Deposit success	capturado/intent (coeficiente)
Settle lag	t (settled) − t (placed), percentil p95
Webhook lag	t(ingested) − t(occurred), p95
DAU/WAU/MAU	jugadores activos únicos según las reglas de actividad

Todo - en UTC especificando la moneda y las unidades menores; la multidivisa se resuelve mediante la conversión de FX fijo a Data Lake.

8) Versificación, filtros y compatibilidad

Ruta: '/v1/... '; nuevas métricas/campos - optional.

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

Paginación: cursor-basado ('next _ cursor').

Breaking → sólo '/v2 '+ Deprecation/Sunset encabezados y changelog.

9) Seguridad y acceso

OAuth2 Credentials de cliente (tokens de vida corta), mTLS para B2B.

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

PII: API no da PII, sólo unidades/pseudo-ID si es necesario.

Residencia: enrutamiento de solicitudes a una región; Datos cruzados regionales - prohibidos.

Rate limits y cupos, anti-abuse; Auditoría de acceso WORM.

10) SLO y observabilidad

SLO puntos de referencia:

'GET/timeseries gran = 5m' p95 ≤ 500-800 ms, 'GET/slice' p95 ≤ 1-2 s (tops hasta 50-100 posiciones), 'POST/retention' (mes de cohorte) p95 ≤ 3-5 s, frescura rollup's: p95 ≤ 2-5 min desde 'occurred _ at'.
Métricas: latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, consultas/escaneo de bytes (OLAP), «freshness lag» por cada rollup 'y.
Logs: estructurados, 'trace _ id', filtros de consulta (sin PII), cuenta de análisis.

11) Caché, cálculos preliminares, costo

Tablas rollup: 1m/5m/1h/1d por métricas clave → 'timeseries' rápidas.

Vistas materializadas para cortes pesados/cohortes.

ETag + max-age; la discapacidad en eventos tardíos se produce de forma incremental.

Estrategia "hot/cold': consultas en caliente - en OLAP-warehouse; Archivo - en Lake.

Restricción de «bytes de análisis» a una solicitud; consejos al planificador.

12) Incrustación (embedded) y exportación

Widgets integrados a través de URL/iFrame señalizados con tokens RLS.

Exportar CSV/Parquet por tareas (API job) con restricciones de tamaño y referencias temporales.

Notificaciones webhook sobre la disponibilidad de descarga.

13) Hojas de cheques

Arquitectura

Esquema Único de Eventos, Semver, Registro; dedoup por 'event _ id'.
Rollup's y vistas materializadas a los mejores casos.
RLS/RBAC/ABAC, residencia, tokens de vida corta.
Caché (ETag/TTL), rate limits, cuotas.

Semántica

Las definiciones GGR/NGR/RTP/DAU/retention están documentadas.
Monedas - unidades menores; FX se registra en el momento del evento.
Retention por UTC, teniendo en cuenta los temporizadores de marca en la visualización.

Operaciones

SLO/dashboards de frescura y latencia.
Auditoría WORM de accesos/exportaciones.
Ejercicios de DR/xaoc: atraso de rollup, un aluvión de consultas, eventos atrasados.

14) Anti-patrones (banderas rojas)

Las tablas OLTP «crudas» se entregan directamente en la API.

Definiciones de métricas no armonizadas entre equipos.

Ningún dedup y watermarks → eventos dobles/perdidos.

Agregaciones on-the-fly ilimitadas sin caché/cuotas → consultas costosas y lentas.

Agregación cruzada-regional sin política de residencia.

Devuelve el PII/detalles del jugador a las respuestas públicas.

Tranquilos breaking-changes sin '/v2 'y Deprecation.

15) Mini Speca (TL; DR)

Eventos: '/v1/events: batch '(en-least-once, dedoop por' event _ id ').

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

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

Embudos: '/v1/analytics/funnel '(ventana, pasos, filtros).

Retenshen/cohortes: '/v1/analytics/retention '(+ LTV).

Seguridad: OAuth2 + mTLS, RLS, tokens por marca/región, auditoría WORM.

SLO: p95 ≤ 0. 5-2 s; frescura ≤ 2-5 minutos.

La API de estadísticas y análisis no es "SELECT FROM big_table", sino un contrato de métricas: eventos estables, agregados pre-leídos y almacenados en caché, retenciones y cohortes estrictamente definidos, seguridad (RLS/RBAC) y residencia entendida por SLO. Así que usted entrega los datos de forma rápida, barata y predecible - a socios, productos y BI - sin interpretaciones controvertidas y sin riesgo de fugas o sobrecarga de almacenamiento.