PGS Recall API'yi oyununuza entegre edin

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

Oyun sunucusu kurulumu

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

1. Play Oyun Hizmetleri projenizi oluşturma

(Henüz tamamlamadıysanız) Google Play Games Hizmetleri'ni Kurma bölümündeki talimatları uygulayın.

Not: Geri çağırma jetonları ve karakterleri, PYS projesi bazında kullanılabilir. Bu, jetonların ve karakterlerin PGS projesi başına depolandığı ve ayrı PGS projeleri için PGS profilleri ve karakterleri 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. Son olarak hizmet hesabı kimlik bilgilerini içeren bir JSON dosyanız olur.

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

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

En yeni 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 Yetkilendirilmiş 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 oturumu kimliklerini alacak şekilde ayarlayın.

Java SDK'sı

İstemcinizde Java SDK'yı 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 oyununuzun sunucusuna göndereceğiniz bir Recall oturum kimliği istemeniz 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'sı

Henüz tamamlamadıysanız istemcinizde Unity SDK'yı kurun.

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

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

Oyun sunucunuzda Recall API'sini kullanma

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

Mağaza jetonları

Kullanıcıların karakteri 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 PGS profiline karakter bağlayabileceğinizi (veya tam tersi) unutmayın. Bu PGS profilinin zaten başka bir karaktere bağlanmış olması ihtimaline karşı çözüm politikasını belirlemeniz gerekir.

İsteğe bağlı olarak jeton üzerinde bir TTL ayarlamayı seçebilirsiniz. Bu, bir Durations nesnesi kullanarak jetonun ne kadar süre geçerli olduğunu beyan eder. Sona erme tarihini yöntemde belirtilen süreye göre belirleyen SetTtl() (aşağıda gösterildiği gibi) ya da jetonların süresinin dolacağı kesin zamanı 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 ve oyun başına oyuncu başına en fazla 20 jeton veya karakter saklanabilir.

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 aktarılmalıdır. 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.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

Geri çağırma jetonunu almak için recallSessionId kodunu almanız gerekir

istemciden alıp retrieveTokens API'ye iletin:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

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
}

Not: Geri çağırma jetonları istenirken karakteri temsil eden dizeler API aracılığıyla geri döndürülmez.

Geri çağırma jetonunu sil

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

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

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