الدليل الفني لـ Drops

جدول المحتويات

• نظرة عامة على Drops في Twitch
• الدليل الفني لـ Drops
• الدليل حملة لـ Drops

المقدمة

تناقش هذه الصفحة المتطلبات الفنية الأساسية لإعداد نظام Drops، والاعتبارات التي يجب مراعاتها لاختيار آليات توصيل Drops المناسبة للعبتك. المراد من هذا أن يكون مجرد دليل تقني، وينبغي مراجعته بعناية قبل تصميم النظام الخاص بك، والرجوع إليه أيضًا أثناء عملية بناء النظام.

المؤسسة وملكية اللعبة

قبل إنشاء حملة Drops، يجب أن يكون لديك مؤسسة مطور تمتلك حاليًّا تصنيف اللعبة التي ترغب في إنشاء حملة Drops لها. استشر شركتك لتحديد ما إذا كانت هذه المنظمة موجودة بالفعل. إذا لم يكن كذلك، فراجع تسجيل المؤسسات وإدارتها للحصول على معلومات حول كيفية إنشاء مؤسسة.

إذا لم يتم تخصيص لعبتك لمؤسستك، فستحتاج إلى طلب ملكية اللعبة. راجع إدارة اللعبة للحصول على معلومات حول كيفية طلب ملكية تصنيف لعبتك على Twitch.

ستحتاج إلى انتظار موافقة كل من مؤسستك، وطلب ملكية اللعبة قبل المتابعة. إذا كنت قد قدمت هذه الطلبات للتو، فقد تستغرق الموافقة عليها من أسبوع إلى أسبوعين. لتجنب المشكلات الشائعة في رفض المؤسسة، راجع لماذا تم رفض طلب المؤسسة الخاص بي؟

ربط الحساب

من أجل المطالبة بالمكافآت داخل اللعبة، سيحتاج مشاهدو Twitch إلى ربط حساباتهم على Twitch وحسابات اللعبة. ربط الحساب، من وجهة نظر Twitch، هو عندما يقوم المستخدم بالمصادقة على تطبيقك (Client ID)؛ ما يؤدي إلى إنشاء ربط بين حساب المستخدم على Twitch وتطبيق الجهة الخارجية.

الحصول على معرّف العميل

يجب أن يكون لديك Client ID -يُعرف أيضًا باسم التطبيق - مملوك لمستخدم هو جزء من مؤسستك. إذا لم يكن لديك واحد بالفعل، فتابع الخطوات الموضحة في Registering your App. من المستحسن أن يكون الحساب الذي ينشئ هذا التطبيق هو حساب شركة مشترك، حيث لا يمكن نقل التطبيقات على Twitch.

تعد هذه التوصية بالغة الأهمية؛ لأن الموظفين قد يتركون مؤسستك بينما لا يزالون يمتلكون التطبيق على حساباتهم الشخصية؛ مما يجعل من المستحيل على مؤسستك إجراء تغييرات على التطبيق.

إعداد عملية ربط الحساب الخاص بك

عندما لا يكون لدى المستخدمين حساب مرتبط بالتطبيق الخاص بك، ستتم إعادة توجيههم إلى موقعك الإلكتروني لإكمال عملية ربط الحساب. من أجل ربط حسابات Twitch وحسابات لعبة بشكل صحيح، ستحتاج إلى اتباع العملية التالية:

1. اطلب من المشاهدين تسجيل الدخول إلى نظام حسابك
2. اطلب من المشاهدين تفويض تطبيق Twitch الخاص بك باستخدام حساب Twitch الخاص بهم
3. قم بتخزين ربط حساب Twitch <> حساب اللعبة في أنظمتك

نوصي بتخزين المعلومات التالية على وجه التحديد:

• معرّف حساب اللعبة
• رمز OAuth على Twitch
• رمز تحديث Twitch
• معرف المستخدم على Twitch

بينما يمكن تحقيق ربط الحساب داخل اللعبة، نوصي باستضافة صفحة ويب للسماح لمشاهدي Twitch بربط حساباتهم. يمكن إضافة عنوان URL للصفحة التي سيربط فيها المستخدمون حسابهم إلى تكوين حملتك؛ بحيث يمكن لـ Twitch إعادة توجيه المشاهدين إلى صفحة ربط الحساب الصحيحة.

للحصول على معلومات حول مصادقة المستخدم الخاص بك مقابل معرّف Client ID الخاص بك، راجع دليل OAuth على Twitch. أكثر أشكال المصادقة شيوعًا لـ Drops هي تدفق المنح الضمني، وتدفق منح رمز التخويل. يجب أن يكون معرّف العميل المستخدم في هذه الخطوات هو معرّف العميل الذي تمت مناقشته سابقًا في هذه الصفحة، وإلا فلن تعمل عملية ربط الحساب.

التعامل مع إلغاء ربط الحساب

قد يقوم المستخدم في أي وقت بفصل ربط الحساب بين حساب Twitch وحساب اللعبة، سواء عن قصد أو عن غير قصد. بعض الأمثلة على الحالات التي قد يحدث فيها ذلك هي عندما يطرأ على المستخدم ما يلي:

