آمار و تجزیه و تحلیل API ها: رویدادها، Aggregates، نگهداری

مقاله کامل

💡 18+. تجزیه و تحلیل مهندسی برای سیستم عامل ها/اپراتورها، استودیوها (RGS/live) و تیم های BI/CRM. فراخوانی برای بازی نیست.

1) چرا API تحلیلی خارجی

همکاران/ارائه دهندگان: نظارت بر محتوای SLA، RTP، تعامل.

بازاریابی/CRM: کمپین های ماشه بر اساس معیارها (DAU، قیف سپرده).

عملیات/امور مالی: نزدیک به زمان واقعی GGR/NGR، موفقیت پرداخت، وب سایت عقب مانده است.

محصول: ویجت های آماری درون برنامه، پانل های A/B.

هدف این است که با خیال راحت و قابل پیش بینی به عقب حوادث و aggregates با معانی قابل فهم و SLA ها.

2) معماری بر روی انگشتان


تولید کنندگان (PAM/کیف پول/RGS/پرداخت/کافکا/CDC)
│
مصرف API ──Stream (کافکا/پولسار) ──Lakehouse (دلتا/کوه یخ)
│ └─OLAP (ClickHouse/BigQuery/Trino)
رابط برنامه نویسی └────────────────────────────────────Aggregation/Query
(کش، RBAC/RLS، محدودیت نرخ)

رویدادها: حداقل یک بار، پدربزرگ توسط «event _ id/idempotency _ key».

Aggregates: رول آپ از پیش محاسبه شده (1m/5m/1h/1d) + در پرواز.

Retenchen: موتور کوهورت در بالای Gold Marts.

Кэш: CDN/edge + ETag/' Cache-Control '، TTL سمت سرور.

3) مدل رویداد: حداقل استاندارد

3. 1 زمینه های مشترک

جی سون
{
«event_id":"uuid,» event_type":"bet حل و فصل «،»  « »  «منطقه»: «اتحادیه اروپا»
«trace_id":"tr_a1b2c3,» schema_version":"1 3. 0"، "بارگیری": {...}
}

قوانین: برچسب زمانی UTC، 'player _ id' - نام مستعار، پول در واحد های جزئی.

3. 2 انواع کلیدی

به سلامتی. شروع کرد	تمام شد
خوب شد. قرار داده شده	حل و فصل ( ، ، )
تمام شد. بدهی	اعتبار (دلیل، reference_id)
حق الزحمه. قصد	مجاز است
سلام. صادر شده	مصرف شده
آ ره. محدود کردن ضربه بزنید	reality_check'
نسخه - نیمه تمام ؛ اضافه کردن فقط اختیاری است.

4) مصرف API (برای منابع شخص ثالث)

ارسال یک دسته از حوادث


POST/v1/رویدادها: دسته ای
هدر: X-idempotency-کلید: ev_20251023_001
[
{«event _ id»:... «،» event _ type «:» شرط. قرار داده شده،...}، {«event _ id»: «...،» event _ type «:» شرط. مستقر شد"..
]
→ 202 {«پذیرفته شده»: 2، «تکراری»: 0، «trace_id":"tr_a1b2»}

گارانتی: حداقل یک بار ؛ تکراری در نقره توسط «event _ id» فیلتر می شود.

5) API جمع آوری: سری زمانی و برش

5. 1 Timeseries (معیارهای زمان)


