واجهة برمجة التطبيقات Recall

تساعدك واجهة Recall API في ربط مستخدمي "خدمات ألعاب Google Play" بسلاسة بحساباتهم داخل اللعبة، ما يتيح استعادة مستوى التقدّم تلقائيًا. يمكنك تخزين رموز Recall المميزة في خوادم الألعاب، ما يربط هذه الرموز بملف شخصي للمستخدم في "خدمات ألعاب Google Play". استخدام واجهة Recall API اختياري، وهو الطريقة المقترَحة لتنفيذ ميزة الاستعادة السلسة إذا لم يكن لديك نظام خلفي قوي خاص بالهوية.

المصطلحات

يستخدم هذا المستند المصطلحات التالية:

رمز مميّز لتذكّر بيانات اللعبة: هو مفتاح آمن يتم تخزينه على خوادم الألعاب ويعمل كرابط بين حساب اللاعب على "خدمات ألعاب Play" وحسابه داخل اللعبة.

معرّف الجلسة: هو معرّف مؤقت وفريد تنشئه حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play" على جهاز اللاعب، ويشير إلى أنّ الطلب الذي أرسله خادم الخلفية صادر عن جلسة لعبة نشطة ومشروعة على جهاز اللاعب.

نماذج للسيناريوهات

في ما يلي سيناريوهات نموذجية لكيفية استخدام Recall API:

1. يلعب المستخدم لعبة يتوفّر فيها نظام هوية للمطوّر لتتبُّع مستوى تقدّم المستخدم، ويستخدم "خدمات ألعاب Google Play" بالتوازي مع طرق مصادقة أخرى لتسجيل دخول المستخدمين إلى اللعبة. في هذا المثال، سجّل المستخدم الدخول إلى حسابه على "خدمات ألعاب Google Play" Laura، وأنشأ حسابًا داخل اللعبة باستخدام نظام تحديد الهوية الخاص بالمطوّر باسم Racer94. أثناء لعب المستخدم، يزامن خادم اللعبة الخاص بالمطوّر مستوى تقدّمه.

   

2. بشكل منفصل، يحفظ المطوّر رمزًا مميّزًا لتذكّر بيانات اللعبة لدى Google، ويتوافق هذا الرمز مع حساب المستخدم داخل اللعبة. وتخزِّن Google هذا الرمز المميّز تلقائيًا في ملف المستخدم الشخصي على "خدمات ألعاب Google Play".

   

3. يقرّر المستخدم الآن تشغيل اللعبة على ألعاب Google Play على الكمبيوتر للمرة الأولى. تتم مصادقة المستخدم تلقائيًا باستخدام حساب "خدمات ألعاب Google Play"، ويتأكّد برنامج اللعبة من توفّر أي مستوى تقدّم لهذا المستخدم على "خدمات ألعاب Google Play". بعد ذلك، يرسل خادم اللعبة طلبًا إلى Google للاطّلاع على ما إذا كانت هناك أي رموز مميّزة لحساب "خدمات ألعاب Google Play" هذا. بما أنّ هناك حسابًا مطابقًا، يرسل Google الرمز المميز لتذكّر بيانات اللعبة، ويستخدم خادم اللعبة هذا الرمز المميز للعثور على حساب المستخدم المرتبط Racer94 واستعادة مستوى تقدّمه. بما أنّ عملية المصادقة باستخدام "خدمات ألعاب Google Play" لا تتطلّب أي مجهود، يستعيد التطبيق مستوى تقدّم المستخدم بدون أن يضطر إلى إدخال اسم مستخدم أو كلمة مرور. بالإضافة إلى ذلك، يمكن للمطوّر استخدام ميزة المصادقة في خدمات ألعاب Google Play مع نظام تحديد الهوية الحالي، والاعتماد على Google لتخزين الرابط بين مستوى تقدّم اللاعب وحسابه على خدمات ألعاب Google Play.

   

كما هو موضّح في المثال السابق، هناك إجراءان رئيسيان تنفّذهما واجهة Recall API:

