تورنت جير

واجهات برمجة التطبيقات الإحصائية والتحليلية: الأحداث والتجمعات والاحتفاظ

مقالة كاملة

💡 18+. تحليل هندسي للمنصات/المشغلين، والاستوديوهات (RGS/live) وأفرقة BI/CRM. ليست دعوة للعب.

1) لماذا تحليلات خارجية API

الشركاء/مقدمو الخدمات: مراقبة محتوى SLA، RTP، المشاركة.

التسويق/إدارة علاقات العملاء: حملات التشغيل القائمة على المقاييس (DAU، قمع الإيداع).

العمليات/التمويل: GGR/NGR في الوقت الفعلي تقريبًا، نجاح الدفع، تأخيرات الويب.

المنتج: أدوات إحصائية داخل التطبيق، لوحات A/B.

الهدف هو إعادة الأحداث والتجمعات بأمان وبشكل متوقع بدلالات مفهومة واتفاقات SLAs.

2) الهندسة المعمارية على الأصابع


المنتجون (PAM/Wallet/RGS/Payments/Kafka/CDC)
│
Ingestion API ──Stream (كافكا/بولسار) ──Lakehouse (دلتا/جبل الجليد)
│ └─OLAP (ClickHouse/BigQuery/Trino)
└────────────────────────────────────Aggregation/Query API
(مخبأ، RBAC/RLS، حدود الأسعار)

الأحداث: مرة واحدة على الأقل، الجد بواسطة «event _ id/idempotency _ key».

المجاميع: rollups محسوبة مسبقًا (1 م/5 م/1 ساعة/1 د) + أثناء الطيران.

Retenchen: محرك جماعي على قمة Gold Marts.

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

3) نموذج الحدث: المعيار الأدنى

3. 1 ميادين مشتركة

جسون
{
"event_id":"uuid," "event_type":"bet. "occurred_at":"2025-10-23T16:21:05Z," "ingested_at":"2025-10-23T16:21:06Z," tenant_id":"brand-7, "" منطقة ":" الاتحاد الأوروبي "،" player_id":"p_19f3, "/ псевдо -ID
"trace_id":"tr_a1b2c3," "schema_version":"1. 3. 0، «الحمولة»: {...}
}

القواعد: الطوابع الزمنية للتوقيت العالمي المنسق، «player _ id» - الاسم المستعار، المال في الوحدات الثانوية.

3. 2 الأنواع الرئيسية

'session. بدأت	انتهى "
'bet. وضع	(stake_minor، win_minor، in_bonus، game_id، provider_id)
'wallet. الخصم	الائتمان '(السبب، reference_id)
الدفع. القصد	مأذون به
«بونس». صدر	المستهلكة
'rg. حد. ضرب	reality_check'
Versioning - semver ؛ إضافة اختيارية فقط.

4) Ingestion API (لمصادر طرف ثالث)

إرسال مجموعة من الأحداث


POST/v1/الأحداث: دفعة
الرؤوس: X-Idempotency-Key: ev_20251023_001
[
{«event _ id»:... «,» event _ type «:» bet. وضعت، "}، {" event _ id ":"...، "event _ type": "bet. '
]
→ 202 {«مقبولة»: 2، «مكررة»: 0، «trace_id":"tr_a1b2»}

الضمانات: مرة واحدة على الأقل ؛ يتم تصفية النسخ المكررة بالفضة بواسطة 'event _ id'.

5) واجهة برمجة التطبيقات التجميعية: السلاسل الزمنية والشرائح

5. 1 التوقيت (القياسات الزمنية)


احصل على/v1/تحليلات/جداول زمنية
؟ متري = gr//ggr، ngr، dau، deposits_success، rtp
الدقة = 5 م/1 م/5 م/1 ح/1 د
من = 2025-10-22T00: 00: 00Z & to = 2025-10-23T00: 00: 00Z
& filters = المنطقة: الاتحاد الأوروبي، العلامة التجارية _ id: العلامة التجارية 7، المزود _ 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 _ minger»: 98020}
]، "next_cursor":null
}

5. 2 شرائح/أعلى (مجموعة تلو الأخرى)


احصل على/v1/تحليلات/شريحة
؟ metric = rtp & dim = game _ id & from = 2025-10-22 & to = 2025-10-23
الحد = 50 & order = -value
→ 200 {«العناصر «: [{«game _ id»:» g _ 01»,» value»: 0. 956},...] }

