توضّح هذه الصفحة كيفية تنفيذ 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 لتخزين الرموز المميزة لـ "تسجيل الدخول السريع" أو استردادها أو حذفها من جهة الخادم.
رموز المتجر المميزة
يتألف حساب اللاعب في واجهة برمجة التطبيقات Recall API في "ألعاب Google Play" من جزأين من المعلومات:
- شخصية تعمل كمعرّف ثابت لحساب داخل اللعبة
- رمز مميّز يعمل كمفتاح لتسجيل دخول اللاعب إلى الحساب بأمان
يمكنك تخزين شخصية المستخدم ورمزه المميّز باستخدام عنصر LinkPersonaRequest. استخدِم GoogleCredential لطلب بيانات من Google APIs (راجِع طلب بيانات من Google APIs للحصول على السياق). تتضمّن الشخصية قيدًا على عدد العناصر إلى العناصر: يمكن أن يتضمّن ملف شخصي واحد على "خدمات Google" شخصية واحدة فقط، ولا يمكن أن توجد الشخصية إلا في ملف شخصي واحد على "خدمات Google". اضبط سياسة حلّ الروابط المتعارضة لتحديد كيفية حلّ انتهاكات قيود التعددية 1:1.
يمكنك اختياريًا ضبط وقت انتهاء صلاحية الرمز المميّز. استخدِم SetTtl() مع عنصر Durations لضبط مدة البقاء أو تقديم وقت انتهاء صلاحية دقيق باستخدام setExpireTime().
يجب تشفير رمز الأفاتار ورمز اللعبة، ويجب ألا يحتويان على معلومات تحديد الهوية الشخصية. يمكن أن يصل طول السلسلة المميزة للشخصية والرمز المميّز إلى 256 حرفًا كحد أقصى.
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 للمستخدمين الذين ليس لديهم ملفات شخصية في "خدمات Google Play للألعاب" باتّباع الخطوات التالية:
- فعِّل ميزة "تذكُّر بيانات الألعاب بدون ملف شخصي" لمشروع لعبتك على "خدمات ألعاب Play" في Play Console.

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