• تخزين الرمز المميز لدى Google عندما يسجّل المستخدم الدخول باستخدام أحد الحسابات داخل اللعبة

• استرداد الرمز المميّز الخاص بمستخدم معيّن من أجل استعادة حساباته داخل اللعبة

بالإضافة إلى رموز مميّزة لتذكّر بيانات اللعبة، تتطلّب واجهة Recall API أيضًا معرّفًا ثابتًا يتوافق مع الحساب داخل اللعبة، ويُعرف باسم الشخصية. يمكنك اعتبار الشخصية بمثابة التصنيف الذي يمثّل حساب المستخدم داخل اللعبة ضمن نظام تعريف المطوّر، ورمز مميّز لتذكّر بيانات اللعبة بمثابة مفتاح يُستخدم لاستعادة حساب المستخدم داخل اللعبة. يجب عدم إعادة استخدام قيم الشخصية والرمز المميّز في مشاريع "خدمات ألعاب Google Play" المختلفة. بالإضافة إلى ذلك، على الرغم من إمكانية تغيير رموز مميّزة لتذكّر بيانات اللعبة بمرور الوقت، يجب أن تكون الشخصية ثابتة وفقًا لحساب المستخدم داخل اللعبة.

الإجراءات الفنية لتخزين الرموز المميزة لتذكُّر بيانات الألعاب واستردادها

يتناول هذا القسم المسار الفني بين تطبيق اللعبة وخوادم Google عند تخزين رموز الاستدعاء واستردادها.

الخطوة 1: مصادقة مستخدم خدمات ألعاب Google Play واسترداد رقم تعريف الجلسة

تبدأ اللعبة في إعداد حزمة تطوير البرامج (SDK) لخدمات ألعاب Google Play وتحاول مصادقة المستخدم من خلالها.

بافتراض أنّ المستخدم قد تمت مصادقته، اطلب معرّف جلسة من حزمة تطوير البرامج (SDK) للألعاب على برنامج اللعبة، واطلب رمزًا مميزًا OAuth 2.0 من الخلفية الخاصة ببروتوكول OAuth من Google. ويتم استخدام معرّف الجلسة ورموز OAuth 2.0 المميزة للتواصل مع الخلفية الخاصة بـ "ألعاب Google".

الخطوة 2: استرداد أي رمز مميّز لتذكّر بيانات اللعبة متوفّر

طلب أي رمز مميّز لتذكّر بيانات اللعبة مرتبط بحساب مستخدم خدمات ألعاب Google Play. إذا كانت هناك رمز مميّز، انتقِل إلى الخطوة 3أ واستعِد مستوى تقدّمك. بخلاف ذلك، إذا كان هذا المستخدم جديدًا ولم يكن لديه رمز مميز، انتقِل إلى الخطوة 3 (ب) وخزِّن رمزًا مميزًا جديدًا.

الخطوة 3 (أ): إذا كان الرمز المميّز متوفّرًا، استعادة مستوى التقدّم

إذا كان الرمز المميّز متوفّرًا، استرِده وفك تشفيره، ثم استعِد بيانات المستخدم.

الخطوة 3 (ب): تخزين رمز مميّز في حال عدم توفّره

بما أنّه لا يتوفّر رمز مميّز، لن يتم استعادة أي تقدّم. وينتقل المستخدم إلى مصادقة المنصة باستخدام نظام هوية المطوّر أو ينشئ حسابًا جديدًا إذا لم يكن لديه حساب. ملاحظة: لا يتم إجراء المصادقة باستخدام "خدمات ألعاب Google Play" (التي تم إجراؤها من قبل)، ولكن باستخدام نظام هوية المطوّر خارج "خدمات ألعاب Google Play".

أنشئ رمزًا مميّزًا لتذكّر بيانات اللعبة مشفّرًا يشفّر حساب المستخدم داخل اللعبة، وأرسِله إلى Google مع معرّف الجلسة ورمز OAuth 2.0 المميز. في هذه المرحلة، تنشئ Google ربطًا بين رمز الاستدعاء الذي تم إرساله وحساب اللاعب على "خدمة ألعاب Play".

