PGS Recall API'yi oyununuza entegre edin

Bu sayfada, Recall API'yi oyununuza nasıl entegre edeceğiniz açıklanmaktadır. Öncelikle oyun sunucunuzu ve istemcinizi API'yi destekleyecek şekilde ayarlama, ardından jetonları saklama ve alma işlemleri 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 tamamlanmadıysa) 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

En son google-api-services-games kitaplığını indirin ve 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, sunucunuzun 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 ve com.google.android.gms:play-services-tasks:18.0.2 veya üzeri bir sürümü 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 tamamlanmadıysa Unity SDK'yı istemcinizde 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
    });

Oyun sunucunuzda Recall API'yi kullanma

Sunucunuzu ve istemcinizi yapılandırdıktan sonra recallSessionID 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 talimatları uygulayabilirsiniz.

Jetonları saklama

Kullanıcıların karakteri ve oyun jetonu, LinkPersonaRequest kullanılarak saklanabilir. Google API'lerini çağırmak için GoogleCredential kullanmanız gerekir (Bağlam için Google API'lerini Çağırma başlıklı makaleye bakın). 1:1 kardinalite kısıtlaması uyarınca, her seferinde yalnızca bir karakteri bir PGS profiline (veya tam tersi) bağlayabileceğinizi unutmayın. Bu PGS profili başka bir karaktere zaten bağlanmışsa çözümleme politikasını ayarlamanız gerekir.

İsteğe bağlı olarak, jetonun geçerlilik süresini belirten bir TTL ayarlamayı seçebilirsiniz. Bu işlem için Durations nesnesi kullanılır. Bu ayarı, yöntemde belirtilen süreye göre geçerlilik bitiş tarihini ayarlayan SetTtl() (aşağıda gösterildiği gibi) veya jetonların geçerlilik bitiş tarihi için tam bir zaman belirlemenize olanak tanıyan setExpireTime() simgesini kullanarak ayarlayabilirsiniz.

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. Oyuncu başına oyun başına en fazla 20 jeton veya karakter saklanabilir.

Belirli bir zamanda, oyuncu başına ve karakter başına yalnızca bir jeton saklanabilir. Aynı karakterle başka bir jeton depolamaya çalışmak orijinal jetonun üzerine yazar.

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ına ait tüm oyunlarda saklanan 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 değerini 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 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 sahip olduğu bir oyun listesiyle ilişkili tüm jetonları almak için istemciden recallSessionId alın ve gamesPlayerTokens API'sine iletin. Uygulama kimlikleri listesi 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şlevini aşağıdaki adımları uygulayarak etkinleştirebilirsiniz:

  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 app manifest dosyanıza ekleyin:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Ek şartlar

Play Games Hizmetleri Hizmet Şartları'na tabi olmanın yanı sıra, Recall API'yi PGS profili olmayan kullanıcılar için kullanmanız durumunda (bu API, son kullanıcının verilerinin Google ile Play Games Hizmetleri profili olmadan paylaşılmasını sağlar) söz konusu verileri Google ile paylaşmadan önce son kullanıcıya aşağıdakileri açıklayan uygun bir bildirim sağlamanız gerektiğini kabul edersiniz:

  1. Play Oyunlar hesap bağlantısı özelliğini etkinleştirmek için verileri Google ile paylaşmanız.
  2. Play Games ayarları gibi bu tür paylaşımları yönetmeye yönelik ayarların kullanılabilirliği.
  3. Bu tür verilerin Google Gizlilik Politikası uyarınca işlenmesi ve bu tür paylaşımlar için geçerli tüm yasal koşulları karşılayan uygun son kullanıcı izninin alınması.