دمج روبوتات Telegram و WebApp مع النظام الأساسي

1) لماذا Telegram في iGaming

الوصول والاحتفاظ: حوارات الدفع السريع (إشعارات البطولة/المهمة، والحالات، والعروض الترويجية).

تسجيل الدخول السهل: SSO عبر Telegram Login Widget/WebApp «initData» بدون كلمة مرور.

العميل المصغر: WebApp داخل Telegram مع السمة/الأزرار الأصلية ونقل السياق الآمن.

💡 مهم: لا تنقل «ميكانيكا الألعاب مقابل المال» داخل الروبوت. استخدم Telegram كقناة مصاحبة: الإشعارات، الملف الشخصي، CUS/statuses، البطولات/لوحات الصدارة، العرض الترويجي، الدعم، تدفق الإحالة. المعاملات المالية - في خزانة/تطبيق ويب مع KYC/AML و PSP بالكامل.

2) بنية التكامل

المكونات:

1. Telegram Bot (Bot API): معالجة التحديثات (webhook)، الأوامر/لوحات المفاتيح، الروابط العميقة «/حمولة البداية ».

2. Telegram WebApp (TWA): صفحة الويب داخل Telegram (WebView داخل التطبيق)، وتتلقى «initData» وتتكامل مع Telegram UI.

3. بوابة منصة Auth/SSO: التحقق من توقيع «initData »/Login Widget، إصدار المنصة قصيرة العمر JWT.

4. منصات واجهة برمجة التطبيقات الخلفية: الملف الشخصي/المحفظة/البطولات/البعثات/الشركات التابعة/الدعم.

5. حافلة الأحداث: الإخطارات (كافكا/ريديس ستريمز) → إرسال الرسائل بواسطة الروبوت.

6. الملاحظة والأمن: WAF، mTLS إلى الويب، حد السعر، التدقيق، التنبيه.

تدفق SSO (قصير):

Telegram (WebApp/Login) → «initData »/auth-bood → بوابة Auth تتحقق من HMAC → تصدر JWT (5-15 دقيقة) → WebApp/bot platform API مع Jwith.

3) طرق الترخيص

أ) Telegram WebApp (نافذة. برقية. WebApp ')

تحل Telegram محل «initData» في WebApp. قم بتوقيعه على الخادم HMAC-SHA256 مع مفتاح رمز الروبوت.

إذا نجحت، قم بإصدار JWT قصير و (إذا لزم الأمر) قم بربط حساب Telegram الخاص بك بملف تعريف موجود.

التحقق من صحة الرمز الزائف «initData»:

python def verify_init_data (init_data: str، bot_token: str) -> dict:
init_data - سلسلة تشبه الاستعلام «key1 =.. & key2 =».
البيانات = parse_qs (init_data)
hash_provided = البيانات. البوب («هاش») [0]
check_string = '\n '.join ([f «{k} = {v [0]}» لـ k في الفرز (البيانات. المفاتيح ())])
secret = hmac. جديد (ب «WebAppData»، bot_token. (sha256). موجز ()
calc = hmac. جديدة (سرية، check_string. (sha256). hexdigest ()
تأكيد hmac. compare_digest (كالك، hash_provided)
تحقق من نضارة auth_date (على سبيل المثال، ≤ 10 دقائق)
تؤكد الآن () - int (البيانات ['auth _ date'] [0]) <600 بيانات إرجاع

ب) Telegram Login Widget (صفحة خارجية)

تعطي الودجة «هوية، first_name، auth_date، هاش». الشيك مشابه («Telegram Login» + bot_token').

مناسب إذا كنت لا تستخدم WebApp، ولكن أدخل خزانة ويب عادية.

4) الربط بين الحسابات ونموذج الهوية

المفتاح الأساسي: "telegram _ user _ id' ('from. id ').

نقوم بإنشاء سجل ملزم: «النظام الأساسي _ المستخدم _ معرف اسم المستخدم (غير قابل للإلغاء)» + سمات الموافقة (التسويق/الإشعارات).

استراتيجيات الربط/عدم الربط:

→ للمستخدم الجديد إنشاء ملف تعريف مبسط، يرجى تأكيد الهاتف/البريد الإلكتروني في المكتب.
الرابط العميق الحالي → '/رابط البداية: «أو WebApp مع» start _ param'، افتح الوسيلة للربط.
فتح - من خلال الإعدادات، نلغي على الفور القدرة على دفع الإشعارات.

5) روبوت الويب: السلامة والاستدامة

HTTPS + مجال ثابت، mTLS (إن أمكن) ومسار سري صالح ('/bot/< token>)، أو سره الخاص في الرأس.

تقييد IP: القائمة البيضاء Telegram IP (إذا سمحت البنية التحتية)، قواعد WAF.

الخصوصية: احتفظ بـ «تحديث _ معرف»، معالجة مرة واحدة بالضبط.

Retrai: يتكرر Telegram عند 5xx/timeout - استمر في المعالجة <1 s، ثقيل - في الطابور.

حدود الأسعار: دلاء رمزية محلية لإرسال الرسائل (حدود Telegram البريد العشوائي)، قوائم الانتظار للبريد الجماعي.

إطار عامل المثال:

ثعبان
@ التطبيق. («/telegram/webhook »)
def on_update (u: Update):
إذا شوهد (ش. update_id): العودة «موافق»
قائمة الانتظار. نشر ("tg. تحديثات،" u. json ()) # async يستهلك mark_seen (u. update_id)
العودة «حسنا»

6) الروابط العميقة ومعايير البدء والإحالة

عرض المرجع: 't. me/< bot> ؟ ابدأ = <حمولة> '(تصل إلى 64 بايت ~ من الحمولة في base64url).

استخدم الحمولة كحمولة لمرة واحدة من أجل:

حملات الإحالة ('aff _ id'، 'campaign _ id'، 'click _ id')، استمرار التدفق غير المكتمل (خطوة KYC، المهمة، البطولة)، ربط الحساب.
تحافظ على عدم الامتثال → intended_action → expires_at'، وتقوم باستخدام واحد.
لـ WebApp - 't. me/< bot >/التطبيق ؟ startapp = <حمولة> '(ادخل' initData. start_param').

7) Telegram WebApp: UX والتكامل