• تغيير كلمة المرور
• تم تعليقه من Twitch
• إزالة الربط يدويًّا من داخل صفحة عمليات الربط
• تنتهي صلاحية كل من رمز OAuth ورمز التحديث
  • ملاحظة: لن تتم إزالة ربط الحساب تلقائيًّا إذا انتهت صلاحية رمز OAuth فقط . يجب أن تنتهي صلاحية كلا الرمزين في هذه الحالة.

على أي حال، يكون ذلك دائمًا بسبب إلغاء أو إزالة تفويض المستخدم الممنوح لمعرف Client ID الخاص بك. للتحقق مما إذا كان المستخدم قد فصل حسابه، يمكنك التحقق من صلاحية رمز OAuth الخاص به.

يمكن للمستخدم إعادة ربط حسابه بعد إلغاء الربط. نقدم بعض التوصيات للتعامل مع إعادة ربط الحساب من قبل المستخدمين:

• يجب أن يكون منح العنصر داخل اللعبة 1 لكل معرّف مستخدم على Twitch - أي مستخدم ربط حساب Twitch الخاص به بحساب اللعبة وأنجز محتوى داخل اللعبة، لا يمكنه إعادة ربط حساب Twitch نفسه بحساب لعبة ثانٍ وإنجاز العنصر نفسه داخل اللعبة.
• يجب أن يحصل حساب Twitch على Drops مرة واحدة فقط داخل لعبتك - أي مستخدم ربط حساب Twitch الخاص به بحساب اللعبة وأنجز المحتوى داخل اللعبة، لا يمكنه إعادة ربط حساب Twitch نفسه بحساب لعبة ثانٍ وإنجاز العنصر نفسه داخل اللعبة.
• يجب ألا يكون المستخدمون قادرين على استخدام حسابات Twitch متعددة للحصول على نسخ مكررة من Drops واحدة - لا يمكن للمستخدم الذي ربط حساب Twitch الخاص به بحساب اللعبة أن يحقق محتوى إضافيًا داخل اللعبة عن طريق إلغاء ربط حساب وربط حساب آخر مستحق على Twitch بحساب اللعبة نفسه.
• لا يجب أن تكون Drops قابلة للتحويل - لا يمكن للمستخدم الذي ربط حساب Twitch الخاص به بحساب اللعبة نقل العناصر المستوفاة إلى حساب لعبة آخر (على سبيل المثال سوق Steam، نقل المحتوى إلى حساب لعبة أخرى).

للتعامل مع الحالات المذكورة أعلاه، يوصى بتخزين بيانات منح Drop المرتبطة بمعرّفات مستخدمي Twitch أو معرّفات الحسابات داخل اللعبة إلى جانب إقران معرّف الحملة + معرّف المكافأة . ضع في اعتبارك أنه يمكن استخدام مُعرّف المكافأة عدة مرات عبر العديد من معرّفات الحملات.

إزالة ربط الحساب

يجوز لك إنهاء ربط الحساب لمستخدم في أي وقت ولأي سبب من الأسباب. نظرًا لأن عمليات ربط الحساب يتم الاحتفاظ بها بشكل أساسي بواسطتك، ستحتاج إلى إزالة عمليات الربط داخل نظام حساب اللعبة الخاص بك.

نوصي أيضًا بإلغاء رمز الوصول OAuth لأسباب أمنية. لا توجد طريقة لإزالة ظهور ربط الحساب من منظور المستخدم على حساب Twitch الخاص به. سيحتاج المستخدم إلى إزالة الربط يدويًّا على Twitch إذا كان يرغب في إعادة ربط حسابه.

تصميم نظام Drops الخاص بك

تتيح لك Twitch الاستفادة من كل من Twitch API وEventSub كوسيلتين لتلقي المعلومات حول حملة Drops الخاصة بك. تعتمد كيفية استخدامك لهذه الأنظمة على مدى توفر نظام المخزون في لعبتك من منظور تقني.

هناك ثلاثة أنظمة Drops موصى بها يمكنك إعدادها:

• EventSub + Twitch API - يسمح لك هذا النظام بتلقي معلومات عبر EventSub حول استحقاقات Drops مباشرةً إلى خادم الويب الخاص بك، ثم إخطار Twitch باستخدام Twitch API عندما يتم استيفاء هذه الاستحقاقات. يوصى بهذه الطريقة في معظم الحالات؛ بما في ذلك ألعاب الخدمة المباشرة.
• Twitch API (المخزون المستضاف) - يسمح لك هذا النظام بالحصول على معلومات حول استحقاقات Drops عند الطلب، ولكنه لا يخطر أنظمتك تلقائيًّا. لا يوصى بهذا، ولكن يمكن أن يكون مفيدًا في بعض الحالات التي يجب فيها التحقق من حالة الـ Drop عند طلب المستخدم.
• Twitch API (مخزون غير متصل) - الألعاب التي لا يتم فيها استضافة العناصر داخل لعبة عبر الإنترنت، ولا تملك إمكانية الوصول إلى خادم عبر الإنترنت لاستحقاق Drops أو إدارة المخزون، يجب أن تتم معالجة أنظمة استحقاق Drops الخاصة بها عن طريق الوصول إلى Twitch API من داخل اللعبة.

