توضّح هذه الصفحة كيفية تنفيذ واجهة برمجة التطبيقات 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();
إعداد برنامج تشغيل اللعبة
إعداد برنامج تشغيل اللعبة لاسترداد أرقام تعريف جلسات الإعادة التي يستخدمها خادمك للتواصل مع خوادم 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 باستخدام المعلومات الصحيحة، عليك طلب معرّف جلسة 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 باستخدام المعلومات الصحيحة، عليك طلب معرّف جلسة تذكير من حزمة تطوير البرامج (SDK) للعميل وإرساله إلى خادم لعبتك.
PlayGamesPlatform.Instance.RequestRecallAccess(
recallAccess => {
string recallSessionId = recallAccess.sessionId;
// Send the recallSessionId to your game server
});
استخدام واجهة برمجة التطبيقات Recall API في خادم اللعبة
بعد ضبط الخادم والعميل، يمكنك إرسال recallSessionID
من برنامج تشغيل اللعبة إلى خادم اللعبة واتّباع الإرشادات أدناه لبدء استخدام Java API لتخزين الرموز المميّزة لميزة "الرجوع" أو استرجاعها أو حذفها من جهة الخادم.
تخزين الرموز المميزة
يمكن تخزين شخصية المستخدمين ورمز اللعبة باستخدام عنصر LinkPersonaRequest
. يجب استخدام GoogleCredential
للاتّصال بواجهات برمجة تطبيقات Google (اطّلِع على الاتّصال
بواجهات برمجة تطبيقات
Google
للحصول على السياق). يُرجى العلم أنّه بموجب قيد عدد القيم الفريدة للسمة: 1:1، يمكنك ربط شخصية واحدة فقط
بملف شخصي واحد على "خدمات ألعاب 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
:
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" باتّباع الخطوات التالية:
- فعِّل ميزة تذكُّر بيانات الألعاب بدون ملف شخصي لمشروع لعبتك على "خدمات ألعاب Play" في Play Developer 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، والحصول على موافقة مناسبة من المستخدِم النهائي على هذه المشاركة تستوفي جميع المتطلبات القانونية السارية