Questa pagina è stata tradotta dall'API Cloud Translation.

Integra l'API PGS Recall nel tuo gioco

In questa pagina viene spiegato come implementare l'API Recall nel tuo gioco. Innanzitutto, illustra come configurare il server e il client di gioco per supportare l'API, quindi spiega come memorizzare e recuperare i token.

Configurazione del server di gioco

Configura il server di gioco in modo che effettui chiamate all'API Recall ai server di Google.

1. Configurare il progetto Servizi per i giochi di Google Play

(Se non l'hai già fatto) segui le istruzioni riportate in Configurare i servizi di Google Play Giochi.

2. Configura un account di servizio per il gioco

Segui le istruzioni per la creazione di un account di servizio. Al termine 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 più recente e caricala sul tuo server.

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

Per maggiori informazioni, 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 in modo da recuperare gli ID sessione di recall utilizzati dal tuo server per comunicare con i server 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 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 l'hai già fatto, configura l'SDK Unity nel tuo 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 il 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

La persona e il token di gioco degli utenti possono essere archiviati utilizzando l'oggetto LinkPersonaRequest. Devi utilizzare GoogleCredential per chiamare le API di Google (consulta la sezione Chiamata delle API di Google per maggiori informazioni). Tieni presente che, in base al vincolo di cardinalità 1:1, puoi collegare una sola persona a un solo profilo PGS alla volta (e viceversa).Devi impostare il criterio di risoluzione nel caso in cui questo profilo PGS sia già stato collegato a un'altra persona.

Facoltativamente, puoi scegliere di impostare un TTL sul token, che dichiara la durata di validità del token utilizzando un oggetto Durations. Puoi scegliere di impostarlo utilizzando SetTtl() (come mostrato di seguito), che imposta la data di scadenza in base al periodo di tempo specificato nel metodo, oppure setExpireTime(), che consente di impostare un'ora esatta per la scadenza dei token.

Devi criptare la persona e il token di gioco, che non possono contenere informazioni che consentono l'identificazione personale. Le stringhe di persona e token possono avere una lunghezza massima di 256 caratteri e possono essere memorizzati al massimo 20 token o persone per giocatore per partita.

È possibile memorizzare un solo token per persona e giocatore alla volta. Il tentativo di memorizzare un altro token con la stessa persona sovrascrive il token originale.

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 al gioco corrente, inclusi i token di richiamo a livello 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 ciascun gioco.

Token di richiamo basati sul gioco

Per recuperare i token di richiamo dalla partita in corso, 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
}

Token di richiamo più recente 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 recuperare 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 dispongono di profili PGS seguendo questi passaggi:

Attiva il richiamo senza profilo per il tuo progetto di giochi PGS in Play Console.
Esamina i termini aggiuntivi descritti più avanti in questa sezione.
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

Oltre a essere soggetto ai Termini di servizio di Play Games Services, accetti che se utilizzi l'API Recall per gli utenti senza un profilo PGS, che consente di condividere i dati dell'utente finale con Google senza che questi abbia un profilo Play Games Services, prima di condividere questi dati con Google devi fornire all'utente finale un'informativa appropriata che descriva quanto segue:

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