إذا لم تكن متأكدًا مما يجب استخدامه، فمعظم الحالات ستكون إما EventSub + Twitch API ، أو Twitch API (المخزون غير المتصل) . إذا كان نظام تسليم الاستحقاقات الخاص بك يتم التعامل معه بواسطة خادم تقوم بتشغيله، فاتبع الدليل الخاص بـ EventSub + Twitch API . إذا كان نظام الاستحقاق الخاص بلعبتك لا يمتلك إمكانية الوصول إلى خادم، فاتبع الدليل الخاص بـ Twitch API (المخزون غير المتصل) .

EventSub + Twitch API

يستخدم نظام Drops الأكثر شيوعًا كلاً من Twitch API و EventSub . في هذا السيناريو، سيتم دفع استحقاقات Drops باستخدام EventSub Webhooks إلى نقطة نهاية URL الذي تستضيفه، والذي سيقوم بعد ذلك بتنشيط أنظمة الاستحقاق الخاصة بلعبتك لتسليم العنصر داخل اللعبة. بعد أن يتم تسليم العنصر داخل اللعبة بنجاح، ستقوم باستدعاء Twitch API لتسجيل استحقاق المكافأة داخل نظام Twitch.

التفاصيل التقنية

قبل تنشيط العملية أدناه، يفترض أن يكون المستخدم قد ربط حساب Twitch وحساب اللعبة الخاص به كما هو موضح في ربط الحساب.

في الرسم البياني أعلاه ستكون الأنظمة التالية في مكانها الصحيح:

• نظام الاستحقاق الخاص بك - هذه هي خدمتك الخاصة التي تقبل EventSub Webhook الوارد، وتقدم حمولة EventSub لـ منح استحقاق Drops.
• EventSub - منتج EventSub على Twitch، والذي سيقدم لك إشعارات Webhook عندما يصبح المستخدم مستحقًّا لمكافأة Drop.
• Twitch API - واجهة برمجة التطبيقات على Twitch، والتي ستستدعيها لتحديث المعلومات حول حالة استحقاق Drop.
• قاعدة بيانات مستخدم اللعبة - هذه هي أي خدمة تتيح لك العثور على ارتباط بين معرّف مستخدم Twitch ومعرّف نظام حسابك داخل اللعبة للمستخدم. يتم إعداد هذا الارتباط أثناء عملية ربط الحساب.
• المخزون داخل اللعبة - هي أي خدمة تتيح لك منح العناصر في نظام المخزون.

ستحتاج إلى استخدام رمز الوصول إلى تطبيق الهاتف عند إعداد اشتراك EventSub. يوصى باستخدام رمز الوصول إلى تطبيق الهاتف نفسه عند استدعاء واجهة برمجة التطبيقات، حيث يتيح لك ذلك تحديث عدد كبير من المستخدمين في وقت واحد.

إعداد EventSub

ملاحظة: قبل البدء في التنفيذ، اقرأ أولاً الأسئلة الشائعة الفنية لمراجعة الأسئلة والمشكلات الشائعة التي تحدث أثناء إنشاء نظام Drops.

نوع الاشتراك في EventSub

يسمح لك منتج EventSub من Twitch بالاستماع إلى الأحداث التي تطلبها في الوقت الفعلي، والتي توصف بأنها أنواع اشتراكات. يقوم نوع الاشتراك drop.entitlement.grant بإرسال إشعار عندما يتم منح استحقاق لـ Drop إلى مشاهد. للحصول على معلومات مفصلة حول موضوع EventSub هذا، راجع منح استحقاق Drop.

للاشتراك في موضوع EventSub، تابع الخطوات في اشتراك في الأحداث. مع هذا النوع الخاص من الاشتراك، ستحتاج إلى تضمين organization_id ضمن شرطك، ويمكنك اختياريًّا تضمين category_id وcampaign_id. في معظم السيناريوهات، تحتاج فقط إلى تحديد organization_id؛ لأن تحديد الحقول الأخرى لن يؤدي إلا إلى تقديم إشعارات Drops تمت تصفيتها حسب تلك الحقول.

يتطلب منك هذا النوع من الاشتراك أيضًا تضمين is_batching_enabled في اشتراك EventSub الخاص بك. وذلك لأن هذا الاشتراك -على عكس معظم اشتراكات EventSub- يمكن أن يتضمن هذا أحداث Drops متعددة ضمن إشعار واحد.

التنفيذ

نظام الاستحقاق الخاص بك هو جوهر تكامل Drops. يتعامل هذا النظام مع خطافات الويب EventSub Webhooks الواردة، ويتواصل مع قاعدة بيانات المستخدم ونظام المخزون في لعبتك، ويقوم بتحديث Twitch API عند الانتهاء.

