Mengintegrasikan PGS Recall API di game Anda

Halaman ini menjelaskan cara menerapkan Recall API ke dalam game Anda. Halaman ini membahas cara menyiapkan server game dan klien untuk mendukung API, lalu membahas cara menyimpan dan mengambil token.

Penyiapan server game

Siapkan server game untuk melakukan panggilan Recall API ke server Google.

1. Menyiapkan project Layanan game Play

(Jika belum selesai) Ikuti petunjuk di Menyiapkan Layanan game Google Play.

Catatan: Token recall dan persona tersedia berdasarkan per project PGS. Artinya, token dan persona akan disimpan per project PGS, dan untuk project PGS terpisah, terdapat kumpulan link terpisah antara profil PGS dan persona. Sebaiknya tinjau dokumentasi ini saat menentukan cara menyiapkan project PGS.

2. Menyiapkan akun layanan untuk game

Ikuti petunjuk tentang cara membuat akun layanan. Pada akhirnya, Anda akan memiliki file JSON dengan kredensial akun layanan.

Catatan: Recall API adalah API server ke server. Oleh karena itu, Recall API menggunakan akun layanan untuk mengautentikasi server game, bukan 3-legged OAuth biasa, yang digunakan oleh Game API lain untuk mengautentikasi server game dan pengguna akhir.

3. Mendownload library Java sisi server untuk Layanan game Play

Download library google-api-services-games terbaru, lalu upload ke server Anda.

4. Menyiapkan kredensial untuk panggilan Recall API

Lihat Menyiapkan panggilan API yang diotorisasi untuk konteks selengkapnya.

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

Penyiapan klien game

Siapkan klien game Anda untuk mengambil ID sesi recall yang digunakan oleh server untuk berkomunikasi dengan server Google.

Java SDK

Siapkan Java SDK di dalam klien Anda, dan pastikan untuk menyertakan com.google.android.gms:play-services-games-v2:19.0.0 dan com.google.android.gms:play-services-tasks:18.0.2 atau yang lebih tinggi dalam file gradle Anda.

Untuk berkomunikasi dengan server Google menggunakan informasi yang benar, Anda perlu meminta ID sesi Recall dari SDK klien yang dikirim ke server game.

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

Jika belum dilakukan, siapkan Unity SDK di dalam klien Anda.

Untuk berkomunikasi dengan server Google menggunakan informasi yang benar, Anda perlu meminta ID sesi Recall dari SDK klien, lalu kirimkan ke server game.

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

Menggunakan Recall API di dalam server game

Setelah mengonfigurasi server dan klien, Anda dapat mengirim recallSessionID dari klien game ke server game, lalu ikuti panduan di bawah ini untuk mulai menggunakan Java API guna menyimpan, mengambil, atau menghapus sisi server token Recall.

Menyimpan token

Persona dan token game pengguna dapat disimpan menggunakan objek LinkPersonaRequest. Anda perlu menggunakan GoogleCredential untuk memanggil Google API (Lihat Memanggil Google API untuk konteks). Perhatikan bahwa, sesuai Batasan kardinalitas 1:1, Anda hanya dapat menautkan satu persona ke satu profil PGS pada satu waktu (dan sebaliknya). Anda harus menetapkan kebijakan resolusi jika profil PGS ini sudah ditautkan dengan persona lain.

Secara opsional, Anda dapat menyetel TTL pada token, yang mendeklarasikan seberapa lama token berlaku menggunakan objek Durasi. Anda dapat menyetelnya dengan menggunakan SetTtl() (seperti yang ditunjukkan di bawah), yang menyetel tanggal kedaluwarsa dari jumlah waktu yang ditentukan dalam metode, atau setExpireTime(), yang memungkinkan Anda menyetel waktu habis masa berlaku token.

Anda harus mengenkripsi persona dan token game, dan keduanya tidak boleh berisi informasi identitas pribadi. Panjang string persona dan token maksimal adalah 256 karakter, dan penyimpanan token atau persona per pemain per game dibatasi sebanyak 20.

Hanya satu token yang dapat disimpan per persona per pemain pada waktu tertentu. Tindakan menyimpan token lain dengan persona yang sama akan menimpa token asli.

Catatan: Kunci enkripsi yang digunakan untuk mengenkripsi token harus unik untuk setiap aplikasi. Jika game ditransfer ke developer lain, kunci enkripsi harus diteruskan ke pemilik baru. Token recall tidak dapat didekripsi tanpa kunci enkripsi asli.

Catatan: Token yang dibuat untuk pengguna tanpa profil memiliki TTL default 30 hari. Jika tidak, untuk pengguna dengan profil PGS, token tidak memiliki TTL default.

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
}

Mengambil token

Ada tiga opsi untuk mengambil token, berdasarkan kebutuhan game Anda. Anda dapat meminta hal berikut:

• Token yang terkait dengan game saat ini, termasuk token recall cakupan game.
• Token terakhir yang disimpan di semua game yang dimiliki oleh akun developer.
• Dengan daftar game yang dimiliki oleh akun developer, semua token recall yang terkait dengan setiap game.

Catatan: Saat Anda meminta token recall, API tidak menampilkan string yang mewakili persona.

Token recall cakupan game

Untuk mengambil token recall dari game saat ini, dapatkan recallSessionId dari klien dan teruskan ke retrieveTokens API:

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
}

Token recall terbaru di semua game yang dimiliki oleh akun developer

Untuk mengambil token terbaru yang disimpan di semua game yang dimiliki oleh akun developer di Konsol Google Play, Anda harus mendapatkan recallSessionId dari klien dan meneruskannya ke lastTokenFromAllDeveloperGames API, seperti yang ditunjukkan dalam cuplikan kode berikut. Sebagai bagian dari respons, Anda dapat memeriksa ID Aplikasi yang terkait dengan token ini.

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.
}

Semua token recall di seluruh daftar game tertentu yang dimiliki oleh akun developer

Untuk mengambil semua token yang terkait dengan daftar game yang dimiliki oleh akun developer Anda di Konsol Google Play, dapatkan recallSessionId dari klien dan teruskan ke gamesPlayerTokens API. Berikan daftar ID Aplikasi.

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.
}

Menghapus token recall

Jika diperlukan, Anda juga dapat menghapus token recall dengan panggilan berikut:

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

Mengaktifkan mode tanpa profil

Anda dapat mengaktifkan fungsi Recall API terbatas untuk pengguna yang tidak memiliki profil PGS dengan mengikuti langkah-langkah berikut:

1. Aktifkan recall tanpa profil untuk project game PGS Anda di Konsol Developer Play.
2. Tinjau istilah tambahan yang dijelaskan nanti di bagian ini.
3. Tambahkan tag metadata berikut ke manifes aplikasi Anda:

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Persyaratan tambahan

Selain tunduk pada Persyaratan Layanan Layanan game Play, Anda setuju bahwa jika Anda menggunakan Recall API untuk pengguna tanpa profil PGS, yang memungkinkan pembagian data pengguna akhir dengan Google tanpa mereka memiliki profil Layanan game Play, Anda harus, sebelum membagikan data tersebut kepada Google, memberikan pemberitahuan yang sesuai kepada pengguna akhir yang menjelaskan hal berikut:

1. Pembagian data Anda dengan Google untuk mengaktifkan fitur penautan akun Play Game.
2. Ketersediaan setelan untuk mengelola berbagi tersebut, seperti melalui setelan Play Game.
3. Pemrosesan data tersebut berdasarkan Kebijakan Privasi Google, dan mendapatkan izin pengguna akhir yang sesuai untuk pembagian tersebut yang memenuhi semua persyaratan hukum yang berlaku.