PGS Recall API را در بازی خود ادغام کنید

این صفحه نحوه پیاده سازی Recall API را در بازی خود توضیح می دهد. ابتدا راه اندازی سرور و کلاینت بازی شما برای پشتیبانی از API را پوشش می دهد و سپس نحوه ذخیره و بازیابی توکن ها را بررسی می کند.

راه اندازی سرور بازی

سرور بازی خود را برای برقراری تماس های Recall API با سرورهای Google تنظیم کنید.

1. پروژه Play Games Services خود را راه اندازی کنید

(اگر قبلاً تکمیل نشده باشد) دستورالعمل‌های موجود در راه‌اندازی خدمات بازی‌های Google Play را دنبال کنید.

2. یک حساب سرویس برای بازی راه اندازی کنید

دستورالعمل های ایجاد یک حساب خدمات را دنبال کنید. در پایان باید یک فایل JSON با اعتبار حساب سرویس داشته باشید.

3. دانلود کتابخانه جاوا سمت سرور برای PlayGamesServices

آخرین کتابخانه google-api-services-games را دانلود کنید و آن را در سرور خود آپلود کنید.

4. اعتبارنامه ها را برای تماس های 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();

راه اندازی مشتری بازی

کلاینت بازی خود را برای بازیابی شناسه‌های جلسه فراخوانی که سرور شما برای برقراری ارتباط با سرورهای Google استفاده می‌کند، تنظیم کنید.

جاوا SDK

جاوا SDK را در کلاینت خود تنظیم کنید و مطمئن شوید که com.google.android.gms:play-services-games-v2:19.0.0 و com.google.android.gms:play-services-tasks:18.0.2 یا بالاتر در فایل gradle شما.

برای برقراری ارتباط با سرورهای Google با اطلاعات صحیح، باید یک شناسه جلسه فراخوان را از SDK کلاینت درخواست کنید که آن را به سرور بازی خود ارسال می کنید.

کاتلین 

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

اگر قبلاً تکمیل نشده است، Unity SDK را در کلاینت خود تنظیم کنید .

برای برقراری ارتباط با سرورهای Google با اطلاعات صحیح، باید یک شناسه جلسه فراخوان از SDK کلاینت درخواست کنید و آن را به سرور بازی خود ارسال کنید. 

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

از Recall API در سرور بازی خود استفاده کنید

پس از پیکربندی سرور و کلاینت خود، می توانید recallSessionID را از کلاینت بازی خود به سرور بازی خود ارسال کنید و دستورالعمل های زیر را دنبال کنید تا شروع به استفاده از Java API برای ذخیره، بازیابی یا حذف Recall tokens سمت سرور کنید.

توکن ها را ذخیره کنید

شخصیت و نشانه بازی کاربران را می توان با استفاده از شی LinkPersonaRequest ذخیره کرد. برای تماس با Google APIها باید از GoogleCredential استفاده کنید (برای متن به تماس با Google APIs مراجعه کنید). توجه داشته باشید که با توجه به محدودیت اصلی 1:1 ، می‌توانید هر بار فقط یک پرسونا را به یک نمایه PGS پیوند دهید (و بالعکس). در صورتی که این نمایه PGS قبلاً با پرسونای دیگری مرتبط شده باشد، باید خط‌مشی وضوح را تنظیم کنید.

به صورت اختیاری، می‌توانید یک 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 API ارسال کنید: 

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، باید 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.
}

همه نشانه‌های فراخوان در فهرست معینی از بازی‌های متعلق به حساب توسعه‌دهنده

برای بازیابی همه نشانه‌های مرتبط با فهرستی از بازی‌هایی که متعلق به حساب توسعه‌دهنده شما در کنسول Google Play هستند، 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 ندارند فعال کنید:

  1. فراخوانی بدون پروفایل را برای پروژه بازی PGS خود در Play Developer Console فعال کنید. گزینه ای با عنوان "روشن کردن فضای ذخیره" را انتخاب کنید.
  2. شرایط اضافی توضیح داده شده در ادامه این بخش را مرور کنید.
  3. تگ فراداده زیر را به مانیفست برنامه خود اضافه کنید: 
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

شرایط اضافی

علاوه بر اینکه مشمول شرایط خدمات سرویس‌های بازی‌های Play هستید، موافقت می‌کنید که اگر از Recall API برای کاربران بدون نمایه PGS استفاده می‌کنید، که امکان اشتراک‌گذاری داده‌های کاربر نهایی با Google را بدون داشتن نمایه خدمات بازی‌های Play فراهم می‌کند، باید: قبل از اشتراک‌گذاری چنین داده‌هایی با Google، اخطار مناسب را در اختیار کاربر نهایی قرار دهید که 1) اشتراک‌گذاری داده‌ها با Google را برای فعال کردن ویژگی پیوند حساب بازی‌های Play، 2) در دسترس بودن تنظیمات برای مدیریت چنین اشتراک‌گذاری‌هایی مانند مواردی که از طریق بازی‌های Play انجام می‌شود، شرح دهد. تنظیمات، و 3) پردازش چنین داده‌هایی تحت خط‌مشی رازداری Google ، و کسب رضایت کاربر نهایی مناسب برای چنین اشتراک‌گذاری که همه الزامات قانونی قابل اجرا را برآورده می‌کند.