دمج واجهة برمجة التطبيقات PGS Recall في لعبتك

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

إعداد خادم اللعبة

يمكنك إعداد خادم اللعبة لإجراء مكالمات من واجهة برمجة التطبيقات Recall API إلى خوادم Google.

1. إعداد مشروع "خدمات ألعاب Play"

(في حال عدم إكمالها من قبل) اتّبِع التعليمات الواردة في إعداد خدمات ألعاب Google Play.

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

2. إعداد حساب خدمة للّعبة

اتّبع التعليمات بشأن إنشاء حساب خدمة. في النهاية، من المفترض أن يتوفّر لديك ملف JSON يحتوي على بيانات اعتماد حساب الخدمة.

ملاحظة: Recall API هي واجهة برمجة تطبيقات مخصّصة لخادم إلى خادم. ولهذا السبب، تستخدم Recall API حسابات الخدمة لمصادقة خادم اللعبة وليس بروتوكول OAuth الثلاثي العادي الذي تستخدمه واجهة برمجة التطبيقات الأخرى للألعاب لمصادقة كلّ من خوادم الألعاب والمستخدمين النهائيين.

3. تنزيل مكتبة Java من جهة الخادم لتطبيق PlayGamesServices

نزِّل أحدث مكتبة google-api-services-games وحمِّلها إلى خادمك.

4. تحضير بيانات الاعتماد لاستدعاءات واجهة برمجة التطبيقات Recall API

راجع التحضير لطلب بيانات من واجهة برمجة التطبيقات المصرّح بها لمزيد من السياق.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

إعداد برنامج اللعبة

يمكنك إعداد برنامج اللعبة لاسترداد معرّفات جلسات الاستدعاء التي يستخدمها الخادم للاتصال بخوادم Google.

حزمة تطوير البرامج (SDK) بلغة Java

عليك إعداد حزمة تطوير البرامج (SDK) بلغة Java في تطبيقك، والتأكّد من تضمين com.google.android.gms:play-services-games-v2:19.0.0 وcom.google.android.gms:play-services-tasks:18.0.2 أو إصدار أحدث في ملف Gradle.

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

Kotlin

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Java

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

Unity SDK

يمكنك إعداد حزمة تطوير البرامج (SDK) لـ Unity ضمن عميلك إذا لم يسبق لك إكمالها.

للاتصال بخوادم Google بالمعلومات الصحيحة، يلزمك طلب معرِّف جلسة Recall من حزمة تطوير البرامج للعميل، وإرساله إلى خادم اللعبة.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

استخدام Recall API في خادم اللعبة

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

تخزين الرموز المميزة

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

يمكنك اختياريًا ضبط مدة البقاء على الرمز المميّز، ما يوضّح مدة صلاحية الرمز المميّز باستخدام عنصر المدة. يمكنك اختيار ضبط هذا الإعداد باستخدام السمة SetTtl() (كما هو موضّح أدناه) التي تحدّد تاريخ انتهاء الصلاحية بدءًا من الوقت المحدّد في الطريقة أو باستخدام setExpireTime() التي تتيح لك ضبط وقت محدّد لانتهاء صلاحية الرموز المميّزة.

عليك تشفير الشخصية والرمز المميز للّعبة، ولا يمكن أن تحتوي هذه الملفات على معلومات تحديد الهوية الشخصية. يمكن أن يبلغ طول سلسلة الشخصية والرمز المميز 256 حرفًا كحد أقصى، ويمكن تخزين 20 رمزًا مميزًا كحد أقصى لكل لاعب في كل لعبة.

يمكن تخزين رمز مميّز واحد فقط لكل شخصية ولكل لاعب في فترة معيّنة. محاولة تخزين رمز مميز آخر بنفس الشخصية تؤدي إلى استبدال الرمز الأصلي.

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

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

استرداد الرموز المميّزة

لاسترداد الرمز المميّز لتذكُّر بيانات الألعاب، عليك الحصول على recallSessionId.

من العميل وتمريره إلى واجهة برمجة تطبيقات retrieveTokens:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

ملاحظة: لا يتم إرجاع السلاسل التي تمثّل الشخصية من خلال واجهة برمجة التطبيقات عند طلب الرموز المميّزة لتذكُّر بيانات الألعاب.

حذف الرمز المميّز لتذكُّر بيانات الألعاب

إذا لزم الأمر، يمكنك أيضًا حذف الرمز المميّز لتذكُّر بيانات الألعاب من خلال الطلب التالي:

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();