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

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

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

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

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

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

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

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

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

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

إعداد برنامج لعبتك لاسترداد أرقام تعريف جلسات Recall التي يستخدمها الخادم للتواصل مع خوادم Google

Java SDK

إعداد حزمة تطوير البرامج (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 APIs للحصول على السياق). يُرجى العِلم أنّه وفقًا لقيد التوافق بين العناصر بنسبة 1:1، يمكنك ربط شخصية واحدة فقط بملف واحد على "خدمات ألعاب Play" في كل مرة (والعكس صحيح).يجب ضبط سياسة الحل في حال تم ربط ملف "خدمات ألعاب Play" هذا بشخصية أخرى من قبل.

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

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.
}

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

لاسترداد جميع الرموز المميزة المرتبطة بقائمة من الألعاب التي يملكها حساب المطوِّر الخاص بك في 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" />

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

بالإضافة إلى الخضوع لبنود خدمة &quot;خدمات ألعاب Play&quot;، أنت توافق على أنّه في حال استخدامك لواجهة Recall API للمستخدمين الذين ليس لديهم ملف شخصي على &quot;خدمات ألعاب Play&quot;، ما يتيح مشاركة بيانات المستخدم النهائي مع Google بدون أن يكون لديه ملف شخصي على &quot;خدمات ألعاب Play&quot;، عليك تقديم إشعار مناسب للمستخدم النهائي قبل مشاركة هذه البيانات مع Google، ويجب أن يصف الإشعار ما يلي:

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