ميزة TWA:

Тема ("themeParams')، mainButton/secondaryButton، BackButton،" HapticFeedback "،" توسيع ()، "viewport'.
التبادل الثنائي: برقية. WebApp. ستصل → SendData () في تحديث الروبوت ؛ أو يتصل WebApp بواجهة برمجة التطبيقات Backend الخاصة بك مباشرة مع JWT المستلم.

التوصيات:

السمة الفاتحة/المظلمة تلقائيًا من "themeParams'.
لا تخزن «initData» في المتصفح لأكثر من 10 دقائق ؛ قم بتحديث JWT بنقطة نهاية تحديث (لكل جلسة خادم).
عملية إغلاق WebApp (على سبيل المثال، إرسال تأكيد العمل للدردشة).
احترم قيود WebView: CSP، https فقط، الأحجام، لا النوافذ المنبثقة.

مثال مصغر على الاستهلال:

js const tg = النافذة. برقية. WebApp ؛
tg. جاهزة () ؛
tg. والتوسع () ؛
const initData = tg. initData ؛//أرسل إلى ظهرك لاستبدال JWT tg. الزر الرئيسي. Set Text («تابع»). (). onClick (() => submission ()) ؛

8) التدفق النموذجي

الملف الشخصي/المحفظة (عرض)

يفتح المستخدم WebApp → التحقق «initData» → إصدار JWT → يعرض الأرصدة، وحالات CUS/حدود اللعبة المسؤولة، وسجل المعاملات (القراءة فقط).

البطولات/البعثات

في TWA، نظهر لوحات الصدارة وتقدم المهمة (في الوقت الفعلي، استطلاع قصير/WS عبر الخلف).

الأزرار: «شارك»، «شارك» (رابط عميق للأصدقاء)، «أشعر قبل 5 دقائق من البداية».

إشعارات

أحداث المنصة → حافلة الأحداث → يقوم المستهلك بإنشاء لوحة مفاتيح نصية/داخلية → "إرسال رسالة" مع "inline _ keyboard' (رابط" Open WebApp "أو رابط عميق).

دعم اختيار الاشتراك/إلغاء الاشتراك في أنواع الإشعارات (البطولات والإخراج والمكافآت).

الدعم

التذكرة السريعة/الأسئلة الشائعة في زر WebApp + «افتح الدردشة مع المشغل».

التحقق من المستخدم (SSO)، وتشديد سياق الدورة/الإيداع الأخيرة.

9) جوانب الدفع والامتثال

المعاملات المالية (الودائع/عمليات السحب) - إلى خزانة ويب مفتوحة من بوت (زر URL) أو من WebApp (زر «انتقل إلى الخزانة»).

داخل TWA، اسمح بعمليات القراءة الآمنة فقط والإجراءات «السهلة» (الروابط والتنشيطات الترويجية والبطولات).

الخصوصية: لا تتحدث مع PII ؛ أظهره فقط داخل WebApp (https، تصريح).

سجلات الموافقة، سياسة الاحتفاظ، «الحق في الحذف» - في الملف الشخصي.

10) مكافحة الروم والحماية

تحقق من شذوذ «auth _ date» والمناطق الزمنية/ASN.

الحد الأقصى للمعدل بواسطة «telegram _ user _ id» و IP للعمليات الحساسة (تفعيل الترويج، الإحالة).

حماية الروابط العميقة: رموز لمرة واحدة، TTL قصيرة، ربط المستخدم/الدردشة.

للبريد الجماعي - دفعة + نفث، تحقق من «رائع» للحصول على الشكاوى/الحظر.

التحقق من الملفات/الوسائط من الدردشات (إذا قبلت المستندات): قم بالتنزيل من خلال Bot API بواسطة 'file _ id'، وتحقق من النوع/الحجم/الفيروسات، وتخزينها في حلقة الامتثال.

