Zintegruj interfejs PGS Recall API ze swoją grą

Na tej stronie dowiesz się, jak zaimplementować interfejs Recall API w swojej grze. Najpierw omówimy konfigurację serwera i klienta gry pod kątem obsługi interfejsu API, a następnie wyjaśnimy, jak przechowywać i pobierać tokeny.

Konfiguracja serwera gry

Skonfiguruj serwer gry, aby wywoływać interfejs Recall API na serwerach Google.

1. Skonfiguruj projekt usług gier Play

Jeśli jeszcze tego nie zrobisz, postępuj zgodnie z instrukcjami w artykule Konfigurowanie usług gier Google Play.

2. Skonfiguruj konto usługi dla gry

Postępuj zgodnie z instrukcjami tworzenia konta usługi. Na koniec powinieneś mieć plik JSON z danymi logowania konta usługi.

3. Pobierz bibliotekę Java po stronie serwera dla usług gier Play

Pobierz bibliotekę google-api-services-games i prześlij ją na serwer.

4. Przygotuj dane logowania do wywoływania interfejsu Recall API

Więcej informacji znajdziesz w artykule Przygotowywanie się do autoryzowanego wywołania interfejsu API.

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

Konfiguracja klienta gry

Skonfiguruj klienta gry, aby pobierać identyfikatory sesji wycofywania używane przez nasz serwer do komunikacji z serwerami Google.

Pakiet Java SDK

Skonfiguruj pakiet Java SDK w kliencie i upewnij się, że w pliku Gradle masz com.google.android.gms:play-services-games-v2:19.0.0 i com.google.android.gms:play-services-tasks:18.0.2 lub nowsze.

Aby komunikować się z serwerami Google za pomocą prawidłowych informacji, musisz poprosić o identyfikator sesji wycofywania z pakietu SDK klienta, który wysyłasz na serwer gry.

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

Pakiet Unity SDK

Jeśli jeszcze tego nie zrobisz, skonfiguruj pakiet Unity SDK w kliencie.

Aby komunikować się z serwerami Google za pomocą prawidłowych informacji, musisz poprosić o identyfikator sesji wycofywania z pakietu SDK klienta i wysłać go na serwer gry.

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

Pakiet v2 Native SDK (beta)

Jeśli jeszcze tego nie zrobisz, zacznij korzystać z usług gier Play w językach C i C++.

// Include the following headers

#include "play_games.h"
#include "recall_client.h"
#include "pgs_status_code.h"
// Request Recall Access
// Initializes the Play Games Services v2 Native SDK (beta).
Pgs_initialize(javaVM, activity);

//Creating Recall Client
PgsRecallClient* pgs_recall_client =
      PgsRecallClient_create(activity);

// RequestRecallAccess Function
PgsRecallClient_requestRecallAccess(
    pgs_recall_client,

    // This is your callback function defined as an inline lambda
    [](PgsStatusCode status_code, char* session_id, user_data) {

        if (status_code == PGS_STATUS_SUCCESS) {
            // Recall Session Id Fetched Successfully
        } else {
            // Fetching Recall Session Id Failed
            // Handle error based on status_code.
            // Examples:
            // PGS_STATUS_NETWORK_ERROR: Check internet connection.
            // PGS_STATUS_INTERNAL_ERROR: An unexpected error occurred.
        }

        // Clean up the client instance passed as user_data
        PgsRecallClient* client = static_cast<PgsRecallClient*>(user_data);
        if (client != nullptr) {
            PgsRecallClient_destroy(client);
        }
    },

    user_data // Data to pass to the callback
);

// Shuts down the Play Games Services v2 Native SDK (beta).
Pgs_destroy()

Używanie interfejsu Recall API na serwerze gry

Po skonfigurowaniu serwera i klienta możesz wysłać recallSessionID z klienta gry na serwer gry i postępować zgodnie z tymi wskazówkami, aby zacząć używać interfejsu Java API do przechowywania, pobierania lub usuwania tokenów wycofywania po stronie serwera.

Przechowywanie tokenów

