Integra l'API PGS Recall nel tuo gioco

Questa pagina spiega come implementare l'API Recall nel tuo gioco. Innanzitutto, spiega come configurare il server di gioco e il client per supportare l'API, quindi illustra 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. Configurare il progetto Servizi per i giochi di Play

Se non l'hai ancora fatto, segui le istruzioni riportate in Configurare Google Play Games Services.

Nota:i token di richiamo e le buyer persona sono disponibili per ogni progetto PGS. Ciò significa che i token e le persona vengono archiviati per progetto PGS e che per progetti PGS separati esistono raccolte separate di collegamenti tra i profili PGS e le persona. Ti consigliamo di consultare questa documentazione per determinare come configurare i tuoi progetti PGS.

2. Configurare un service account per il gioco

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

Nota :l'API Recall è un'API server-to-server. Per questo motivo, l'API Recall utilizza i service account per autenticare il server di gioco, non OAuth a tre passaggi regolare, che viene utilizzato da altre API Games per autenticare sia i server di gioco sia gli utenti finali.

3. Scarica la libreria Java lato server per PlayGamesServices

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

4. Prepara le credenziali per le chiamate API Recall

Per maggiori dettagli, consulta la sezione 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 Google.

SDK Java

Configura l'SDK Java all'interno del 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 file gradle.

Per comunicare con i server di Google con le informazioni corrette, devi richiedere un ID sessione di richiamo 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
    });

Unity SDK

Se non è già stato fatto, configura l'SDK Unity all'interno del client.

Per comunicare con i server di Google con le informazioni corrette, devi richiedere un ID sessione di richiamo 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
    });

Utilizzare l'API Recall all'interno del server di gioco

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

Memorizzare i token

Un account giocatore nell'API Google Play Games Recall è 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 modo sicuro all'account

Puoi memorizzare la persona e il token di un utente utilizzando l'oggetto LinkPersonaRequest. Usa GoogleCredential per chiamare le API di Google (vedi Chiamare le API di Google per il contesto). Una persona ha un vincolo di cardinalità 1:1: un singolo profilo PGS può contenere una sola persona e una persona può esistere solo in un singolo profilo PGS. Imposta le norme di risoluzione dei link in conflitto per definire come devono essere risolte le violazioni del vincolo di cardinalità 1:1.

(Facoltativo) Imposta la scadenza del token. Utilizza SetTtl() con un oggetto Durations per impostare una durata o fornire un'ora di scadenza esatta con setExpireTime().

Devi criptare il token del personaggio e del gioco, che non possono contenere informazioni che consentono l'identificazione personale. Le stringhe di persona e token possono contenere al massimo 256 caratteri.

Nota :la chiave di crittografia utilizzata per criptare i token deve essere univoca per ogni applicazione. Se il gioco viene trasferito a un altro sviluppatore, la chiave di crittografia deve essere trasferita al nuovo proprietario. I token Recall non possono essere decriptati senza la chiave di crittografia originale.

Nota: i token creati per gli utenti senza profilo hanno un TTL predefinito di 30 giorni. In caso contrario, per gli utenti con profili dei servizi per i giochi di Play, i token non hanno un TTL predefinito.

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
}

Recuperare i token

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

• I token associati alla partita corrente, inclusi i token di richiamo specifici per la partita.
• L'ultimo token memorizzato in tutti i giochi di proprietà dell'account sviluppatore.
• Dato un elenco di giochi di proprietà dell'account sviluppatore, tutti i token di revoca associati a ciascun gioco.

Nota: quando richiedi token di richiamo, l'API non restituisce stringhe che rappresentano la persona.

Token di richiamo con ambito di gioco

Per recuperare i token di richiamo dal gioco corrente, ottieni 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 ritiro per tutti i giochi di proprietà dell'account sviluppatore

Per recuperare il token più recente memorizzato in tutti i giochi di proprietà dell'account sviluppatore in Google Play Console, devi ottenere recallSessionId dal client e passarlo all'API lastTokenFromAllDeveloperGames, come mostrato nel seguente snippet di codice. Nell'ambito 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 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 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();

Attivare la modalità senza profilo

Puoi attivare la funzionalità limitata dell'API Recall per gli utenti che non hanno profili PGS seguendo questi passaggi:

1. Attiva il richiamo senza profilo per il tuo progetto di gioco PGS in Play Developer Console.
2. Esamina i termini aggiuntivi descritti più avanti in questa sezione.
3. Aggiungi il seguente tag di metadati al manifest dell'app:

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

Termini aggiuntivi

Oltre a essere soggetto ai Termini di servizio di Play Giochi, accetti che, se utilizzi l'API Recall per gli utenti senza un profilo Play Giochi, che consente la condivisione dei dati dell'utente finale con Google senza che questi disponga di un profilo Play Giochi, prima di condividere questi dati con Google, devi fornire all'utente finale un avviso appropriato che descriva quanto segue:

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