تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

إعداد مشروعك على "خدمات ألعاب Play"

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

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

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

تنزيل مكتبة Java من جهة الخادم لاستخدام "خدمات ألعاب Play"

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

تحضير بيانات الاعتماد لطلبات 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 باستخدام المعلومات الصحيحة، يمكنك طلب معرّف الجلسة من حزمة تطوير البرامج (SDK) للعميل، وإرساله إلى خادم اللعبة باتّباع الخطوات التالية:

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
  });

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

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

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

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

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

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

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

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();

// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();