این صفحه نحوه پیادهسازی 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
    });
از 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 را بدون داشتن نمایه سرویسهای بازیهای Play فراهم میکند، باید قبل از اشتراکگذاری چنین دادههایی با Google، به کاربر نهایی اطلاعیه مناسبی با شرح موارد زیر ارائه دهید:
- اشتراکگذاری دادهها با گوگل برای فعال کردن قابلیت اتصال حساب کاربری Play Games.
 - در دسترس بودن تنظیماتی برای مدیریت چنین اشتراکگذاریهایی، مانند تنظیمات بازیهای Play.
 - پردازش چنین دادههایی تحت سیاست حفظ حریم خصوصی گوگل ، و کسب رضایت کاربر نهایی مناسب برای چنین اشتراکگذاری که تمام الزامات قانونی مربوطه را برآورده میکند.