ادغام API چگونه بین استودیوها و سیستم عامل ها کار می کند

ادغام استودیو (ارائه دهنده بازی) با پلت فرم/جمع کننده زنجیره ای از تماس های همزمان و ناهمزمان در اطراف جلسه، کیف پول، نتیجه چرخش و تله متری رویداد است. در زیر یک نقشه مختصر اما عملی از چگونگی اتصال همه چیز بدون درد برای توسعه دهندگان و انطباق است.

1) معماری در کف دست شما

بازیگران:

استودیو RGS (از راه دور بازی سرور) - منطق بازی، RNG، پاداش، jackpots.
پلت فرم/جمع کننده - مسیریابی، صدور صورت حساب، تبلیغی، انطباق.
کیف پول اپراتور، KYC/RG، ویترین.
مشتری - ظرف بازی وب/موبایل (iframe/webview/native).

اتوبوس های اصلی:

همگام سازی API: جلسات، کیف پول، نتیجه.
Async/Event Bus: رویدادهای چرخش، پاداش، جکپات، RG، خطاهای فنی.
متادیتا/کاتالوگ: بازی ها، ساخت بازار، پروفایل های RTP، مکان ها.

2) پروتکل ها و راه حل های اساسی

حمل و نقل: HTTPS/JSON (گاهی اوقات gRPC برای اتوبوس رویداد/کیف پول).

نسخه بندی: 'Accept: application/vnd. آر جی اس. v1 + json 'or '/v1/...'; تخریب سازگاری - تنها از طریق نسخه های جدید.

شناسایی: 'game _ id'، 'build _ hash'، 'operator _ id'، 'session _ id'، 'round _ id'، 'spin _ id'.

زمان: به شدت UTC، ISO-8601 با میلی ثانیه.

ارزها: دقت ISO-4217 + (واحدهای جزئی). FX - طرف اپراتور/جمع کننده.

3) احراز هویت و مجوز

سرور به سرور: اعتبار مشتری HMAC- ('X-Signature: (payload, )').

جلسه پخش کننده: JWT کوتاه مدت (پلت فرم علائم) c 'sub'، 'geo'، 'rg _ flags'، 'exp'، 'aud = استودیو'.

لیست دسترسی: IP اجازه + mTLS برای حلقه های تولید.

4) مدل های کیف پول: بدهی/اعتباری در مقابل انتقال

الف) بدهی/اعتبار (در پرواز):

1. این پلت فرم RGS را فراخوانی می کند: «SpinRequest (stake)» → RGS نتیجه را محاسبه می کند.

2. به موازات, پلت فرم باعث می شود «بدهی (سهام)» و «اعتباری (برنده)» در محل اپراتور.

مزایا: حسابداری ساده. منفی: تماس های شبکه بیشتر، الزامات سخت برای idempotency.

ب) انتقال (تعادل جلسه):

1. در ابتدای جلسه، پلت فرم «transferIn (مقدار)» را در RGS انجام می دهد.

2. در طول چرخش، RGS خود تعادل جلسه ؛ پس از اتمام - 'transferOut (remaining)'.

مزایا: چت کیف پول کمتر. معایب: حسابداری برای «پول در کنار RGS»، خطرات و آشتی های اضافی.

توصیه ها:

برای اسلات، بدهی/اعتبار با کلیدهای idempotent اغلب استفاده می شود.

در چرخش آزاد و مسابقات آن است که مناسب به انواع شرط جداگانه 'spin _ type = رایگان	تبليغات.

5) بی نظمی و سازگاری

هر مرحله پول باید یک «idempotency _ key» منحصر به فرد (به عنوان مثال، «round _ id» یا «spin _ id») داشته باشد.

تکراری («HTTP 409/425») نتیجه مشابهی را نشان می دهد، نه «خطایی که قبلا اجرا شده است».

دقیقا یک بار برای رسیدن به آن دشوار است، بنابراین ما حداقل یک بار + idemotency ایجاد می کنیم.

Idempotence به «بدهی»، «اعتبار»، «جکپات _ مشارکت»، «پاداش _ جایزه» گسترش یافته است.

6) طرح پرس و جو کلیدی (به اختصار)

6. 1. آغاز جلسه

جی سون
POST/rgs/v1/جلسات
{
" :" s-...، " :" op- "...،" : "p-"...، "sha256:...،" jwt ":" eyJhbGci "...،" geo ":" DE "،" ارز ":" EUR "،" EU ": {" خود "_ حذف شده": غلط "، : 60}
}

6. 2. چرخش (بدهی/اعتباری)

جی سون
پست/rgs/v1/چرخش
{
"spin_id": "... اسپین-"، "round_id": "rnd-"...، "session_id": "s-"...، "سهام": {"مقدار": 1. 00، «ارز»: «EUR»} «، spin_type": «پول نقد»، «idempotency_key": «spin-»...
}

