トレントギア

統計と分析API：イベント、集計、保持

完全な記事

💡 18+.プラットフォーム/オペレータ、スタジオ（RGS/ライブ）およびBI/CRMチームのエンジニアリング分析。再生する呼び出しではありません。

1）外部アナリティクスAPIを使用する理由

パートナー/プロバイダー：SLAコンテンツ監視、RTP、エンゲージメント。

マーケティング/CRM：メトリクス（DAU、預金ファネル）に基づいてキャンペーンをトリガーします。

オペレーション/ファイナンス：ほぼリアルタイムのGGR/NGR、支払い成功、webhook lags。

製品：アプリ内の統計ウィジェット、A/Bパネル。

目標は、理解可能な意味論とSLAを使用して、イベントと集計を安全かつ予測可能に戻すことです。

2）指のアーキテクチャ


生産者（PAM/財布/RGS/支払 い/カフカ/CDC）
│
Ingestion API──ストリーム（カフカ/パルサー）──レイクハウス（デルタ/アイスバーグ）
└─OLAP （ClickHouse/BigQuery/Trino）
└────────────────────────────────────Aggregation/Query API
（キャッシュ、RBAC/RLS、レート制限）

イベント：少なくとも1回は、祖父は'event_id/idempotency_key'。

集計：事前に計算されたロールアップ（1m/5m/1h/1d）+オンザフライ。

Retenchen：ゴールドマートの上にコホートエンジン。

Кэш： CDN/edge+ETag/'キャッシュ制御'、サーバー側TTL。

3）イベントモデル： 最低の標準

3.1共通フィールド

JSON
{
「event_id":"uuid,」 「event_type":"bet」。決済"、""occurred_at":"2025-10-23T16:21:05Z,""ingested_at":"2025-10-23T16:21:06Z, "tenant_id":"brand-7,""地域"："EU"、 "player_id":"p_19f3, "//独立ID
「trace_id":"tr_a1b2c3,」 「schema_version":"1」。3.0"、 "payload"：{……}
}

ルール：UTCタイムスタンプ、'player_id'-エイリアス、マイナーユニットのマネー。

3.2つのキーのタイプ

「セッション」開始しました	終了しました'
'ベット。配置された	settled '（stake_minor、 win_minor、 in_bonus、 game_id、 provider_id）
'wallet。デビット	credit'（理由、reference_id）
支払いだよ。インテント	認可された
「ボーナス」発行された	消費される
'RG。限界。ヒットしました	reality_check'
バージョン管理-semver；追加はオプションのみです。

4） Ingestion API（サードパーティのソース用）

イベントの一括送信


POST/v1/events：バッチ
ヘッダー：X-Idempotency-Key： ev_20251023_001
[
{"event_id"："……"、"event_type"：" bet。配置された、」……},{「event_id「：「……「、「event_type」：」 bet。落ち着いた、"……}
]
→202 {「accepted」： 2、 「duplicates」： 0、 「trace_id":"tr_a1b2」}

保証：少なくとも一度；重複は'event_id'によってSilverでフィルターされます。

5）集計API： 時系列とスライス

5.1時系列（タイムメトリック）


GET/v1/analytics/timeseries
？metric=ggr//ggr、 ngr、 dau、 deposits_success、 rtp
&粒度=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スライス/トップス（グループ単位）


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ファネル


