Integra l'API PGS Recall nel tuo gioco

In questa pagina viene spiegato come implementare l'API Recall nel tuo gioco. Viene prima illustrata la configurazione del server e del client di gioco per supportare l'API, quindi viene spiegato come archiviare e recuperare i token.

Configurazione del server di gioco

Configura il server di gioco per effettuare chiamate all'API Recall ai server di Google.

1. Configura il progetto Play Games Services

Se non l'hai ancora fatto, segui le istruzioni riportate in Configurare i servizi per i giochi di Google Play.

2. Configura un account di servizio per il gioco

Segui le istruzioni per creare un account di servizio. Alla fine dovresti avere un file JSON con le credenziali dell'account di servizio.

3. Scarica la libreria Java lato server per PlayGamesServices

Scarica la libreria google-api-services-games e caricala sul tuo server.

4. Prepara le credenziali per le chiamate all'API Recall

Per maggiori dettagli, consulta Prepararsi a effettuare una chiamata API autorizzata.

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

Configurazione del client di gioco

Configura il client di gioco per recuperare gli ID sessione di Recall utilizzati dal nostro server per comunicare con i server di Google.

SDK Java

Configura l'SDK Java nel client e assicurati di includere com.google.android.gms:play-services-games-v2:19.0.0 e com.google.android.gms:play-services-tasks:18.0.2 o versioni successive nel tuo file Gradle.

Per comunicare con i server di Google con le informazioni corrette, devi richiedere un ID sessione di Recall dall'SDK client, che invii al server del tuo gioco.

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

SDK Unity

Se non l'hai ancora fatto, configura l'SDK Unity nel client.

Per comunicare con i server di Google con le informazioni corrette, devi richiedere un ID sessione di Recall dall'SDK client e inviarlo al server del tuo gioco.

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

SDK nativo v2 (beta)

Se non l'hai ancora fatto, inizia a utilizzare Play Games Services per C e 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()

Utilizza l'API Recall nel server di gioco

Dopo aver configurato il server e il client, puoi inviare il recallSessionID dal client di gioco al server di gioco e seguire le seguenti indicazioni per iniziare a utilizzare l'API Java per archiviare, recuperare o eliminare i token di richiamo lato server.

Archivia i token

Un account giocatore nell'API Recall dei servizi per i giochi di Google Play è composto da due informazioni:

  • Una persona che funge da identificatore stabile per un account in-game
  • Un token che funge da chiave per consentire a un giocatore di accedere in sicurezza all'account

Puoi archiviare la persona e il token di un utente utilizzando l'oggetto LinkPersonaRequest. Utilizza il GoogleCredential per chiamare le API di Google (per maggiori dettagli, consulta Chiamare le API di Google). Una persona ha un vincolo di cardinalità 1:1: un profilo dei servizi per i giochi di Play può contenere una sola persona e una persona può appartenere a un solo profilo dei servizi per i giochi di Play. Imposta le norme di risoluzione dei link in conflitto per definire come risolvere le violazioni del vincolo di cardinalità 1:1.

(Facoltativo) Imposta il tempo di scadenza del token. Utilizza SetTtl() con un Durations oggetto per impostare un TTL (Time to Live) o fornisci un'ora di scadenza esatta con setExpireTime().

Devi criptare la persona e il token di gioco e non possono contenere informazioni che consentono l'identificazione personale. Le stringhe di persona e token possono avere una lunghezza massima di 256 caratteri.

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
}

Recupera i token

Esistono tre opzioni per recuperare un token, in base alle esigenze dei tuoi giochi. Puoi richiedere quanto segue:

  • I token associati al gioco attuale, inclusi i token di richiamo con ambito di gioco.
  • L'ultimo token archiviato in tutti i giochi di proprietà dell'account sviluppatore.
  • Dato un elenco di giochi di proprietà dell'account sviluppatore, tutti i token di richiamo associati a ogni gioco.

Token di richiamo con ambito di gioco

Per recuperare i token di richiamo dal gioco attuale, recupera il recallSessionId dal client e passalo all'API retrieveTokens:

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
}

Ultimo token di richiamo in tutti i giochi di proprietà dell'account sviluppatore

Per recuperare il token più recente archiviato in tutti i giochi di proprietà dell'account sviluppatore in Google Play Console, devi recuperare il recallSessionId dal client e passarlo all'API lastTokenFromAllDeveloperGames, come mostrato nel seguente snippet di codice. Come parte della risposta, puoi esaminare l' ID applicazione associato a questo token.

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

Tutti i token di richiamo in un determinato elenco di giochi di proprietà dell'account sviluppatore

Per recuperare tutti i token associati a un elenco di giochi di proprietà del tuo account sviluppatore in Google Play Console, recupera il recallSessionId dal client e passalo all'API gamesPlayerTokens. Fornisci un elenco di ID applicazione.

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

Elimina il token di richiamo

Se necessario, puoi anche eliminare il token di richiamo con la seguente chiamata:

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

Attiva la modalità senza profilo

Puoi attivare la funzionalità limitata dell'API Recall per gli utenti che non hanno profili dei servizi per i giochi di Play seguendo questi passaggi:

  1. Attiva il richiamo senza profilo per il tuo progetto di gioco dei servizi per i giochi di Play in Play Developer Console. Seleziona l&#39;opzione &quot;Attiva
l&#39;archiviazione&quot;.
  2. Esamina i termini aggiuntivi descritti più avanti in questa sezione.
  3. Aggiungi il seguente tag di metadati al file manifest dell'app:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Termini aggiuntivi

Devi inoltre rispettare i Termini di servizio di Play Games Services. Se utilizzi l'API Recall per gli utenti senza un profilo dei servizi per i giochi di Play, che prevede la condivisione dei dati degli utenti finali con Google, prima di condividere questi dati con Google devi fornire agli utenti finali un avviso appropriato che descriva quanto segue:

  • Come condividi i dati con Google per attivare la funzionalità di collegamento dell'account Play Giochi.
  • La disponibilità di impostazioni per gestire questa condivisione, ad esempio tramite le impostazioni di Play Giochi.
  • Il trattamento di questi dati ai sensi delle Norme sulla privacy di Google e l' obbligo di ottenere il consenso appropriato dell'utente finale per questa condivisione che soddisfi tutti i requisiti legali applicabili.