PGS Recall API'yi oyununuza entegre edin

Bu sayfada, Recall API'nin oyununuza nasıl entegre edileceği açıklanmaktadır. Öncelikle oyun sunucunuzu ve istemcinizi API'yi destekleyecek şekilde ayarlama, ardından jetonları saklama ve alma yöntemleri açıklanır.

Oyun sunucusu kurulumu

Oyun sunucunuzu, Google sunucularına Recall API çağrıları yapacak şekilde ayarlayın.

1. Play Oyun Hizmetleri projenizi ayarlama

Henüz yapmadıysanız Google Play Games Hizmetleri'ni ayarlama bölümündeki talimatları uygulayın.

2. Oyun için hizmet hesabı oluşturma

Hizmet hesabı oluşturma talimatlarını uygulayın. Sonunda, hizmet hesabı kimlik bilgilerini içeren bir JSON dosyanız olmalıdır.

3. PlayGamesServices için sunucu taraflı Java kitaplığını indirin

google-api-services-games kitaplığını indirip sunucunuza yükleyin.

4. Recall API çağrıları için kimlik bilgileri hazırlama

Daha fazla bilgi için Yetkili bir API çağrısı yapmaya hazırlanma başlıklı makaleyi inceleyin.

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();

Oyun istemcisi kurulumu

Oyun istemcinizi, sunucumuzun Google sunucularıyla iletişim kurmak için kullandığı geri çağırma oturumu kimliklerini alacak şekilde ayarlayın.

Java SDK'sı

Java SDK'yı istemcinizde ayarlayın ve Gradle dosyanıza com.google.android.gms:play-services-games-v2:19.0.0 com.google.android.gms:play-services-tasks:18.0.2 veya sonraki sürümleri eklediğinizden emin olun.

Google'ın sunucularıyla doğru bilgilerle iletişim kurmak için istemci SDK'sından bir geri çağırma oturumu kimliği isteyip bu kimliği oyununuzun sunucusuna göndermeniz gerekir.

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

Henüz yapmadıysanız istemcinizde Unity SDK'sını ayarlayın.

Google'ın sunucularıyla doğru bilgilerle iletişim kurmak için istemci SDK'sından bir geri çağırma oturumu kimliği istemeniz ve bunu oyununuzun sunucusuna göndermeniz gerekir.

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

v2 Native SDK (beta)

Henüz yapmadıysanız C ve C++ için Play Games Hizmetleri'ni kullanmaya başlayın.

// 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()

Oyun sunucunuzda Recall API'yi kullanma

Sunucunuzu ve istemcinizi yapılandırdıktan sonra recallSessionID değerini oyun istemcinizden oyun sunucunuza gönderebilir ve Recall jetonlarını sunucu tarafında saklamak, almak veya silmek için Java API'yi kullanmaya başlamak üzere aşağıdaki yönergeleri uygulayabilirsiniz.

Jetonları saklama

Google Play Games Recall API'deki bir oyuncu hesabı iki bilgi parçasından oluşur:

  • Oyun içi hesap için sabit tanımlayıcı olarak kullanılan bir Karakter
  • Oyuncunun hesaba güvenli bir şekilde giriş yapmasını sağlayan anahtar görevi gören bir jeton

LinkPersonaRequest nesnesini kullanarak kullanıcının kişiliğini ve jetonunu saklayabilirsiniz. Google API'lerini çağırmak için GoogleCredential kullanın (Bağlam için Google API'lerini Çağırma bölümüne bakın). Karakterlerin 1:1 kardinalite kısıtlaması vardır: Bir PGS profilinde yalnızca bir karakter olabilir ve bir karakter yalnızca bir PGS profiline ait olabilir. 1:1 kardinalite kısıtlaması ihlallerinin nasıl çözüleceğini tanımlamak için çakışan bağlantı çözümü politikasını ayarlayın.

İsteğe bağlı olarak jetonun geçerlilik süresini ayarlayın. Bir yaşam süresi ayarlamak veya setExpireTime() ile tam bir geçerlilik bitiş zamanı sağlamak için SetTtl() ile Durations nesnesini kullanın.

Karakter ve oyun jetonunu şifrelemeniz gerekir. Bu jetonlar, kimliği tanımlayabilecek bilgiler içeremez. Karakter ve jeton dizeleri en fazla 256 karakter uzunluğunda olabilir.

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
}

Jetonları alma

Oyunlarınızın ihtiyaçlarına bağlı olarak jeton almak için üç seçenek vardır. Aşağıdakileri talep edebilirsiniz:

  • Oyun kapsamlı geri çağırma jetonları da dahil olmak üzere mevcut oyunla ilişkili jetonlar.
  • Geliştirici hesabının sahip olduğu tüm oyunlarda depolanan son jeton.
  • Geliştirici hesabına ait oyunların listesi verildiğinde, her oyunla ilişkili tüm geri çağırma jetonları.

Oyun kapsamlı geri çağırma jetonları

Recall jetonlarını mevcut oyundan almak için istemciden recallSessionId alın ve retrieveTokens API'sine iletin:

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
}

Geliştirici hesabının sahip olduğu tüm oyunlardaki en son geri çağırma jetonu

Google Play Console'da geliştirici hesabının sahip olduğu tüm oyunlarda depolanan en son jetonu almak için istemciden recallSessionId değerini almanız ve aşağıdaki kod snippet'inde gösterildiği gibi lastTokenFromAllDeveloperGames API'sine iletmeniz gerekir. Yanıtın bir parçası olarak bu jetonla ilişkili Uygulama Kimliği'ni inceleyebilirsiniz.

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.
}

Geliştirici hesabının sahip olduğu belirli bir oyun listesindeki tüm geri çağırma jetonları

Google Play Console'da geliştirici hesabınızın sahibi olduğu bir oyun listesiyle ilişkili tüm jetonları almak için istemciden recallSessionId alın ve gamesPlayerTokens API'sine iletin. Uygulama kimliklerinin listesini sağlayın.

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.
}

Geri çağırma jetonunu silme

Gerekirse aşağıdaki çağrıyla geri çağırma jetonunu da silebilirsiniz:

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();

Profilsiz modu etkinleştirme

PGS profili olmayan kullanıcılar için sınırlı Recall API işlevselliğini etkinleştirmek istiyorsanız aşağıdaki adımları uygulayın:

  1. Play Console'da PGS oyun projeniz için profilsiz geri çağırmayı etkinleştirin. &quot;Depolamayı aç&quot; etiketli seçeneği belirleyin.
  2. Bu bölümün ilerleyen kısımlarında açıklanan ek şartları inceleyin.
  3. Aşağıdaki meta veri etiketini uygulama manifestinize ekleyin:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Ek şartlar

Ayrıca Play Games Hizmetleri Hizmet Şartları'na da uymanız gerekir. Son kullanıcı verilerinin Google ile paylaşılmasını içeren PGS profili olmayan kullanıcılar için Geri Çağırma API'sini kullanıyorsanız bu verileri Google ile paylaşmadan önce son kullanıcılara aşağıdakileri açıklayan uygun bir bildirim sağlamanız gerekir:

  • Play Oyunlar hesap bağlantısı özelliğini etkinleştirmek için Google ile nasıl veri paylaştığınız
  • Bu paylaşımı yönetmek için kullanılabilecek ayarların (ör. Play Games ayarları) durumu.
  • Bu verilerin Google Gizlilik Politikası uyarınca işlenmesi ve bu paylaşım için geçerli tüm yasal şartları karşılayan uygun son kullanıcı izninin alınması zorunluluğu.