11) قابلية الملاحظة والتنبيهات والحدود

المقاييس:

"tg _ webhook _ latency"، "webhook _ 5xx"، "قائمة الانتظار _ lag"، "send _ rate"، "flood _ wait _ hits'.
SLI WebApp: «auth _ verify _ success'،» jwt _ issue _ latency _ p95 «،» api _ 4xx/5xx «،» leadboard _ rtt'.
التحويل: فتح → الإذن → العمل المستهدف (المهمة/البطولة/العودة إلى المكتب).

تنبيهات:

خطأ التحقق من التوقيع> X٪ في 5 دقائق
"FloodWait'/429 عند إرسال الرسائل.
نمو «deep _ link _ reuse» أو أخطاء رمزية لمرة واحدة.

Logs: JSON with 'trace _ id', 'telegram _ user _ id' (اسم مستعار), without PII; ارتبط بمسارات المنصة.

12) عقود API (رسومات)

تبادل «البيانات الداخلية» لـ JWT

http
POST/v1/tg/exchange
{"init_data": "<سلسلة>"}
→ 200 {«jwt':» <قصير العمر>، «» expires_in":900}

الملف الشخصي

http
احصل على/v1/tg/me
الإذن: حامل <jwt>
→ 200 {«user_id":"u_123,» «الأرصدة»: [...]، «kyc «: {«المستوى»:» الأساسي»}}

اشتراكات الإخطار

http
POST/v1/tg/consents
{«ترقيات»: صحيح، «بطولات»: صحيح، «مدفوعات»: صحيح}

التوزيع (الخدمة الداخلية)

جسون
{
«قالب»: «البطولة _ البداية»، «vars': {» الاسم «:» Halloween Sprint'، «يبدأ _ في»: «5m»}، «الأهداف»: [{«chat _ id»: 12345، «المستخدم _ id»: «u _ 123»}]
}

13) أمثلة على واجهة المستخدم في الروبوت

«بطولة» لوحة المفاتيح الداخلية

جسون
{
inline_keyboard": [
[{«نص»: «Open Leadboard'،» web _ app «: {» url «:» https ://twa. مثال/مسابقة ؟ id = october»}}]، [{«نص «: «قواعد «، «url»:» https ://brand. com/contests/october/rules"}]
]
}

لوحة مفاتيح الرد «القائمة الرئيسية»

الملف الشخصي

البطولات والبعثات
المكافآت والعروض الترويجية
دعم العملاء

14) الحجم وتحمل الخطأ

خطاف شبكي → طابور → العمال (عديمي الجنسية) ؛ المقياس الأفقي.

قم بتخزين «حالة الحوار» في Redis/DB (آلة الحالة المحدودة لكل 'chat _ id').

آلية النسخ الاحتياطي getUpdates (استطلاع طويل) فقط للتنقيح/الفولباك.

الحد من سرعة الإرسال («رسائل/ثانية») وحجم رسائل الفطور المتأخر ؛ مخطط الموجات.

DR: رمز/نسخة احتياطية سرية، نقطة نهاية الويب الثانوية، نص «التبديل السريع».

15) قائمة التسليم المرجعية

Webhook HTTPS، secret/mTLS، retry-security، idempotency 'update _ id'.
التحقق من التوقيع «initData »/Login Widget، نافذة النضارة، استبدال JWT قصير.
حساب Link/unlink، تخزين 'telegram _ user _ id '/' chat _ id'، الموافقة على الإشعارات.
الروابط العميقة/« startapp »التي يمكن التخلص منها فقط، TTL ومراجعة الحسابات.
WebApp: السمة، الأزرار، الخلف، تحديث JWT ؛ CSP، https، لا PII في URL.
مكافحة الاحتيال: حد السعر، إشارات ASN/الوكيل، حماية الإحالة.
التوزيعات: قوائم الانتظار، دفعة + نفث، مراقبة FloodWait/429.
إمكانية الرصد: الويب/TWA/مقاييس التحويل، التنبيهات.
وثائق UX/القيود، سياسة الخصوصية، DPA مع Telegram كقناة.
Runbook 'و: سقوط خطاف الويب، ارتفاع مكرر، FloodWait الهائل، فشل TWA.

ملخص السيرة الذاتية

التكامل مع Telegram ليس «روبوتًا آخر»، ولكنه قناة كاملة مع SSO آمنة (تحقق من «initData »/Login)، و UX WebApp الأنيق ومعالجة الخادم الموثوقة للتحديثات. احتفظ بالمعاملات المالية في التطبيق الرئيسي، وفي Telegram - سيناريوهات مصاحبة قوية: الملف الشخصي والبطولات والمهام والإشعارات والدعم والإحالة. أضف روابط عميقة لمرة واحدة، و JWTs قصيرة العمر، وقوائم الانتظار وإمكانية الملاحظة - واحصل على قناة نمو واحتفاظ سريعة وآمنة وقابلة للقياس.