PGS Recall API'yi oyununuza entegre edin

Bu sayfada, Recall API'sini oyununuzda nasıl uygulayacağınız açıklanmaktadır. İlk olarak oyun sunucunuzu ve istemcinizi API'yi destekleyecek şekilde ayarlamaktan bahsedeceğiz. Ardından jetonların nasıl depolanıp alınacağına değineceğiz.

Oyun sunucusu kurulumu

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

1. Play Games Hizmetleri projenizi oluşturun

(Henüz tamamlanmadıysa) Google Play Oyun Hizmetleri'ni Kurma 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ığı, ayrı PGS projeleri için PGS profilleri ve karakterler arasında ayrı bağlantı koleksiyonları olduğu anlamına gelir. PGS projelerinizi nasıl oluşturacağınızı belirlerken bu dokümanları incelemenizi öneririz.

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

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, yalnızca sunucudan sunucuya API'dir. Bu nedenle Recall API, hizmet hesaplarını oyun sunucusunun kimliğini doğrulamak için kullanır. Diğer Games API'ler tarafından hem oyun sunucularının hem de son kullanıcıların kimliğini doğrulamak için kullanılan normal 3 aşamalı OAuth yöntemini kullanmaz.

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

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

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

Daha fazla bilgi için Yetkili bir API çağrısı yapmaya hazırlanma bölümüne bakın.

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, sunucunuz tarafından Google sunucularıyla iletişim kurmak için kullanılan geri çağırma oturum kimliklerini alacak şekilde ayarlayın.

Java SDK'sı

Java SDK'yı istemcinizde kurun 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 üstünü 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 gerekir. Bu kimliği oyununuzun sunucusuna gönderirsiniz.

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'sı

Henüz yapmadıysanız istemcinizde Unity SDK'yı 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 sunucunuzdaki Recall API'sini kullanın

Sunucunuzu ve istemcinizi yapılandırdıktan sonra recallSessionID öğesini oyun istemcinizden oyun sunucunuza gönderebilir ve aşağıdaki talimatları uygulayarak Recall jetonlarını sunucu tarafında depolamak, almak veya silmek için Java API'yi kullanmaya başlayabilirsiniz.

Mağaza jetonları

Kullanıcının karakteri ve oyun jetonu LinkPersonaRequest nesnesi kullanılarak depolanabilir. Google API'lerini çağırmak için GoogleCredential kullanmanız gerekir (Bağlam için Google API'lerini çağırma konusuna bakın). 1:1 kardinalite kısıtlaması uyarınca, aynı anda yalnızca bir PGS profiline bir karakter bağlayabileceğinizi (veya tam tersi) unutmayın. Bu PGS profilinin zaten başka bir karaktere bağlanmış olması durumunda çözüm politikasını ayarlamanız gerekir.

İsteğe bağlı olarak jeton üzerinde, Durations nesnesi kullanarak jetonun ne kadar süre geçerli olduğunu tanımlayan bir TTL ayarlayabilirsiniz. Son kullanma tarihini yöntemde belirtilen süreye göre ayarlayan SetTtl() (aşağıda gösterildiği gibi) veya jetonların süresinin tam olarak ne zaman dolacağını ayarlamanızı sağlayan setExpireTime() özelliğini kullanarak bunu ayarlayabilirsiniz.

Karakter ve oyun jetonunu şifrelemeniz gerekir. Bunlar 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 depolanabilir.

Belirli bir zamanda, her oyuncu için karakter başına yalnızca bir jeton depolanabilir. Aynı karaktere sahip başka bir jeton depolanmaya çalışıldığında 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 iletilmelidir. Orijinal şifreleme anahtarı olmadan geri çağırma jetonlarının şifresi çözülemez.

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

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

• Oyun kapsamlı geri çağırma jetonları da dahil olmak üzere mevcut oyunla ilişkilendirilen jetonlar.
• Geliştirici hesabına ait tüm oyunlarda depolanan son jeton.
• Geliştirici hesabına ait oyunların listesinde, her bir oyunla ilişkili tüm Recall jetonları yer alır.

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

Oyun kapsamlı geri çağırma jetonları

Mevcut oyundan geri çağırma jetonlarını almak için istemciden recallSessionId öğesini alıp 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 oyunlardaki 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 öğesini alıp lastTokenFromAllDeveloperGames API'sine aşağıdaki kod snippet'inde gösterildiği gibi 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ına ait belirli bir oyun listesindeki tüm Recall jetonları

Google Play Console'da geliştirici hesabınıza ait bir oyun listesiyle ilişkili tüm jetonları almak için istemciden recallSessionId öğesini alıp gamesPlayerTokens API'ye iletin. Bir 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 sil

Gerekirse geri çağırma jetonunu aşağıdaki çağrıyla 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ştir

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 Geliştirici Konsolu'nda 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. Uygulama manifestinize aşağıdaki meta veri etiketini 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 PGS profili olmayan kullanıcılar için Recall API'sini kullanarak tüm uygun gizlilik şartlarını (ör. PGS profili olmayan kullanıcılar için Recall API'sini kullanıyorsanız) bu tür verileri Google ile paylaşmadan önce son kullanıcıya 1) verilerin Google ile paylaşılmasını ve 1) Play Games'in hesap bağlama kullanılabilirliğini etkinleştirmek için geçerli ayarları Google ile paylaşmayı ve