دمج واجهة برمجة التطبيقات 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

إعداد حزمة Java SDK في العميل، وتأكَّد من تضمين 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. اتّباع قيد عدد القيم الفريدة للسمة هو 1:1 : يمكنك ربط شخصية واحدة فقط بملف شخصي واحد على PGS في كل مرة، والعكس صحيح. اضبط سياسة القرار في حال سبق أن تم ربط ملف تعريف PGS هذا بشخصيّة أخرى.

يمكنك اختياريًا ضبط مدة بقاء (TTL) على الرمز المميّز مع توضيح مدة فإن الرمز صالح باستخدام 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();

تفعيل وضع "بدون ملف شخصي"

يمكنك تفعيل وظائف محدودة لواجهة برمجة التطبيقات Recall API للمستخدمين الذين ليس لديهم ملفات شخصية في "خدمات ألعاب Play" باتّباع الخطوات التالية:

  1. تفعيل ميزة التذكُّر بدون ملف شخصي لمشروع لعبتك على "خدمات ألعاب Play" في مطوّر برامج Play وحدة التحكم. حدد الخيار المسمى
  2. راجِع البنود الإضافية الموضّحة لاحقًا في هذا القسم.
  3. إضافة علامة البيانات الوصفية التالية إلى تطبيقك manifest:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

البنود الإضافية

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