كما هو موضح في الرسم البياني أعلاه، يجب أن يكمل نظامك العمليات التالية:

قبول عمليات منح استحقاق Drop

أولاً، سيرسل لك نظام EventSub الخاص بـ Twitch إشعارًا عندما يكمل مستخدم واحد أو أكثر حملة Drops. ضمن إشعار EventSub، سترى مصفوفة تحتوي على بيانات Drops بهذا التنسيق:

[
    {
        "id": "bf7c8577-e3e3-4881-a78a-e9446641d45d",
        "data": {
            "organization_id": "373c8318-78e7-4bc5-bf2f-7a1a48a1d7d4",
            "category_id": "26936",
            "category_name": "Music",
            "campaign_id": "9003e09a399c-256e-11f0-8869-0a58a9feac02",
            "user_id": "141981764",
            "user_name": "TwitchDev",
            "user_login": "twitchdev",
            "entitlement_id": "WW91IGFyZW4ndCBzdXBwb3NlZCB0byBkZWNvZGUgdGhlc2UhIQ==",
            "benefit_id": "your-custom-reward-id-ends-up-here",
            "created_at": "2019-01-28T04:17:53.325Z"
        }
    },
    ...
]

نظرًا لأنه قد يتم إرجاع استحقاقات متعددة، فقد يكون هناك عدة مستخدمين مدرجين في إشعار EventSub واحد. ستحتاج إلى فحص جميع الاستحقاقات في مصفوفة الحمولة، وتخزين الصلاحيات التي يتم منحها للمستخدمين مؤقتًا.

الحصول على معلومات المستخدم من قاعدة البيانات الخاصة بك

عندما يقوم المستخدم بربط حسابه، يجب أن يكون لديك إدخال في قاعدة البيانات في مكان ما يربط الربط بين حساب المستخدم على Twitch وحسابه في لعبتك. ستكون هذه المعلومات ضرورية لإبلاغ اللعبة بمن يستحق مكافأة Drops.

إذا لم يكن المستخدم موجودًا في قاعدة البيانات الخاصة بك، فهذا يعني أن المستخدم لم يربط حسابه بعد. ستحتاج إلى تجاهل الإشعار في هذا الوقت، ومعالجته في وقت لاحق. أنت ملزم بمحاولة معالجة هذا الاستحقاق لمدة تصل إلى 14 يومًا بعد انتهاء الحملة.

إعادة توجيه المعلومات إلى لعبتك لتستحقها داخل اللعبة

الآن بعد أن أصبحت لديك المعلومات المطلوبة، يمكنك إعادة توجيه benefit_id و معرف المستخدم داخل اللعبة إلى خوادم الواجهة الخلفية للعبتك. ستحتاح قبل المتابعة بعد ذلك، إلى التأكد من أن العنصر داخل اللعبة كان يحق له الوصول إلى مخزون المستخدم بشكل صحيح.

استدعاء Twitch API لتمييز الاستحقاقات على أنها مستوفاة

باستخدام Update Drops Entitlements API، ستقوم بإخطار Twitch بأن الاستحقاقات قد تم استيفاؤها. يمكنك استدعاء API على غرار طلب curl هذا:

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

ستحتاج إلى إجراء هذه المكالمة باستخدام رمز الوصول إلى تطبيق الهاتف؛ حيث يمكن أن يؤثر استدعاء API هذا على عدة مستخدمين. للمزيد من المعلومات حول واجهة برمجة التطبيقات هذه، بما في ذلك مثال على استجابة الحمولة، راجع API لتحديث استحقاقات Drops.

الأفكار النهائية

من الحالات الشائعة التي قد تحدث هي الحسابات غير المرتبطة. في حالة حدوث إشعار لحساب غير مرتبط، سيتعين عليك إعادة محاولة استحقاق العنصر داخل اللعبة حتى يتم بنجاح أو يمر 14 يومًا بعد انتهاء الحملة.

بالإضافة إلى ذلك، يعتمد هذا التطبيق على قيام EventSub بدفع المعلومات إليه، ولا يتحقق من API بحثًا عن المعلومات المفقودة. بينما يحاول EventSub إعادة إرسال الإشعارات الفاشلة، إلا أنه في حالات نادرة جدًّا قد لا يتم تسليم الإشعار. لحل هذه المشكلة، يوصى بالاستعداد للبحث يدويًّا في واجهة برمجة تطبيقات API الحصول على استحقاقات Drops للاستحقاقات التي لم تتم معالجتها من CLAIMED إلى FULFILLED.

Twitch API (المخزون المستضاف)

إذا كنت لا ترغب في استضافة خادم ويب للتعامل مع EventSub Webhooks الواردة، يمكنك بدلاً من ذلك استدعاء Twitch API على فترات متكررة. في هذا السيناريو، سوف تتحقق من Twitch API في فترة زمنية موصى بها من 5 إلى 15 دقيقة، وتتحقق من وجود Drops لم يتم استيفاؤها للمستخدم، ثم تتابع تسليم العنصر داخل اللعبة إلى حساب اللعبة الخاص بالمستخدم. بعد أن يتم تسليم العنصر داخل اللعبة بنجاح، ستقوم باستدعاء Twitch API لتسجيل استحقاق المكافأة داخل نظام Twitch.

