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

تتيح واجهة برمجة التطبيقات Recall API للألعاب إدارة الروابط بين مستخدمي "خدمات ألعاب Google Play" (PGS) و حساباتهم داخل اللعبة من خلال تخزين الرموز المميّزة لإعادة التذكير على خوادم Google. في ما يلي مثال على أحد سيناريوهات استخدام واجهة برمجة التطبيقات Recall API.

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

   

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

   

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

   

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

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

• استرداد الرمز المميّز لمستخدم لاستعادة حساباته في اللعبة

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

قواعد عدد القيم الفريدة

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

قد يتم أيضًا تغيير الشخصية المرتبطة بملف شخصي على "خدمات ألعاب Play" بمرور الوقت (نظرًا لربط حساب مختلف في اللعبة بملف PGS).

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

يتناول هذا القسم العملية الفنية بين برنامج تشغيل اللعبة والخوادم مع خوادم Google عند تخزين الرموز المميّزة لإعادة التذكير واستردادها.

الخطوة 1: تسجيل الدخول بحساب مستخدم PGS واسترداد معرّف الجلسة

تبدأ اللعبة حزمة تطوير البرامج (SDK) لخدمة "خدمات ألعاب Play" وتحاول تسجيل دخول المستخدم من خلال هذه الخدمة.

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

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

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

الخطوة 3(أ): استعادة مستوى التقدّم في حال توفّر الرمز المميّز

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

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

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

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

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

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

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

تخزين زوج من الرموز المميّزة وشخصيات المستخدِمين

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

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

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

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

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