این صفحه نحوه پیادهسازی Recall API را در بازی شما توضیح میدهد. ابتدا تنظیمات سرور و کلاینت بازی شما برای پشتیبانی از API را پوشش میدهد و سپس نحوه ذخیره و بازیابی توکنها را توضیح میدهد.
راه اندازی سرور بازی
سرور بازی خود را طوری تنظیم کنید که فراخوانیهای Recall API را به سرورهای گوگل انجام دهد.
۱. پروژه خدمات بازیهای Play خود را راهاندازی کنید
اگر قبلاً این کار را نکردهاید، دستورالعملهای موجود در «راهاندازی سرویسهای بازیهای گوگل پلی» را دنبال کنید.
۲. یک حساب کاربری سرویس برای بازی تنظیم کنید
دستورالعملهای ایجاد یک حساب کاربری سرویس را دنبال کنید. در پایان، باید یک فایل JSON حاوی اطلاعات حساب کاربری سرویس داشته باشید.
۳. دانلود کتابخانه جاوا سمت سرور برای PlayGamesServices
کتابخانه google-api-services-games را دانلود کرده و آن را روی سرور خود آپلود کنید.
۴. آمادهسازی اعتبارنامهها برای فراخوانیهای Recall API
برای اطلاعات بیشتر، به بخش آمادهسازی برای برقراری یک فراخوانی 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();
تنظیم کلاینت بازی
کلاینت بازی خود را طوری تنظیم کنید که شناسههای جلسه فراخوانی مورد استفاده سرور ما برای ارتباط با سرورهای گوگل را بازیابی کند.
کیت توسعه نرمافزار جاوا
SDK جاوا را درون کلاینت خود تنظیم کنید و مطمئن شوید که com.google.android.gms:play-services-games-v2:19.0.0 و com.google.android.gms:play-services-tasks:18.0.2 یا نسخههای جدیدتر را در فایل Gradle خود قرار دادهاید.
برای برقراری ارتباط با سرورهای گوگل با اطلاعات صحیح، باید از SDK کلاینت، یک شناسه جلسه فراخوانی (Recall session ID) درخواست کنید که آن را به سرور بازی خود ارسال میکنید.
کاتلین
PlayGames.getRecallClient(getActivity())
.requestRecallAccess()
.addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
// Send the recallSessionId to your game server
جاوا
PlayGames.getRecallClient(getActivity())
.requestRecallAccess()
.addOnSuccessListener(
recallAccess -> {
String recallSessionId = recallAccess.getSessionId();
// Send the recallSessionId to your game server
});
کیت توسعه نرمافزاری یونیتی
اگر هنوز این کار را انجام ندادهاید، Unity SDK را در کلاینت خود راهاندازی کنید .
برای برقراری ارتباط با سرورهای گوگل با اطلاعات صحیح، باید یک شناسه جلسه Recall از SDK کلاینت درخواست کنید و آن را به سرور بازی خود ارسال کنید.
PlayGamesPlatform.Instance.RequestRecallAccess(
recallAccess => {
string recallSessionId = recallAccess.sessionId;
// Send the recallSessionId to your game server
});
SDK بومی نسخه ۲ (بتا)
اگر هنوز این کار را نکردهاید، با Play Games Services for C و C++ شروع کنید .
// Include the following headers
#include "play_games.h"
#include "recall_client.h"
#include "pgs_status_code.h"
// Request Recall Access
// Initializes the Play Games Services v2 Native SDK (beta).
Pgs_initialize(javaVM, activity);
//Creating Recall Client
PgsRecallClient* pgs_recall_client =
PgsRecallClient_create(activity);
// RequestRecallAccess Function
PgsRecallClient_requestRecallAccess(
pgs_recall_client,
// This is your callback function defined as an inline lambda
[](PgsStatusCode status_code, char* session_id, user_data) {
if (status_code == PGS_STATUS_SUCCESS) {
// Recall Session Id Fetched Successfully
} else {
// Fetching Recall Session Id Failed
// Handle error based on status_code.
// Examples:
// PGS_STATUS_NETWORK_ERROR: Check internet connection.
// PGS_STATUS_INTERNAL_ERROR: An unexpected error occurred.
}
// Clean up the client instance passed as user_data
PgsRecallClient* client = static_cast<PgsRecallClient*>(user_data);
if (client != nullptr) {
PgsRecallClient_destroy(client);
}
},
user_data // Data to pass to the callback
);
// Shuts down the Play Games Services v2 Native SDK (beta).
Pgs_destroy()
از API Recall در سرور بازی خود استفاده کنید
پس از پیکربندی سرور و کلاینت، میتوانید recallSessionID از کلاینت بازی خود به سرور بازی ارسال کنید و برای شروع استفاده از API جاوا جهت ذخیره، بازیابی یا حذف توکنهای Recall در سمت سرور، دستورالعملهای زیر را دنبال کنید.
توکنهای فروشگاه
یک حساب کاربری بازیکن در API مربوط به فراخوانی بازیهای گوگل پلی شامل دو بخش اطلاعات است:
- یک پرسونا که به عنوان شناسه پایدار برای یک حساب کاربری درون بازی عمل میکند
- یک توکن که به عنوان کلید ورود ایمن یک بازیکن به حساب کاربری عمل میکند
شما میتوانید با استفاده از شیء LinkPersonaRequest شخصیت و توکن کاربر را ذخیره کنید. از GoogleCredential برای فراخوانی APIهای گوگل استفاده کنید (برای آشنایی با زمینه، به بخش فراخوانی APIهای گوگل مراجعه کنید). یک شخصیت دارای محدودیت کاردینالیتی ۱:۱ است: یک پروفایل PGS میتواند فقط شامل یک شخصیت باشد و یک شخصیت میتواند فقط به یک پروفایل PGS تعلق داشته باشد. سیاست حل تداخل لینکها را طوری تنظیم کنید که نحوه رفع نقض محدودیت کاردینالیتی ۱:۱ را تعریف کند.
به صورت اختیاری میتوانید زمان انقضای توکن را تنظیم کنید. از SetTtl() به همراه یک شیء Durations برای تنظیم زمان ماندگاری استفاده کنید یا با setExpireTime() زمان انقضای دقیق را ارائه دهید.
شما باید شخصیت و توکن بازی را رمزگذاری کنید و آنها نمیتوانند حاوی اطلاعات شخصی قابل شناسایی باشند. رشتههای شخصیت و توکن میتوانند حداکثر ۲۵۶ کاراکتر داشته باشند.
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 از کلاینت دریافت کرده و آن را به API 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
}
آخرین توکن فراخوان در تمام بازیهای متعلق به حساب توسعهدهنده
برای بازیابی جدیدترین توکن ذخیره شده در تمام بازیهای متعلق به حساب توسعهدهنده در کنسول گوگل پلی، باید recallSessionId از کلاینت دریافت کرده و آن را به lastTokenFromAllDeveloperGames API ارسال کنید، همانطور که در قطعه کد زیر نشان داده شده است. به عنوان بخشی از پاسخ، میتوانید شناسه برنامه مرتبط با این توکن را بررسی کنید.
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.
}
تمام توکنهای فراخوانی در فهرست مشخصی از بازیهای متعلق به حساب توسعهدهنده
برای بازیابی تمام توکنهای مرتبط با لیستی از بازیهایی که متعلق به حساب توسعهدهنده شما در کنسول گوگل پلی هستند، recallSessionId از کلاینت دریافت کرده و آن را به API 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 را برای کاربرانی که پروفایل PGS ندارند، فعال کنید:
- فراخوانی بدون پروفایل را برای پروژه بازی PGS خود در کنسول توسعهدهندگان Play فعال کنید.

- اصطلاحات اضافی که بعداً در این بخش توضیح داده شده است را مرور کنید.
- تگ متادیتای زیر را به مانیفست برنامه خود اضافه کنید:
<meta-data
android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
android:value="true" />
شرایط اضافی
شما همچنین باید از شرایط خدمات سرویسهای بازیهای Play پیروی کنید. اگر از API Recall برای کاربران بدون نمایه PGS استفاده میکنید، که شامل اشتراکگذاری دادههای کاربر نهایی با Google میشود، باید قبل از اشتراکگذاری این دادهها با Google، به کاربران نهایی یک اطلاعیه مناسب ارائه دهید که موارد زیر را شرح دهد:
- نحوه اشتراکگذاری دادهها با گوگل برای فعال کردن ویژگی پیوند حساب بازیهای Play.
- در دسترس بودن تنظیماتی برای مدیریت این اشتراکگذاری، برای مثال، از طریق تنظیمات بازیهای Play.
- پردازش این دادهها تحت سیاست حفظ حریم خصوصی گوگل ، و الزام به کسب رضایت مناسب از کاربر نهایی برای این اشتراکگذاری که تمام الزامات قانونی مربوطه را برآورده کند.