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

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

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

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

۱. راه‌اندازی پروژه «خدمات بازی‌های Play»

اگر قبلاً این کار را نکرده‌اید، دستورالعمل‌های راه‌اندازی «خدمات بازی‌های Google Play» را دنبال کنید.

توجه: کدهای فراخوانی و شخصیت‌ها براساس هر پروژه PGS دردسترس هستند. برای پروژه‌های جداگانه «خدمات بازی‌های Play»، مجموعه‌های جداگانه‌ای از پیوندها بین نمایه‌ها و شخصیت‌های «خدمات بازی‌های Play» وجود دارد. برای کسب اطلاعات بیشتر، به اسناد مربوط به راه‌اندازی پروژه‌های PGS مراجعه کنید.

۲. راه‌اندازی حساب سرویس برای بازی

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

توجه: Recall API یک میانای برنامه‌سازی کاربردی سروربه‌سرور است. به‌همین دلیل، Recall API از حساب‌های خدمات برای اصالت‌سنجی سرور بازی استفاده می‌کند، نه OAuth سه-پایه معمولی که توسط دیگر Games API برای اصالت‌سنجی سرورهای بازی و کاربران نهایی استفاده می‌شود.

۳. بارگیری کتابخانه جاوا سمت سرور برای 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();

راه‌اندازی کلاینت بازی

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

کیت توسعه نرم‌افزار Java

کیت توسعه نرم‌افزار 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 را از کیت توسعه نرم‌افزار کارخواه درخواست کنید و آن را به سرور بازی‌تان ارسال کنید.

کاتلین

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

اگر قبلاً این کار را نکرده‌اید، کیت توسعه نرم‌افزار Unity را در کارخواهتان راه‌اندازی کنید.

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

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

کیت توسعه نرم‌افزار بومی نسخه ۲ (بتا)

اگر قبلاً این کار را نکرده‌اید، با «سرویس‌های بازی‌های Play» برای 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()

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

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

ذخیره کردن داده‌واحدها

حساب بازیکن در Google Play Games Recall API از دو بخش اطلاعات تشکیل شده است:

• یک شخصیت که به‌عنوان شناسه پایدار برای حساب درون‌بازی عمل می‌کند
• رمز که به‌عنوان کلید برای ورود ایمن بازیکن به سیستم حساب عمل می‌کند

می‌توانید بااستفاده از شیء LinkPersonaRequest، شخصیت و توکن کاربر را ذخیره کنید. از GoogleCredential برای فراخوانی Google APIs استفاده کنید (برای بافت، به فراخوانی Google APIs مراجعه کنید). شخصیت دارای محدودیت عدد اصلی ۱:۱ است: نمایه «خدمات بازی‌های Play» فقط می‌تواند حاوی یک شخصیت باشد و شخصیت فقط می‌تواند به یک نمایه «خدمات بازی‌های Play» تعلق داشته باشد. خط‌مشی حل‌وفصل پیوندهای متناقض را تنظیم کنید تا تعریف کنید چگونه نقض محدودیت کاردینالیتی ۱:۱ باید حل‌وفصل شود.

درصورت تمایل، زمان انقضای کد را تنظیم کنید. از SetTtl() با شیء Durations برای تنظیم «زمان زندگی» یا ارائه زمان انقضای دقیق با setExpireTime() استفاده کنید.

باید شناسه و کلید بازی را رمزگذاری کنید و این موارد نباید حاوی اطلاعات شناساننده شخصی باشد. رشته‌های توکن و شخصیت می‌توانند حداکثر ۲۵۶ نویسه داشته باشند.

توجه: کلید رمزگذاری استفاده‌شده برای رمزگذاری کردن توکن‌ها باید برای هر برنامه منحصربه‌فرد باشد. اگر بازی به توسعه‌دهنده دیگری منتقل شود، کلید رمزگذاری باید به مالک جدید منتقل شود. کدهای Recall بدون کلید رمزگذاری اصلی رمزگشایی نمی‌شوند.

توجه: کدهای ایجادشده برای کاربران بدون نمایه دارای TTL پیش‌فرض ۳۰ روزه هستند. درغیراین‌صورت، برای کاربران دارای نمایه PGS، کدها TTL پیش‌فرض ندارند.

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
}

بازیابی کدها

براساس نیازهای بازی‌هایتان، سه گزینه برای بازیابی کردن توکن وجود دارد. می‌توانید موارد زیر را درخواست کنید:

• نشان‌های مرتبط با بازی فعلی، ازجمله نشان‌های فراخوانی با دامنه بازی.
• آخرین توکن ذخیره‌شده در همه بازی‌های تحت مالکیت حساب توسعه‌دهنده.
• با داشتن فهرستی از بازی‌های تحت مالکیت حساب توسعه‌دهنده، همه توکن‌های فراخوانی مرتبط با هر بازی.

توجه: وقتی توکن‌های فراخوانی را درخواست می‌کنید، API رشته‌هایی را که نشان‌دهنده شخصیت هستند برنمی‌گرداند.

کدهای فراخوانی با دامنه بازی

برای بازیابی کدهای recall از بازی فعلی، 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»، باید 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» هستند، 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» فعال کنید.
2. شرایط تکمیلی را که در ادامه این بخش شرح داده شده است مرور کنید.
3. برچسب فراداده زیر را به مانیفست برنامه خود اضافه کنید:

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

شرایط تکمیلی

همچنین باید از شرایط خدمات سرویس‌های بازی‌های Play پیروی کنید. اگر از Recall API برای کاربران بدون نمایه «خدمات بازی‌های Play» استفاده می‌کنید، که شامل هم‌رسانی داده‌های کاربر نهایی با Google می‌شود، باید قبل‌از هم‌رسانی این داده‌ها با Google، اعلان مناسبی به کاربران نهایی ارائه دهید که موارد زیر را شرح دهد:

• چگونه داده‌ها را با Google هم‌رسانی می‌کنید تا ویژگی پیوند دادن حساب «بازی‌های Play» فعال شود.
• دردسترس بودن تنظیمات برای مدیریت این هم‌رسانی، برای مثال، ازطریق تنظیمات «بازی‌های Play».
• پردازش این داده‌ها تحت خط‌مشی رازداری Google، و الزام به دریافت رضایت مناسب کاربر نهایی برای این هم‌رسانی که مطابق با همه الزامات قانونی ذی‌ربط باشد.