التفاصيل التقنية

قبل تنشيط العملية أدناه، يفترض أن يكون المستخدم قد ربط حساب Twitch وحساب اللعبة الخاص به كما هو موضح في ربط الحساب.

في الرسم البياني أعلاه ستكون الأنظمة التالية في مكانها الصحيح:

• نظام الاستحقاق الخاص بك - هذه هي خدمتك الخاصة التي تقبل EventSub Webhook الوارد، وتقدم حمولة EventSub لـ منح استحقاق Drops.
• Twitch API - واجهة برمجة تطبيقات Twitch، والتي ستستدعيها للحصول على قائمة باستحقاقات Drops، وتحديث المعلومات حول حالة استحقاق Drop.
• قاعدة بيانات مستخدم اللعبة - هذه هي أي خدمة تتيح لك العثور على ارتباط بين معرّف مستخدم Twitch ومعرّف نظام حسابك داخل اللعبة للمستخدم. يتم إعداد هذا الارتباط أثناء عملية ربط الحساب.
• المخزون داخل اللعبة - هي أي خدمة تتيح لك منح العناصر في نظام المخزون.

يوصى باستخدام رمز وصول المستخدم لهذا الإعداد، ولكن يمكنك استخدام رمز الوصول إلى تطبيق الهاتف إذا رغبت في ذلك. في الحالات التي يتم فيها استخدام رمز وصول المستخدم ، ستحتاج إلى استدعاء تحديث استحقاقات Drop بشكل فردي لكل مستخدم باستخدام رمز وصول المستخدم الخاص به.

ملاحظة: قبل البدء في التنفيذ، اقرأ أولاً الأسئلة الشائعة الفنية لمراجعة الأسئلة والمشكلات الشائعة التي تحدث أثناء إنشاء نظام Drops.

التنفيذ

نظام الاستحقاق الخاص بك هو جوهر تكامل Drops. سيتم تنشيط هذا النظام في إحدى هذه اللحظات:

• تلقائيًّا، كل 5-15 دقيقة.
• عند التنشيط بواسطة نظام آخر، مثل تفاعل المستخدم على موقعك الإلكتروني.

عند التنشيط، يستدعي النظام Twitch API للحصول على قائمة بجميع الاستحقاقات غير المستوفاة، ويتواصل مع قاعدة بيانات المستخدم ونظام المخزون في لعبتك، ويقوم بتحديث واجهة برمجة التطبيقات Twitch عند الانتهاء.

كما هو موضح في الرسم البياني أعلاه، يجب أن يكمل نظامك العمليات التالية:

استدعاء Twitch API للحصول على قائمة بالاستحقاقات

باستخدام واجهة برمجة تطبيقات الحصول على استحقاقات Drops، ستحصل على معلومات حول جميع الاستحقاقات غير المستوفاة للعبتك. يمكنك استدعاء API على غرار طلب curl هذا:

curl -H GET 'https://api.twitch.tv/helix/entitlements/drops?game_id=<Your game ID>&fulfillment_status=CLAIMED' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>'

إذا كنت تستخدم رمز وصول المستخدم ، فستقوم API بإرجاع الاستحقاقات الخاصة بهذا المستخدم فقط. إذا كنت تستخدم رمز الوصول إلى تطبيق الهاتف ، فستقوم API بإرجاع الاستحقاقات لجميع المستخدمين ما لم تحدد خلاف ذلك معرف مستخدم في معلمات الاستعلام.

الحصول على معلومات المستخدم من قاعدة البيانات الخاصة بك

عندما يقوم المستخدم بربط حسابه، يجب أن يكون لديك إدخال في قاعدة البيانات في مكان ما يربط الربط بين حساب المستخدم على Twitch وحسابه في لعبتك. ستكون هذه المعلومات ضرورية لإبلاغ اللعبة بمن يستحق مكافأة Drops.

إذا لم يكن المستخدم موجودًا في قاعدة البيانات الخاصة بك، فهذا يعني أن المستخدم لم يربط حسابه بعد. ستحتاج إلى تجاهل الإشعار في هذا الوقت، ومعالجته في وقت لاحق. أنت ملزم بمحاولة معالجة هذا الاستحقاق لمدة تصل إلى 14 يومًا بعد انتهاء الحملة.

إعادة توجيه المعلومات إلى لعبتك لتستحقها داخل اللعبة

الآن بعد أن أصبحت لديك المعلومات المطلوبة، يمكنك إعادة توجيه benefit_id و معرف المستخدم داخل اللعبة إلى خوادم الواجهة الخلفية للعبتك. ستحتاح قبل المتابعة بعد ذلك، إلى التأكد من أن العنصر داخل اللعبة كان يحق له الوصول إلى مخزون المستخدم بشكل صحيح.

