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

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

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

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

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

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

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

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

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

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

4. إعداد بيانات الاعتماد الخاصة باستدعاءات واجهة برمجة التطبيقات Recall

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

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 من حزمة تطوير البرامج (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
    });

Unity SDK

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

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

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

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

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

الرموز المميّزة للمتجر

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

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

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

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

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
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 API:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

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
}

أحدث رمز مميّز لتذكُّر بيانات الألعاب في جميع الألعاب التي يملكها حساب المطوِّر

لاسترداد أحدث رمز مميّز مخزّن في جميع الألعاب التي يملكها حساب المطوّر في Google Play Console، يجب الحصول على recallSessionId من العميل وإدخاله في واجهة برمجة تطبيقات lastTokenFromAllDeveloperGames، كما هو موضّح في مقتطف الرمز التالي. كجزء من الردّ، يمكنك فحص معرّف التطبيق المرتبط بهذا الرمز المميّز.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

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

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

جميع رموز Recall المميّزة في قائمة معيّنة من الألعاب التي يملكها حساب المطوِّر

لاسترداد جميع الرموز المميّزة المرتبطة بقائمة ألعاب يملكها حساب المطوِّر الخاص بك في Google Play Console، احصل على recallSessionId من العميل وأرسِله إلى واجهة برمجة التطبيقات gamesPlayerTokens. قدِّم قائمة بمعرّفات التطبيقات.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

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

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();
    
    // Decrypt and recover in-game account.
}

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

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

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

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

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

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

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

الأحكام الإضافية

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