PGS Recall API'yi oyununuza entegre edin

Bu sayfada, Recall API'nin oyununuza nasıl uygulanacağı açıklanmaktadır. Öncelikle oyun sunucunuzu ve istemcinizi API'yi destekleyecek şekilde ayarlamayı, ardından jetonları nasıl depolayacağınızı ve alacağınızı ele alır.

Oyun sunucusu kurulumu

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

1. Play Games Hizmetleri projenizi ayarlama

(Henüz tamamlanmadıysa) Google Play Games Hizmetleri'ni kurma başlıklı makaledeki talimatları uygulayın.

Not: Geri çağırma jetonları ve karakterler, PGS projesi başına kullanılabilir. Bu, jetonların ve karakterlerin PGS projesi başına depolandığı ve ayrı PGS projeleri için PGS profilleri ile karakterler arasında ayrı bağlantı koleksiyonları bulunduğu anlamına gelir. PGS projelerinizi nasıl oluşturacağınızı belirlerken bu dokümanları

incelemenizi öneririz.

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

Hizmet hesabı oluşturma ile ilgili talimatları uygulayın. İşlem sonunda, hizmet hesabı kimlik bilgilerini içeren bir JSON dosyanız olur.

Not: Recall API, sunucudan sunucuya bir API'dir. Bu nedenle Recall API, hem oyun sunucularının hem de son kullanıcıların kimliğini doğrulamak için diğer Games API'leri tarafından kullanılan normal 3 aşamalı OAuth'ı değil, oyun sunucusunun kimliğini doğrulamak için hizmet hesaplarını kullanır.

3. PlayGamesServices için sunucu tarafı Java kitaplığını indirme

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

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

Daha fazla bilgi için Yetkili 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'sını istemcinizde ayarlayın ve gradle dosyanıza com.google.android.gms:play-services-games-v2:19.0.0 ile com.google.android.gms:play-services-tasks:18.0.2 veya daha yeni 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 Recall oturum kimliği istemeniz ve bu kimliği oyun sunucunuza 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'sını istemcinizde ayarlayın.

Google'ın sunucularıyla doğru bilgilerle iletişim kurmak için istemci SDK'sından bir Recall oturum 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, oyun istemcinizden oyun sunucunuza recallSessionID gönderebilir ve Recall jetonlarını sunucu tarafında depolamak, almak veya silmek için Java API'yi kullanmaya başlamak üzere aşağıdaki talimatları uygulayabilirsiniz.

Mağaza jetonları

Kullanıcıların kimliği ve oyun jetonu, LinkPersonaRequest nesnesi kullanılarak saklanabilir. Google API'lerini çağırmak için GoogleCredential kullanmanız gerekir (Bağlam için Google API'lerini çağırma bölümüne bakın). 1:1 kardinalite kısıtlaması uyarınca, aynı anda yalnızca bir persona'yı bir PGS profiline bağlayabileceğinizi (ve bunun tam tersini) unutmayın. Bu PGS profilinin başka bir persona'ya bağlı olması durumunda çözüm politikasını ayarlamanız gerekir.

İsteğe bağlı olarak, jetonda bir TTL ayarlayabilirsiniz. Bu ayar, Durations nesnesi kullanılarak jetonun ne kadar süreyle geçerli olacağını belirtir. Bunu, 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 süresinin sona ereceği tam zamanı ayarlamanıza olanak tanıyan setExpireTime() kullanarak ayarlayabilirsiniz.

Kimliği tanımlayabilecek bilgiler içermemesi gereken kimlik ve oyun jetonunu şifrelemeniz gerekir. Kişi ve jeton dizeleri en fazla 256 karakter uzunluğunda olabilir. Ayrıca, oyun başına oyuncu başına en fazla 20 jeton veya kişi depolanabilir.

Belirli bir zamanda oyuncu başına yalnızca bir jeton saklanabilir. Aynı kişiliğe sahip başka bir jeton depolamaya çalışırken orijinal jetonun üzerine yazılır.

Not: Jetonları şifrelemek için kullanılan şifreleme anahtarı her uygulama için benzersiz olmalıdır. Oyun başka bir geliştiriciye aktarılırsa şifreleme anahtarı yeni sahibe aktarılmalıdır. Geri çağırma jetonlarının şifresi, orijinal şifreleme anahtarı olmadan çözülemez.

Not: Profili olmayan kullanıcılar için oluşturulan jetonların varsayılan TTL'si 30 gündür. Aksi takdirde, PGS profiline sahip kullanıcılar için jetonların varsayılan TTL'si yoktur.

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 isteyebilirsiniz:

• 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 ve her oyunla ilişkili tüm geri çağırma jetonları.

Not: Hatırlatma jetonu istediğinizde API, kişiliği temsil eden dizeler döndürmez.

Oyun kapsamlı geri çağırma jetonları

Mevcut oyundan geri çağırma jetonlarını almak için istemciden recallSessionId'yi 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ına ait tüm oyunlarda en son geri çağırma jetonu

Google Play Console'da geliştirici hesabına ait 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'ye iletmeniz gerekir. Yanıtın bir parçası olarak bu jetonla ilişkili uygulama kimliğini 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ına ait belirli bir oyun listesinde bulunan tüm geri çağırma jetonları

Google Play Console'da geliştirici hesabınıza ait oyunların listesiyle ilişkili tüm jetonları almak için istemciden recallSessionId değerini alın ve gamesPlayerTokens API'ye aktarın. 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şlevini etkinleştirmek istiyorsanız aşağıdaki adımları uygulayın:

1. Play Console'da PGS oyun projeniz için profilsiz geri çağırma özelliğini etkinleştirin.
2. Bu bölümün ilerleyen kısmı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

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

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