استدعاء Twitch API لتمييز الاستحقاقات على أنها مستوفاة

باستخدام Update Drops Entitlements API، ستقوم بإخطار Twitch بأن الاستحقاقات قد تم استيفاؤها. يمكنك استدعاء API على غرار طلب curl هذا:

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

إذا كنت تستخدم رمز وصول المستخدم ، ستُرجع API خطأً إذا حاولت تعديل حالة الاستحقاقات لمستخدم غير مقترن بالرمز المميز. إذا كنت تستخدم رمز الوصول إلى تطبيق الهاتف ، يمكنك استخدام استدعاء API هذا لتعديل أي استحقاق مرتبط بلعبة مملوكة لمؤسسة يكون مالك معرّف Client ID عضوًا فيها.

الأفكار النهائية

من الحالات الشائعة التي قد تحدث هي الحسابات غير المرتبطة. ستظل الاستحقاقات من هذه الحسابات تظهر في حالة CLAIMED على الرغم من عدم إمكانية استيفائها حتى يتخذ المستخدم إجراءً. إذا كنت تقوم بمعالجة الاستحقاقات تلقائيًّا، فستحتاج إلى إعادة محاولة استحقاق العنصر داخل اللعبة حتى تنجح، أو بعد مرور 14 يومًا من نهاية الحملة. إذا كنت تقوم بالمعالجة عند تفاعل المستخدم، فقم بإخطار المستخدم بضرورة إكمال ربط حسابه قبل أن يتمكن من استلام مكافأة Drops.

Twitch API (مخزون غير متصل)

في السيناريو الذي لا توجد فيه حاجة لاستضافة مخزون المستخدم -كما هو الحال في لعبة لاعب واحد- يمكنك استضافة اللعبة محليًّا.

ربط الحساب

تختلف عملية ربط الحساب لهذا السيناريو اختلافًا طفيفًا، حيث يجب الاحتفاظ برمز OAuth محليًّا. نظرًا لأنه من المفترض أن تكون اللعبة غير متصلة بالإنترنت بالكامل، سنحتاج إلى خادم ويب محلي يتعامل مع اتصال OAuth.

في الرسم البياني أعلاه، ستكون الأنظمة والكيانات التالية في مكانها الصحيح:

• اللاعب - هذا هو المستخدم الذي يلعب لعبتك.
• اللعبة - هذه هي لعبتك، وتشمل جميع الجوانب المرئية والخلفية للعبتك، باستثناء خادم HTTP المستضاف محليًّا.
• خادم HTTP المستضاف في اللعبة - هذا هو خادم HTTP الذي ستبدأه لعبتك في الخلفية. استخدامه الوحيد هو التعامل مع إعادة توجيه المصادقة.
• Twitch - Twitch هو المكان الذي سيتم إعادة توجيه المستخدم إليه حتى يتمكن من ربط حسابه بلعبتك. ستكون الأجزاء ذات الصلة من Twitch في هذا النظام هي شاشة تسجيل الدخول إلى Twitch، وشاشة تفويض تطبيق الطرف الثالث في Twitch.

لكي يقوم المستخدم بربط حسابه باللعبة الخاصة بك، سيتم إكمال العمليات التالية:

• سينقر اللاعب على الزر “ الربط مع Twitch “ ضمن قائمة إعدادات اللعبة.
• في خلفية لعبتك، سيبدأ خادم HTTP المستضاف محليًا. يجب أن تتم استضافة هذا الخادم على نفس منفذ المضيف المحلي المحدد في URI لإعادة التوجيه الخاص بمعرّف Client ID الخاص بك، والذي تم إعداده أثناء الحصول على معرّف Client ID الخاص بك.
• ستفتح اللعبة الخاصة بك متصفح الويب الخاص باللاعب، وتنقله تلقائيًا إلى عنوان URL الخاص بتفويض Twitch. نظرًا لأنه يجب ألا تقوم تحت أي ظرف من الظروف بتضمين Client Secret لمعرف Client ID الخاص بك داخل لعبتك، ستحتاج إلى استخدام عنوان URL المحدد في Implicit Grant Flow.
• بمجرد أن يقوم المستخدم بتسجيل الدخول إلى Twitch وتفويض تطبيقك، ستتم إعادة توجيهه إلى عنوان URL الخاص بالمضيف المحلي، مع تضمين رمز الوصول الخاص به في عنوان URL الخاص به.
• سيقبل خادم HTTP الخاص بك هذا الطلب، ويخزن الرمز محليًا، ويعيد HTML إلى المستخدم ليطلب منه إغلاق نافذة المتصفح.
• داخل لعبتك، سوف تقوم بتحديث واجهة مستخدم قائمة الإعدادات للإشارة إلى المستخدم أنه قام بربط حساب Twitch الخاص به بنجاح.

