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ı depolama 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 yapmadıysanız Google Play Games Hizmetleri'ni ayarlama bölümündeki talimatları uygulayın.

Not: Geri çağırma jetonları ve karakterler, PGS projesi bazında 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ının olduğu anlamına gelir. PGS projelerinizi nasıl ayarlayacağınızı belirlerken bu dokümanı incelemenizi öneririz.

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.

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

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

En son 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'sını istemcinizde ayarlayın ve com.google.android.gms:play-services-games-v2:19.0.0

ve com.google.android.gms:play-services-tasks:18.0.2 veya sonraki bir sürümünü kullanın.

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 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 Persona
• 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: Tek bir PGS profilinde yalnızca tek bir karakter bulunabilir ve bir karakter yalnızca tek bir PGS profilinde yer alabilir. 1:1 kardinalite kısıtlaması ihlallerinin nasıl çözüleceğini tanımlamak için çakışan bağlantı çözünürlüğü 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()'ı Durations nesnesiyle birlikte 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.

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 iletilmelidir. Geri çağırma jetonlarının şifresi, orijinal şifreleme anahtarı olmadan çözülemez.

Not: Profilsiz kullanıcılar için oluşturulan jetonların varsayılan TTL'si 30 gündür. Aksi takdirde, PGS profili olan kullanıcılar için jetonların varsayılan bir 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 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ı.

Not: Geri çağırma jetonları istediğinizde API, karakteri temsil eden dizeleri döndürmez.

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 alıp 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 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.
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

Play Games Hizmet Şartları'na tabi olmanın yanı sıra, son kullanıcının verilerinin Google ile Play Games Hizmetleri profili olmadan paylaşılmasını sağlayan Recall API'yi PGS profili olmayan kullanıcılar için kullanmanız durumunda, bu verileri Google ile paylaşmadan önce son kullanıcıya aşağıdakileri açıklayan uygun bir bildirimde bulunmanı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 şartları karşılayan uygun son kullanıcı izninin alınması.