5. 3 قمع


POST/v1/analytics/vunnel
{
«خطوات»: [
{"حدث ":" دفع. النية»}، {«الحدث «:» الدفع. مأذون به»}، {«حدث «:» دفع. تم القبض عليه»}، {«حدث «:» محفظة. الائتمان، «السبب»: «الإيداع»}
], "window_sec": 3600," filters': {"region": "EU", "brand _ id':" brand-7 "}
}
→ 200 {
«المجموع»: 12450، «الخطوات»: [
{«الاسم «:» النية»، «العد «: 12450، «المعدل»: 1. 0}، {«الاسم «: «المصرح به»، «العد «: 11020، «المعدل»: 0. 885}, {"name": "capted", "count': 10110," rate ": 0. 811}, {"name": "credited", "count': 10050," rate ": 0. 807}
]
}

5. 4 الحدود والمخبأ

حد المعدل لكل رمز/علامة تجارية/منطقة.

'ETag' للردود ؛ دعم «If-None-Match».

يعتمد مخبأ TTL على الدقة (على سبيل المثال، 5 م → TTL 60-120 ث).

6) الاحتفاظ والأفواج: القواعد وواجهة برمجة التطبيقات

6. 1 التعاريف (الاتفاقيات)

DAU/WAU/MAU: نشط إذا كان 'bet. وضعت 'أو' المحفظة. ائتمان (إيداع) جلسة 'или'. بدأت '≥ N دقائق.

المجموعة حسب الوديعة الأولى (غالبًا بالنسبة لـ LTV) أو عن طريق التسجيل (للمشاركة).

D1/D7/D30 الاحتفاظ: عادت النسبة من المجموعة إلى نافذة اليوم +/- التسامح حسب المنطقة الزمنية للعلامة التجارية.

نعتبر الزيارات المتكررة من قبل «player _ id» الفريد في النافذة.

6. 2 مجموعة واجهة برمجة التطبيقات


POST/v1/التحليلات/الاحتفاظ
{
"مجموعة": "first _ deposit", "start_date":"2025-09-01," end_date":"2025-09-30, "return_event":"bet. وضع، «أيام»: [1,7,14,30]، «مرشحات»: {«منطقة»: «الاتحاد الأوروبي»، «علامة تجارية _ هوية»: «علامة تجارية -7»}
}
→ 200 {
"مجموعة": "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 ؟ الفوج = الوديعة الأولى والعملة = اليورو والأفق = 90 د
→ 200 {«أفواج «: [{» تاريخ»:» 2025-09-01 «، «ltv _ minor «: [0,150,230,280،...]}}

7) دلالات المقاييس (لا تجادل)

المقاييس	التعريف (موجز)
GGR	مجموع (حصة) − مجموع (ربح) по 'رهان. استقر 'بالفترة/العملة
NGR	GGR − Bonus Expense − Jackpot Commissions − Commission
RTP	مجموع (ربح )/مجموع (حصة)
نجاح الودائع	أسر/نية (عامل)
تسوية التأخر	t (settled) − t (placed), percentele p95
تأخر الويب	t (ابتلع) − t (حدث), p95
DAU/WAU/MAU	عناصر فاعلة فريدة حسب قواعد النشاط

الكل - في التوقيت العالمي المنسق بالعملة والوحدات الثانوية ؛ يتم حل العملات المتعددة عن طريق تحويل العملات الأجنبية الثابتة إلى بحيرة البيانات.

8) النسخة والمرشحات والتوافق

المسار: '/v1/... '; مقاييس/حقول جديدة - اختيارية.

Фильтры: «العلامة التجارية _ id، المنطقة، provider_id، game_id، الطريقة، العملة، الجهاز، geo».

التثبيت: قائم على المؤشر («المؤشر التالي»).

كسر → فقط '/v2 '+ رفض/رؤوس غروب الشمس والتغيير.

9) الأمن والوصول

OAuth2 أوراق اعتماد العميل (رموز قصيرة العمر)، mTLS لـ B2B.

RBAC/ABAC: أذونات مترية/شريحة ؛ مرشح RLS حسب «العلامة التجارية/المنطقة».

PII: API لا يعطي PII، فقط المجاميع/المعرف الزائف إذا لزم الأمر.

الإقامة: توجيه الطلبات إلى المنطقة ؛ البيانات عبر المناطق - غير مسموح بها.