ملاحظة: رموز وصول المستخدم قصيرة الأجل، ولا تتضمن رموز الوصول التي يتم توفيرها عبر Implicit Grant Flow رمز يمكن تحديثه. لهذا السبب، ستحتاج إلى التحقق من صحة الرمز من حين لآخر، بما في ذلك أثناء إطلاق لعبتك، وعندما يبدأ المستخدم في التحقق من وجود Drops.

التفاصيل التقنية

في الرسم البياني أعلاه، ستكون الأنظمة والكيانات التالية في مكانها الصحيح:

• اللاعب - هذا هو المستخدم الذي يلعب لعبتك.
• اللعبة - هذه هي لعبتك، وتشمل جميع الجوانب المرئية والخلفية للعبتك، باستثناء أنظمة المخزون داخل اللعبة.
• المخزون داخل اللعبة - نظام مخزون لعبتك، وأي أنظمة مرتبطة به تسمح لك بإجراء تغييرات على مخزون اللاعب.
• Twitch API - واجهة برمجة تطبيقات Twitch، والتي ستستدعيها للحصول على قائمة باستحقاقات Drops، وتحديث المعلومات حول حالة استحقاق Drop.

التنفيذ

يبدأ هذا النظام عندما يبدأ المستخدم يدويًا طلبًا للتحقق من مكافآت Drops غير المستوفاة. ستكون هذه الطلبات بشكل عام ضمن زر التحقق من وجود Drops من واجهة مستخدم الإعدادات داخل اللعبة. عند التنشيط، يقوم النظام بالتحقق من صحة رمز OAuth المميز المخزن محليًا، ويستدعي واجهة برمجة تطبيقات Twitch للحصول على قائمة بجميع الاستحقاقات غير المستوفاة، ويتواصل مع نظام المخزون الخاص بلعبتك، ويقوم بتحديث Twitch API عند الانتهاء.

كما هو موضح في الرسم البياني أعلاه، يجب أن يكمل نظامك العمليات التالية:

التحقق من صحة رمز OAuth المخزن

رموز وصول المستخدم قصيرة الأجل، ولا تتضمن رموز الوصول المقدمة عبر Implicit Grant Flow رمزًا يمكن تحديثه. لهذا السبب، ستحتاج إلى التحقق من صحة الرمز الخاص بك قبل استدعاء Twitch API. وبدلاً من ذلك، يمكنك محاولة إجراء استدعاء API وستقوم بإرجاع HTTP 401 Unauthorized إذا انتهت صلاحية الرمز.

إذا انتهت صلاحية الرمز، فستحتاج إلى توجيه المستخدم لإعادة ربط حسابه عبر زر الربط مع Twitch .

استدعاء Twitch API للحصول على قائمة بالاستحقاقات

باستخدام واجهة برمجة تطبيقات الحصول على استحقاقات Drops، ستحصل على معلومات حول جميع الاستحقاقات غير المستوفاة للعبتك. يمكنك استدعاء API على غرار طلب curl هذا:

curl -H GET 'https://api.twitch.tv/helix/entitlements/drops?game_id=<Your game ID>&fulfillment_status=CLAIMED' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>'

يجب إجراء هذا الاستدعاء باستخدام رمز وصول المستخدم الذي تمت مناقشته سابقًا. سيعيد المعلومات تلقائيًا للمستخدم الذي يلعب لعبتك فقط.

التحقق من وجود أي استحقاقات غير مستوفاة

في هذا النظام، يمكن للمستخدم بدء التحقق من استحقاقات Drops في أي وقت. وبسبب ذلك قد لا يكون هناك أي استحقاقات Drops للوفاء بها. قم بالمعالجة باستخدام استجابة API والتحقق من وجود استحقاقات يجب الوفاء بها قبل المتابعة.

استدعاء Twitch API لتمييز الاستحقاقات على أنها مستوفاة

باستخدام Update Drops Entitlements API، ستقوم بإخطار Twitch بأن الاستحقاقات قد تم استيفاؤها. يمكنك استدعاء API على غرار طلب curl هذا:

curl -X PATCH 'https://api.twitch.tv/helix/entitlements/drops' \
-H 'Authorization: Bearer <Your OAuth token goes here>' \
-H 'Client-Id: <Your tokens associated Client ID goes here>' \
-H 'Content-Type: application/json' \
-d '{
    "fulfillment_status": "FULFILLED",
    "entitlement_ids": [
        "U2VyaW91c2x5LCBkb24ndCB3b3JyeSBhYm91dCBkZWNvZGluZyB0aGVzZSE=",
        "R28gcmVhZCB0aGUgVGVjaG5pY2FsIEZBUSBmb3IgbW9yZSBpbmZv"
    ]
}'

يمكن تنفيذ ذلك قبل أو بعد استحقاق العنصر داخل اللعبة، ولكن تنفيذ ذلك قبل استحقاقه داخل اللعبة قد يؤدي إلى تجنب بعض حالات التسابق مع نظام المخزون الخاص بك. الغرض من هذا الاستدعاء هو منع المستخدم من المطالبة بالعنصر داخل اللعبة عدة مرات.