Konto gracza w interfejsie Google Play Games Recall API składa się z 2 elementów:

  • Persony , która służy jako stały identyfikator konta w grze.
  • Tokena , który służy jako klucz do bezpiecznego logowania gracza na konto.

Aby zapisać personę i token użytkownika, użyj obiektu LinkPersonaRequest. Do wywoływania interfejsów API Google użyj GoogleCredential (więcej informacji znajdziesz w artykule Calling Google APIs). Persona ma ograniczenie kardynalności 1:1: profil usług gier Play może zawierać tylko 1 personę, a persona może należeć tylko do 1 profilu usług gier Play. Ustaw zasadę rozwiązywania konfliktów, aby określić jak należy rozwiązywać naruszenia ograniczenia kardynalności 1:1.

Opcjonalnie ustaw czas wygaśnięcia tokena. Użyj SetTtl() z obiektem Durations, aby ustawić czas życia danych (TTL), lub podaj dokładny czas wygaśnięcia za pomocą setExpireTime().

Musisz zaszyfrować personę i token gry. Nie mogą one zawierać informacji umożliwiających identyfikację osoby. Ciągi znaków persony i tokena mogą mieć maksymalnie 256 znaków.

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
}

Pobieranie tokenów

Istnieją 3 sposoby pobierania tokena, w zależności od potrzeb Twoich gier. Możesz poprosić o:

  • Tokeny powiązane z bieżącą grą, w tym tokeny wycofywania w zakresie gry.
  • Ostatni token zapisany we wszystkich grach należących do konta dewelopera.
  • Biorąc pod uwagę listę gier należących do konta dewelopera, wszystkie tokeny wycofywania powiązane z każdą grą.

Tokeny wycofywania w zakresie gry

Aby pobrać tokeny wycofywania z bieżącej gry, pobierz recallSessionId z klienta i przekaż go do interfejsu 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
}

Najnowszy token do pobrania danych we wszystkich grach należących do konta dewelopera

Aby pobrać najnowszy token zapisany we wszystkich grach należących do konta dewelopera w Konsoli Google Play, musisz pobrać recallSessionId z klienta i przekazać go do interfejsu lastTokenFromAllDeveloperGames API, jak pokazano w tym fragmencie kodu. W ramach odpowiedzi możesz sprawdzić identyfikator aplikacji powiązany z tym tokenem.

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

Wszystkie tokeny wycofywania na danej liście gier należących do konta dewelopera

Aby pobrać wszystkie tokeny powiązane z listą gier należących do Twojego konta dewelopera w Konsoli Google Play, pobierz recallSessionId z klienta i przekaż go do interfejsu gamesPlayerTokens API. Podaj listę identyfikatorów aplikacji.

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

Usuwanie tokena do pobrania danych

W razie potrzeby możesz też usunąć token do pobrania danych za pomocą tego wywołania:

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

Włączanie trybu bez profilu

Możesz włączyć ograniczoną funkcjonalność interfejsu Recall API dla użytkowników, którzy nie mają profili usług gier Play, wykonując te czynności:

  1. Włącz wycofywanie bez profilu w projekcie gry usług gier Play w Konsoli Play. Wybierz opcję „Włącz
pamięć”.
  2. Zapoznaj się z dodatkowymi warunkami opisanymi w dalszej części tej sekcji.
  3. Dodaj ten tag metadanych do pliku manifestu aplikacji:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Dodatkowe warunki

Musisz też przestrzegać Warunków korzystania z usług gier Play. Jeśli używasz interfejsu Recall API w przypadku użytkowników bez profilu usług gier Play, co wiąże się z udostępnianiem Google danych użytkowników, przed udostępnieniem tych danych Google musisz poinformować użytkowników o tym, że:

  • udostępniasz dane Google, aby włączyć funkcję łączenia kont w usługach gier Play;
  • dostępne są ustawienia umożliwiające zarządzanie tym udostępnianiem, np. w ustawieniach usług gier Play;
  • dane te są przetwarzane zgodnie z Polityką prywatności Google, a Ty musisz uzyskać odpowiednią zgodę użytkownika na to udostępnianie, która spełnia wszystkie obowiązujące wymagania prawne.