حدود الأسعار والحصص، ومكافحة إساءة الاستخدام ؛ مراجعة 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، نضارة rollup: p95 ≤ 2-5 دقيقة من 'حدث _ at'.
المقاييس: الكمون p50/p95/p99، معدل الخطأ (4xx/5xx)، ضرب المخبأ، الطلبات/الفحص البايت (OLAP)، تأخر النضارة لكل rollup 'y.
الجذوع: منظم، «تتبع _ معرف»، مرشحات استعلام (بدون PII)، عدد المسح.

11) النقد والحسابات الأولية والتكلفة

جداول Rollup: 1 م/5 م/1 ساعة/1 د بالمقاييس الرئيسية → «الجداول الزمنية» السريعة.

وجهات نظر ملموسة للأقسام/المجموعات الثقيلة.

ETag + الحد الأقصى للعمر ؛ تحدث الإعاقة في الأحداث المتأخرة بشكل متزايد.

الاستراتيجية «الساخنة/الباردة»: الاستفسارات الساخنة - في مستودع OLAP ؛ أرشيف - في بحيرة.

تقييد «بايت المسح» لكل طلب ؛ تلميحات للجدول.

12) تضمين وتصدير

أدوات مدمجة عبر URL/iFrame موقعة مع رموز RLS.

تصدير CSV/Parquet حسب المهمة (API الوظيفي) مع قيود الحجم والمراجع المؤقتة.

إشعارات Webhook حول جاهزية التحميل.

13) القوائم المرجعية

الهندسة المعمارية

مخطط حدث موحد، وسيففر، وسجل ؛ الجد بواسطة 'event _ id'.
آراء Rollup والمتجسدة لأعلى القضايا.
RLS/RBAC/ABAC، الإقامة، الرموز القصيرة الأجل.
المخبأ (ETag/TTL)، حدود الأسعار، الحصص.

دلالات

تم توثيق تعاريف GGR/NGR/RTP/DAU/الاحتفاظ.
العملات - الوحدات الثانوية ؛ يتم إصلاح FX في وقت الحدث.
الاحتفاظ من قبل UTC، مع مراعاة المنطقة الزمنية للعلامة التجارية في العرض.

العمليات

لوحات القيادة SLO/النضارة والكمون.
مراجعة WORM للوصول/الصادرات.
تمارين DR/xaoc: تأخر الدوران، سلسلة من الطلبات، الأحداث المتأخرة.

14) الأنماط المضادة (الأعلام الحمراء)

تُعطى جداول OLTP «الخام» مباشرة إلى API.

التعاريف المترية غير المتسقة بين الأوامر.

لا يوجد تفريغ وعلامات مائية → أحداث مزدوجة/مفقودة.

التجمعات غير المحدودة أثناء الطيران بدون مخبأ/حصص → طلبات باهظة الثمن وبطيئة.

التجميع عبر المناطق بدون سياسات الإقامة.

أعد تفاصيل PII/اللاعب إلى الردود العامة.

تغييرات كسر هادئة بدون «/v2 »و Deprecation.

15) مواصفات مصغرة (TL; DR)

الأحداث: '/v1/الأحداث: دفعة '(مرة واحدة على الأقل، التخلص من' event _ id').

التسلسل الزمني: '/v1/التحليلات/التسلسل الزمني ؟ (rollup + кэш).

الشرائح: '/v1/التحليلات/الشرائح ؟ متري =... & dim =... '.

القمع: '/v1/analytics/funnel' (نافذة، خطوات، مرشحات).

الاحتفاظ/المجموعات: '/v1/التحليلات/الاحتفاظ '(+ LTV).

الأمان: OAuth2 + mTLS، RLS، لكل علامة تجارية/رموز المنطقة، تدقيق WORM.

SLO: p95 ≤ 0. 5-2 ث ؛ النضارة ≤ 2-5 دقائق.

الإحصائيات والتحليلات APIs ليست «SELECT FROM، big_table» ولكنها عقد من المقاييس: أحداث مستقرة، ومجموعات مقروءة ومخبأة مسبقًا، والاحتفاظ والأفواج المحددة بدقة، والأمن (RLS/RBAC) والإقامة مفهومة من قبل SLO. لذا فأنت تقدم البيانات بسرعة وبتكلفة رخيصة وبشكل متوقع - للشركاء والمنتج و BI - دون تفسيرات مثيرة للجدل ودون خطر التسرب أو زيادة التخزين.