إذا فشل استدعاء API لأي سبب من الأسباب، مثل انتهاء صلاحية الرمز أو عدم وجود اتصال بالإنترنت، فستحتاج إلى إخطار اللاعب بهذا الفشل وتزويده بالتعليمات المناسبة لاستكشاف الأخطاء وإصلاحها.

حدِّث مخزونك داخل اللعبة ليشمل عنصر المكافأة

نظرًا لأن هذا النظام يعمل بالكامل داخل لعبتك، يمكنك الآن استدعاء مخزون لعبتك لتحديثه ليشمل عنصر المكافأة المرتبط بالاستحقاق.

إخطار اللاعب بأنه تم استحقاق المكافأة بنجاح.

يمكن الآن إعادة توجيه اللاعب مرة أخرى إلى لعبتك للاستمتاع بالعنصر الذي حصل عليه داخل اللعبة!

الأسئلة الشائعة التقنية

ما هي المدة التي أحتاجها لدعم استيفاء مطالبة Drops للمستخدم؟

يُطلب من المطورين الوفاء بمكافآت المشاهدين التي تربط حسابهم حتى 14 يومًا بعد انتهاء الحملة. بالنسبة لبعض الحملات الحساسة من حيث الوقت، مثل الإصدار التجريبي محدود الوقت، قد يتم التنازل عن هذا الشرط.

هل يمكن أن تحدث المطالبات بعد انتهاء الحملة؟

نعم. يجب أن يستوفي المستخدمون المتطلبات اللازمة لكسب Drop خلال الفترة الزمنية للحملة، ولكن لمدة تصل إلى 14 يومًا بعد انتهاء الحملة، يمكن للمستخدم ربط حسابه والمطالبة. عند حدوث ذلك، قد تتلقى إشعار EventSub، وسيتم تحديث البيانات التي توفرها Twitch API.

هل هناك حد أقصى لطول المعرفات التي يوفرها EventSub و Twitch API؟

لا يوجد حد أقصى مفروض لطول المعرفات، حيث أن المعرفات مبهمة وقابلة للتغيير. إذا كان الحد الأقصى المتوقع للطول المتوقع من قبل قاعدة البيانات الخاصة بك، فمن المستحسن استخدام 255 للسماح بالمرونة.

هل يجب التحقق من صحة تنسيق معرّفات المكافآت أو فك تشفيرها؟

المعرفات المتعلقة بـ Drops التي توفرها Twitch API و EventSub مبهمة، وتوفر معلومات لا معنى لها إذا تم فك تشفيرها. يخضع تنسيق المعرفات أيضًا للتغيير في أي وقت، لذا لا تتحقق من صحة المعرفات بناءً على توقع التنسيق (مثل GUID أو Base64 ).

هل يمكن أن تحدث المطالبات قبل ربط الحساب؟

نعم، يمكن للمستخدمين المطالبة بمكافآت Drops قبل ربط حسابهم. في هذه الحالات، يُتوقع منك التحقق من قيام المستخدم بربط حسابه حتى يقوم بذلك. هذا مطلوب فقط لمدة تصل إلى 14 يومًا بعد انتهاء الحملة، حيث لم يعد بإمكان المستخدمين المطالبة بالمكافآت بعد هذه الفترة.

هل أحتاج إلى وضع علامة على استحقاقات Drops على أنها FULFILLED؟

نعم. لا توجد طريقة أخرى لمعرفة أنه تم استيفاء استحقاق Drop بأثر رجعي إلا من خلال وضع علامة على ذلك عبر Twitch API. من المفيد القيام بذلك حتى في الأنظمة التي تستخدم EventSub حيث يمكن أن تكون هناك حالات نادرة يكون فيها نظام EventSub الخاص بك معطلاً خلال فترة حملة ويفقد استحقاق Drop جديد.

هل هناك ترتيب لكيفية إرجاع نتائج API؟

لا. لا يوجد ترتيب متوقع في API الحصول على استحقاق Drops في النتائج التي يتم إرجاعها، وقد تُرجع النتائج بترتيب لا علاقة له بأي من خصائصها. للبحث بشكل أفضل عن استحقاقات ذات خصائص محددة، مثل حالة الاستيفاء، استخدم معلمات الاستعلام عند استدعاء API.

لماذا لا يظهر للمستخدم رابط حساب بعد محاولة ربط حسابه؟

يتم تحديد ربط الحساب الناجح لحملة Drops من خلال قيام المستخدم بالمصادقة بنجاح مقابل معرّف Client ID المرفق بلعبتك، الذي تم تعيينه في إعدادات Drops. تأكد من تعيين معرّف Client ID الذي تم تعيينه ضمن إعدادات Drops إلى نفس معرّف Client ID مثل ربط “ الربط مع Twitch “ الذي قمت بإعداده في قسم ربط الحساب سابقًا.

ملاحظة: إذا قمت بتغيير معرّف Client ID الخاص بلعبتك في إعدادات Drops بعد إنشاء حملة Drops، فستحتاج إلى إنشاء حملة جديدة لمزامنتها مع معرّف Client ID المعين حديثًا للعبة.