GET/v1/تجزیه و تحلیل/timeseries
? متریک = ggr//ggr, ngr, dau, deposits_success, rtp
& دانه دانه = 5m//1m/5m/1h/1d
& از = 2025-10-22T00: 00: 00Z & به = 2025-10-23T00: 00: 00Z
& filters = region: EU, brand _ id: نام تجاری 7, provider _ id: studio _ x
& گروه _ بر اساس = نام تجاری _ شناسه
→ 200 {
«متریک»:» ggr»، «دانه دانه»:» 5m»، «سری»: [
{«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/تجزیه و تحلیل/تکه
? metric = rtp & dim = game _ id & from = 2025-10-22 & to = 2025-10-23
& حد = 50 & سفارش = - مقدار
→ 200 {«موارد «: [{«game _ id»:» g _ 01»،» ارزش»: 0. 956},...] }

5. 3 قیف


POST/v1/تجزیه و تحلیل/قیف
{
«قدمها»:
{"رویداد ":" پرداخت. قصد»}، {«رویداد «:» پرداخت. مجاز "}"، {"رویداد": "پرداخت. "}"، {"رویداد": "کیف پول. اعتبار"، "دلیل ": "سپرده"}
] ", window_sec": 3600 ", filters ": {"region ": "EU"," brand _ id":" brand-7 "}
}
→ 200 {
«کل»: 12450، «مراحل»: [
{«نام «:» قصد»، «شمارش «: 12450، «نرخ»: 1. 0}، {«نام «: «مجاز»، «شمارش «: 11020، «نرخ»: 0. 885}، {«نام «: «اسیر»، «شمارش «: 10110، «نرخ»: 0. 811}، {«نام «: «اعتبار»، «شمارش «: 10050، «نرخ»: 0. 807}
]
}

5. 4 محدودیت ها و کش

محدودیت نرخ در هر نشانه/نام تجاری/منطقه.

"ETag 'به پاسخ ؛ 'If-None-Match' پشتیبانی می کند.

حافظه نهان TTL به گرانروی بستگی دارد (به عنوان مثال، 5m → TTL 60-120 s).

6) نگهداری و گروه ها: قوانین و API

6. 1 تعاریف (قراردادها)

DAU/WAU/MAU: active if was 'bet. قرار دادن «یا» کیف پول. جلسه «или» اعتباری (سپرده). ≥ دقیقه شروع کرد.

کوهورت توسط سپرده برای اولین بار (اغلب برای LTV) و یا با ثبت نام (برای دخالت).

D1/D7/D30 نگهداری: نسبت از گروه به پنجره روز +/- تحمل با منطقه زمانی نام تجاری بازگشت.

ما بازدیدهای مکرر توسط «player _ id» منحصر به فرد در پنجره را در نظر می گیریم.

6. 2 گروه های API


POST/v1/تجزیه و تحلیل/نگهداری
{
"کوهورت": "first _ deposit"، "start_date":"2025-09-01," end_date":"2025-09-30, "return_event":"bet. قرار داده شده"، "روز ": [1,7,14,30]، "فیلتر ": {"منطقه ": "اتحادیه اروپا"،" نام تجاری _ id":" نام تجاری 7 "}
}
→ 200 {
«کوهورت «: «اول _ سپرده», «ردیف»: [
{«cohort _ date»:» 2025-09-01 «، «اندازه «: 1820،» d1»: 0. 36، «d7»: 0. 22، «d14»: 0. 18، «d30»: 0. 12}، {«cohort _ date»:» 2025-09-02 «، «اندازه «: 1714،» d1»: 0. 35، «d7»: 0. 23، «d14»: 0. 19، «d30»: 0. 13}
]
}

6. 3 LTV/تجمعی


GET/v1/تجزیه و تحلیل/ltv ؟ کوهورت = اولین _ سپرده و ارز = EUR و افق = 90d
→ 200 {«گروه ها «: [{» تاریخ»:» 2025-09-01 «، «ltv _ minor «: [0,150,230,280،...]}}

7) معانی متریک (نه به استدلال)

معیارهای اندازه گیری	تعریف (مختصر)
جی جی آر	شرط sum (stake) − sum (win) по ' حل و فصل در دوره/ارز
ان جی آر	GGR − هزینه پاداش − مشارکت برنده تمام پولها − کمیسیون
دستگاه RTP	sum (برد )/sum (قمار)
موفقیت سپرده گذاری	اسیر/قصد (عامل)
حل و فصل تاخیر	t (حل و فصل) − t (قرار داده شده)، صدک p95
وب هوک تاخیر	t (مصرف شده) − t (رخ داده است)، p95
DAU/WAU/MAU	بازیکنان فعال منحصر به فرد با قوانین فعالیت

همه - در UTC با واحد پول و واحد جزئی ؛ چند ارزی با تبدیل FX ثابت به Data Lake حل می شود.

8) نسخه، فیلتر و سازگاری

مسیر: '/v1/... '; معیارها/فیلدهای جدید - اختیاری

Фильтры: 'brand _ id، region، provider_id، game_id، method، currency، device، geo'.

صفحه بندی: مکان نما بر اساس ('next _ cursor').

شکستن → تنها '/v2 '+ هدر رد/غروب آفتاب و changelog.

9) امنیت و دسترسی

OAuth2 اعتبار مشتری (نشانه های کوتاه مدت)، mTLS برای B2B.

RBAC/ABAC: مجوزهای متریک/برش ؛ RLS بر اساس «نام تجاری/منطقه» فیلتر می شود.

PII: API PII را نمی دهد، فقط در صورت لزوم aggregates/pseudo-ID را می دهد.

اقامت: درخواست مسیریابی به منطقه ؛ داده های متقابل منطقه - مجاز نیست.

محدودیت ها و سهمیه های نرخ، ضد سوء استفاده ؛ بررسی دسترسی های WORM