پاسخ:

جی سون
{
"spin_id": "... اسپین-"، "نتیجه": {
«win»: {«مقدار»: 3. 40, «ارز»: «EUR»} «, ویژگی های»: [{«نوع «: «پاداش _ ماشه «, «نام»:» FreeSpins»,» تعداد»: 10}], «نمادها»: «مات و یا حذف شده»
"rgs_txns":
{«نوع «: «جک پات _ مشارکت»،» مقدار»: 0. 01}
]، "telemetry_ref": "evt-"..
}

6. 3. اتوبوس رویداد

جی سون
POST/rgs/v1/رویدادها/دسته ای
{
«حوادث»: [
{
«نوع»: «spin _ finished», «ts»: 2025-10-20T11: 22:33. 123Z," "spin_id":"spin-...," "round_id":"rnd-...," "سهام": 1. 00، «برنده شدن»: 3. 40، «ارز»: «EUR»، «game_id":"g-...,""build_hash":"sha256:...,» player_id":"p-...,""operator_id":"op-..., «spin_type":"cash»
}
]
}

7) ساخت نسخه و ساخت بازار

'build _ hash' (SHA-256) - مورد نیاز در هر رویداد.

ساخت جهانی در مقابل بازار: زبان، هشدارها، محدودیت نرخ، مشخصات RTP.

این پلت فرم تأیید می کند: «ساخت در حال حاضر در حال پخش است که با گواهی یک کشور مشخص مطابقت دارد».

ماتریس: 'game _ id کشور .

8) RNG، ریاضی و پخش

RNG در RGS زندگی می کند ؛ منطق کسب و کار شانس پرواز را تغییر نمی دهد.

برای پزشکی قانونی: 'دانه/nonce' در هر دور/چرخش + نسخه مکانیک.

تکرار: با «spin _ id »/« seed»، RGS نتیجه را بازتولید می کند و یک دنباله حسابرسی می دهد.

9) بازی مسئولانه (RG) و قلاب های انطباق

قلاب از زمان/محدودیت: 'session _ time _ ms', «یادآوری», وقفه; 'rg _ event' در اتوبوس رویداد.

خود حذفی/بلوک: با پرچم - فوری '403 RG_BLOCKED'.

UI invariants: پلتفرم بررسی می کند که مشتری هشدارها/برچسب های سن را از ساخت بازار نشان می دهد.

10) اشکالات، Retrays و SLA ها

کدهای: «400» (اعتبار سنجی)، «401/403» (احراز هویت/RG)، «409» (تعارض idempotency)، «422» (خطای کسب و کار)، «429» (حد نرخ)، «5xx» (موقت).

سیاست Retray: نمایی، با کلید idempotent و deduplication در گیرنده.

SLA ≥99 در دسترس بودن API. 9٪، تاخیر p95 برای «چرخش» ≤200 -300 ms (منطقه ای)، اتوبوس رویداد - نزدیک به زمان واقعی <60 ثانیه.

11) قابلیت مشاهده و حسابرسی

سیاهههای مربوط: سیاهههای مربوط به سرور قطع نشده با همبستگی 'trace _ id'.

معیارهای: p95/p99 تاخیر، میزان خطا توسط روش، انحراف از فرکانس RTP/پاداش، نسبت «چرخش الاستیک».

هشدارها: توسط SLA، توسط ناهنجاری های ریاضی، با افزایش خرابی کیف پول.

حسابرسی: ذخیره سازی WORM برای رویدادهای شرط بندی/نتایج ؛ صادرات بر اساس تقاضا

12) ایمنی

mTLS + TLS 1. 2 +، HSTS، CORS سخت در لودر مشتری.

چرخش کلید، نشانه TTL کوتاه، چک JTI/نانس.

Anti-tamper برای مشتری: امضای دارایی، بررسی یکپارچگی، حفاظت از اشکال زدایی.

اسرار - فقط در مدیر مخفی ؛ هیچ «کلیدی در پیکربندی بازی».

13) محیط آزمایش و صدور گواهینامه

Sandbox: کیف پول ساختگی، RNG قطعی (بذر ثابت)، شکست خودکار سناریوهای RG.

مرحله بندی: یک کپی از prod-infra بدون پول واقعی.

بسته بندی برای آزمایشگاه ها: GDD/ریاضیات، پرونده RNG، نمودارهای ورود به سیستم، ساخت قابل تکرار و هش ها.

14) تبلیغات و جکپات در API

چرخش آزاد: انتقال بسته: 'grant _ free _ spins (count, bet_size, rtp_profile?); رویدادها در RGS صرف و ثبت شده است.

مسابقات: ویژگی 'spin _ type = tournament' + aggregates فردی در اتوبوس رویداد.