تدفقات المستخدمين الذين ليس لديهم ملف شخصي على "خدمات ألعاب Play"

يمكنك تخزين رموز مميّزة لتذكّر بيانات اللعبة لمستخدم لم ينشئ ملفًا شخصيًا على "خدمات ألعاب Google Play" بعد، وذلك باستخدام وضع "بدون ملف شخصي". ومع ذلك، هناك ملاحظتان مهمّتان:

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

تخزين رمز مميّز مع شخصية

1. يفتح مستخدم ليس لديه ملف شخصي في "خدمات ألعاب Play" لعبة تم تفعيل ميزة تذكُّر الحسابات المُستخدَمة بدون ملف شخصي فيها.
2. تؤدي حزمة تطوير البرامج (SDK) للألعاب إلى بدء عملية مصادقة تلقائية على المنصة، ولكنها تفشل لأنّ المستخدم ليس لديه ملف شخصي على "خدمات ألعاب Play".
3. تعرض حزمة تطوير البرامج (SDK) للألعاب شريط إعلام منبثق يوضّح للمستخدم أنّ اللعبة متوافقة مع Google. ويمكن اتّخاذ إجراء بشأن شريط الإعلام المنبثق هذا، إذ يمكن للمستخدم إيقاف ميزة "التذكير" إلى أن يتم إنشاء ملف شخصي.
4. تطلب اللعبة إذن الوصول إلى ميزة "تذكُّر الحساب". يُرجى العِلم أنّ "خدمات ألعاب Google Play" ترفض طلبات الوصول إلى ميزة "تذكُّر الحساب" عندما تتوفّر ملفات شخصية على "خدمات ألعاب Google Play" على الجهاز أو عندما لا تتوفّر حسابات Google على الجهاز. وفي هذه الحالة، يجب أن تستمر اللعبة بدون استخدام "خدمات ألعاب Google Play".
5. بعد أن يسجّل المستخدم الدخول باستخدام حساب داخل اللعبة، تنشئ اللعبة رمزًا مميزًا وزوجًا من المعلومات الشخصية للمستخدم يتوافق مع حسابه داخل اللعبة، وتخزّن اللعبة هذا الزوج لدى Google. وقد تخزّن اللعبة المزيد من الرموز المميزة لاحقًا إذا سجّل المستخدم الدخول إلى حسابات أخرى داخل اللعبة.

تشغيل لعبة على جهاز جديد

1. يفتح مستخدم ليس لديه ملف شخصي على "خدمات ألعاب Google Play" لعبة تم تفعيل ميزة تذكُّر الحسابات المُستخدَمة بدون ملف شخصي فيها على أحد الأجهزة.
2. تسجّل اللعبة رمزًا مميّزًا لتذكُّر بيانات الألعاب بدون ملف شخصي على النحو الموضّح في تخزين رمز مميّز وزوج من الشخصيات.
3. يفتح المستخدم اللعبة نفسها على جهاز مختلف تم إعداد الحساب نفسه عليه.
4. تؤدي حزمة تطوير البرامج (SDK) للألعاب إلى بدء عملية إنشاء الملف الشخصي. يمكن للمستخدم مراجعة الرموز المميّزة من أجل تذكُّر بيانات الألعاب التي تم تخزينها سابقًا ورفضها. ينشئ المستخدم ملفًا شخصيًا في خدمات ألعاب Google Play في هذا الوقت.
5. تكتمل عملية المصادقة التلقائية على المنصة في "خدمات ألعاب Google Play"، وتتلقّى اللعبة حالة المصادقة.
6. تسترد اللعبة رموز Recall المميّزة للمستخدم كالمعتاد.

الخطوات التالية

لدمج Recall API مع الخادم والعميل في لعبتك، يُرجى اتّباع هذه الإرشادات.