10) SLO و قابلیت مشاهده

معیارهای SLO:

'GET/timeseries gran = 5m' p95 500-800 ms، 'GET/slice' p95 1-2 s (حداکثر تا 50-100 موقعیت)، 'POST/retention' (ماه از گروه ها) p95 3-5 s، rollup طراوت: p95 2-5 دقیقه از 'رخ داده است _ at'.
معیارهای: تاخیر p50/p95/p99، نرخ خطا (4xx/5xx)، حافظه پنهان، درخواست/بایت اسکن (OLAP)، تاخیر طراوت برای هر rollup 'y.
سیاهههای مربوط: ساختار یافته، 'trace _ id'، فیلترهای پرس و جو (بدون PII)، تعداد اسکن.

11) پول نقد، محاسبات اولیه، هزینه

جداول رول آپ: 1m/5m/1h/1d با معیارهای کلیدی → سریع «timeseries».

دیدگاه های تحقق یافته برای بخش های سنگین/گروه ها.

ETag + حداکثر سن ؛ معلولیت در حوادث دیررس به طور تدریجی اتفاق می افتد.

استراتژی «گرم/سرد»: نمایش داده شد گرم - در OLAP-انبار ؛ بایگانی - در دریاچه.

محدودیت «اسکن بایت» در هر درخواست ؛ به زمانبندی اشاره میکند.

12) جاسازی شده و صادرات

ساخته شده در ویدجت از طریق URL امضا/iFrame با نشانه RLS.

صادرات CSV/پارکت توسط وظیفه (API کار) با محدودیت اندازه و منابع موقت.

اطلاعیه های Webhook در مورد آمادگی آپلود.

13) چک لیست

معماری و معماری

طرح رویداد یکپارچه، semver، رجیستری ؛ پدربزرگ با 'event _ id'.
Rollup و دیدگاه های تحقق یافته برای موارد بالا.
RLS/RBAC/ABAC، اقامت، نشانه های کوتاه مدت.
کش (ETag/TTL)، محدودیت نرخ، سهمیه.

معناشناسی

تعاریف GGR/NGR/RTP/DAU/احتباس مستند شده است.
ارزها - واحدهای جزئی ؛ FX در زمان رویداد ثابت شده است.
نگهداری توسط UTC، با در نظر گرفتن منطقه زمانی نام تجاری در صفحه نمایش.

عملیات ها

داشبورد SLO/طراوت و تاخیر.
ممیزی WORM از دسترسی/صادرات.
تمرینات DR/xaoc: عقب ماندگی، عجله از درخواست ها، رویدادهای اواخر.

14) ضد الگوهای (پرچم قرمز)

جداول OLTP «خام» به طور مستقیم به API داده می شود.

تعاریف متریک متناقض بین دستورات.

بدون deduplication و علامت های سفید → رویدادهای دوگانه/از دست رفته.

تجمع نامحدود در پرواز بدون کش/سهمیه → درخواست های گران قیمت و کند.

تجمع بین منطقه ای بدون سیاست های اقامت

جزئیات PII/بازیکن را به پاسخهای عمومی برگردانید.

شکستن آرام تغییرات بدون «/v2 »و تخفیف.

15) مینی مشخصات (TL ؛ دکتر)

Events: '/v1/events: batch '(حداقل یک بار, dedup by' event _ id ').

Timeseries: '/v1/analytics/timeseries? متریک =... و دانه دانه بودن = "... (رول آپ + кэш).

برش ها: "/v1/تجزیه و تحلیل/تکه ؟ متریک =... & کم نور =... '.

قیف: '/v1/analytics/funnel '(پنجره، مراحل، فیلترها).

حفظ/کوهورت :/v1/تجزیه و تحلیل/حفظ (+ LTV).

امنیت: OAuth2 + mTLS، RLS، در هر علامت تجاری/منطقه، حسابرسی WORM.

SLO: p95 ≤ 0 5-2 ثانیه ؛ طراوت ≤ 2-5 دقیقه.

APIهای آمار و تجزیه و تحلیل «SELECT FROM، big_table» نیستند، بلکه قراردادی از معیارها هستند: رویدادهای پایدار، سنگدانه های از پیش خوانده شده و ذخیره شده، نگهداری و گروه های کاملاً تعریف شده، امنیت (RLS/RBAC) و اقامت قابل درک توسط SLO. بنابراین شما داده ها را به سرعت، ارزان و قابل پیش بینی - به شرکا، محصول و BI - بدون تفسیر بحث برانگیز و بدون خطر نشت یا اضافه بار ذخیره می کنید.