جکپات: 'jackpot _ contribution' و 'jackpot _ win' به عنوان معاملات جداگانه ؛ سازگاری از طریق idempotency و «امضا» حوادث.

15) گزارش و صورتحساب

Блоки выгрузок: 'چرخش _ کل'، 'واجد شرایط _ چرخش'، 'گردش مالی'، 'ggr'، 'در'، 'برنده تمام پولها _'، 'پاداش _ هزینه'، 'حق امتیاز _ به دلیل'.

Per-spin/turnover-fee: account by «eligible _ spins» or «نرخ Σ سهام ×».

Rev-share: از «NetWin» پس از «آبشار» نگه می دارد ؛ سه ماهه واقعی برای FX/استثنا.

16) توالی های معمولی (نمودار کلمه)

چرخش (بدهی/اعتباری):

مشتری → بستر های نرم افزاری: StartRound → بستر های نرم افزاری → RGS: چرخش → RGS → بستر های نرم افزاری: نتیجه → بستر های نرم افزاری → کیف پول: بدهی → بستر های نرم افزاری → مشتری: نتیجه → بستر های نرم افزاری → EventBus: spin_finished.

چرخش آزاد:

بستر های نرم افزاری → RGS: GrantFreeSpins → مشتری: شروع → RGS: مصرف/ورود به سیستم هر → EventBus: spin_finished (spin_type=free).

17) تغییر مدیریت و قابلیت همکاری

قرارداد اول: OpenAPI/Protobuf یک منبع واحد از طرح است.

SemVer: فقط فیلدها را اضافه کنید حذف/تغییر - در/v2.

ویژگی پرچم فعال کردن گزینه (پاداش خرید/آنتی) از طریق پروفایل های گواهی تنها.

رد: اعلام → دوره فضل → خاموش کردن در مناطق غیر فعال است.

18) چک لیست

استودیو → پلت فرم

مشخصات OpenAPI/gRPC و بارهای نمونه.
IDempotency 'spin/debit/credit/jackpot'.
'build _ hash' و بازار رجیستری را ایجاد می کند.
کپی RNG و گزارش حسابرسی.
RG قلاب و خطاهای 403 RG_BLOCKED'.
Sandbox با ثابت بذر، کیف پول تست و اسکریپت های خودکار.

سکو → استودیو

امضای JWT با TTL کوتاه، allowlist IP، mTLS.
اعتبار دهنده ساخت و گواهی های بازار.
اتوبوس رویداد و داشبورد (تاخیر/خطا/رانش RTP).
سهمیه ها و محدودیت های نرخ با بازخورد صادقانه «429-Retry-After».
SLAs/حوادث/لینک ها 24 × 7.

19) طرح راه اندازی 30-60-90

0-30 روز

در مورد قراردادهای API و طرح های رویداد توافق کنید، یک مدل کیف پول را انتخاب کنید.

بالا بردن sandbox: RNG ثابت بذر، کیف پول تست، autotests از idemotency.

Registry 'build _ hash' و بازار ماتریس اولیه ایجاد می کند.

31-60 روز

ادغام کیف پول و چرخش ؛ اتوبوس رویداد و داشبورد را فعال کنید.

تست بار (p95/p99)، retrai/idempotency، سناریوهای هرج و مرج شبکه.

انطباق: RG-hooks، locales، age-labels ؛ بسته به آزمایشگاه

61-90 روز

خلبان برای 1-2 اپراتورها, A/B برای تبلیغی (چرخش آزاد/مسابقات).

وارد کردن درست به بالا/گزارش, RTP هشدار رانش/پاداش freq.

آماده سازی پیشرفت های v2: رویدادهای دسته ای، gRPC برای کیف پول، مسیریابی جغرافیایی.

20) سوالات متداول کوتاه

کجا RTP/نسخه بررسی می شود ؟ در پلت فرم: 'build _ hash' ↔ گواهی ↔ کشور.

آیا می توان RTP را به صورت پویا تغییر داد ؟ نه، اينطور نيست فقط پروفایل های از پیش تأیید شده و فقط ساخت بازار سوئیچینگ.

چگونه «بدهی دوگانه» را حل کنیم ؟ کلید Idempotent + ذخیره سازی وضعیت معامله ؛ redo-نتیجه را برمی گرداند.

آیا به gRPC نیاز دارم ؟ مفید برای کیف پول/حوادث در حجم بالا ؛ REST برای پانل متادیتا/مدیریت باقی می ماند.

ادغام پایدار قراردادها + idempotency + مشاهده پذیری است. طرح های رویداد شفاف، ساخت/کنترل بازار، قلاب RG و نظم و انضباط نسخه 90٪ از خطرات را در ابتدا حذف می کند. علاوه بر این - اتوماسیون تبلیغی و گزارش, SLA سخت و توسعه دقیق API بدون «شکستن» تغییرات.