POST/v1/analytics/funnel
{
「ステップ」：［
{"イベント"："支払い。intent」}、 {「event「：」payment。authorized」}、 {「event「：」payment。キャプチャされた"}"、{"event"： "wallet。クレジット"、"理由"："預金"}
］、"window_sec"： 3600"、フィルター"：{"region"："EU"、" brand_id"：" brand-7"}
}
→ 200 {
「合計」：12450、「ステップ」：［
{"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制限とキャッシュ

トークン/ブランド/地域ごとのレート制限。

応答に'ETag'；'If-None-Match'をサポート。

TTLキャッシュは粒度に依存します（例えば、5m→TTL 60-120 s）。

6）保持とコホート： ルールとAPI

6.1定義（規約）

DAU/WAU/MAU： active if if if 'bet。'または'walletを配置しました。クレジット（デポジット）'デポジット'セッション。開始'≥ N分。

最初の預金によるコホート（しばしばLTV用）または登録（関与用）。

保持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。配置、"days'： ［1,7,14,30］,"フィルター"：{"地域"："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）メトリクスの意味論（議論しないこと）

メトリクス	定義（brief）
GGR	sum （stake） − sum （win）のベット。期間/通貨で決済'
NGRについて	GGR −ボーナス費用−ジャックポット貢献−委員会
RTP （RTP）	sum （win ）/sum （stake）
デポジットの成功	キャプチャ/インテント（因子）
ラグを解決する	t（定着）− t（配置）、パーセンタイルp95
Webhookの遅れ	t（摂取済み）− t（発生）、p95
DAU/WAU/MAU	アクティビティルールによるユニークなアクティブプレーヤー

すべて-通貨とマイナーユニットでUTC；multicurrencyは、固定FXをData Lakeに変換することで解決されます。

8）バージョン、フィルターおよび両立性

パス：'/v1/……';新しいメトリック/フィールド-オプション。

Фильтры： 'brand_id、 region、 provider_id、 game_id、 method、 currency、 device、 geo'。

ページネーション：カーソルベース（'next_cursor'）。

Breaking→のみ'/v2'+Rejection/Sunsetヘッダーとchangelog。

9）セキュリティとアクセス

OAuth2 Client Credentials（短命トークン）、mTLS for B2B。

RBAC/ABAC：メトリック/スライスのアクセス許可；'brand/region'によるRLSフィルタ。

PII： APIはPIIを与えず、必要に応じて集計/擬似IDのみを与えます。

レジデンシー：地域へのルーティングリクエスト；クロスリージョンデータ-許可されていません。

レート制限とクォータ、乱用防止；アクセスのWORM監査。

10） SLOおよび観察可能性

SLOベンチマーク：

'GET/timeseries gran=5m' p95 ≤ 500-800 ms、 'GET/slice' p95 ≤ 1-2 s（最大50-100ポジション）、'POST/保持'（コホートの月）p95 ≤ 3-5 s、鮮度ロールアップ：p95 ≤ 2-5 min from 'oked_at'。
メトリクス：latency p50/p95/p99、 error-rate （4xx/5xx）、 cache-hit、 requests/scan bytes （OLAP）、各ロールアップの鮮度lag 'y。
ログ：構造化、'trace_id'、クエリフィルタ（PIIなし）、スキャン数。

11）現金、予備計算、コスト

ロールアップテーブル：1m/5m/1h/1dキーメトリクス→高速'時系列'。

重いセクション/コホートのマテリアライズされたビュー。

ETag+max-age；遅い出来事の障害は段階的に起こります。

戦略「ホット/コールド」：ホットなクエリ-OLAP-warehouse；アーカイブ-湖で。

リクエストごとに「スキャンバイト」の制限;スケジューラへのヒント。

12）埋め込まれ、輸出

RLSトークンで署名されたURL/iFrame経由の組み込みウィジェット。

CSV/Parquetをタスク（ジョブAPI）でエクスポートし、サイズ制約と一時参照を指定します。

アップロードの準備についてのWebhook通知。

13）チェックリスト

アーキテクチャ

統一されたイベントスキーマ、semver、レジストリ；おじいちゃんby 'event_id'。
トップケースのロールアップとマテリアライズされたビュー。
RLS/RBAC/ABAC、レジデンシー、短命トークン。
キャッシュ（ETag/TTL）、レート制限、クォータ。

セマンティクス

GGR/NGR/RTP/DAU/retentionの定義がドキュメント化されています。
通貨-マイナーユニット；FXはイベント時に固定されます。
ディスプレイ内のブランドタイムゾーンを考慮し、UTCによる保持。

Operations（オペレーション）

SLO/鮮度とレイテンシのダッシュボード。
アクセス/エクスポートのWORM監査。
DR/xaoc演習：ロールアップラグ、リクエストのフラリー、遅いイベント。

14）アンチパターン（赤い旗）

「Raw」 OLTPテーブルはAPIに直接与えられます。

コマンド間の一貫性のないメトリック定義。

重複排除と透かし→二重/失われたイベントはありません。

キャッシュ/クォータ→高価で遅いリクエストのない無制限のオンザフライ集計。

居住ポリシーのない地域横断集約。

PII/プレイヤーの詳細を公開レスポンスに戻します。

'/v2'およびDeprecationのない静かな壊れ目の変更。

15）ミニスペック（TL；DR）

イベント：'/v1/events： batch'（少なくとも一度は'event_id'でデダップ）。

時系列：'/v1/analytics/timeseries？metric=……&granularity=……'（ロールアップ+кэш）。

スライス：'/v1/analytics/slice？metric=……&dim=……'。

ファネル：'/v1/analytics/funnel'（ウィンドウ、ステップ、フィルタ）。

保持/コホート：'/v1/analytics/retention'（+LTV）。

セキュリティ：ブランド/リージョントークンごとのOAuth2+mTLS、 RLS、 WORM監査。

SLO： p95 ≤ 0。5-2 s；新鮮さ≤ 2-5分。

統計および分析APIは「SELECT FROM、 big_table」ではなく、安定したイベント、事前に読み取りおよびキャッシュされた集計、厳密に定義された保持とコホート、セキュリティ（RLS/RBAC）、およびSLOが理解できる居住性などのメトリクスの契約です。だから、データを迅速に、安く、予測可能に-パートナーに、製品とBI-物議を醸す解釈せず、漏洩やストレージの過負荷のリスクなし。