Integra l'API PGS Recall nel tuo gioco

In questa pagina viene spiegato come implementare l'API Recall all'interno del tuo gioco. Innanzitutto, descrive la configurazione del server di gioco e del client per il supporto dell'API, quindi illustra le modalità di archiviazione e recupero dei token.

Configurazione del server di gioco

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

1. Configurare il progetto dei servizi per i giochi di Play

Segui le istruzioni nella sezione Configurare i servizi per i giochi di Google Play (se non l'hai già fatto).

Nota: i token di richiamo e gli utenti tipo sono disponibili in base ai singoli progetti dei servizi per i giochi di Play. Ciò significa che i token e gli utenti tipo vengono archiviati per progetto dei servizi per i giochi di Play e, per i progetti dei servizi per i giochi di Play separati, esistono raccolte separate di collegamenti tra profili e utenti dei servizi per i giochi di Play. Ti consigliamo di consultare questa documentazione per determinare come configurare i progetti dei servizi per i giochi di Play.

2. Configura un account di servizio per il gioco

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

Nota: l'API Recall è un'API server-server pura. Per questo motivo, l'API Recall utilizza gli account di servizio per autenticare il server di gioco e non il normale OAuth a tre vie usato da altre API di gioco per autenticare i server di gioco e 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 ulteriori informazioni, consulta Preparazione per 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 tuo client di gioco per recuperare gli ID sessione di richiamo utilizzati dal tuo server per comunicare con i server di Google.

SDK Java

Configura l'SDK Java all'interno del tuo 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 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
    });

Unity SDK

Se non l'hai ancora fatto, configura l'SDK Unity all'interno del tuo client.

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

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

Usa l'API Recall nel tuo server di gioco

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

Archivia token

Il token di gioco e l'utente tipo degli utenti possono essere archiviati utilizzando l'oggetto LinkPersonaRequest. Devi utilizzare GoogleCredential per chiamare le API di Google (vedi Chiamata alle API di Google per il contesto). Tieni presente che, in base al vincolo di cardinalità 1:1, puoi collegare un solo utente tipo a un profilo dei servizi per i giochi di Play alla volta (e viceversa).Devi impostare il criterio di risoluzione nel caso in cui questo profilo dei servizi per i giochi di Play sia già stato collegato a un altro utente tipo.

Facoltativamente, puoi scegliere di impostare un TTL sul token, che dichiara per quanto tempo il token è valido utilizzando un oggetto Durations. Puoi scegliere di farlo utilizzando SetTtl() (come mostrato di seguito), che consente di impostare la data di scadenza a partire dalla quantità di tempo specificata nel metodo, oppure setExpireTime(), che ti consente di impostare un orario esatto di scadenza dei token.

Devi criptare l'utente tipo e il token di gioco, in modo che questi non possano contenere informazioni che consentono l'identificazione personale. Le stringhe di utenti tipo e token possono contenere al massimo 256 caratteri e possono essere archiviati al massimo 20 token o utenti tipo archiviati per giocatore per partita.

È possibile memorizzare un solo token alla volta per utente tipo per giocatore. Se provi ad archiviare un altro token con lo stesso utente tipo, il token originale viene sovrascritto.

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 passata al nuovo proprietario. I token Recall non possono essere decriptati senza la chiave di crittografia 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
}

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 corrente, inclusi i token Recall con ambito a livello di gioco.
• L'ultimo token memorizzato in tutti i giochi di proprietà dell'account sviluppatore.
• In base a un elenco di giochi di proprietà dell'account sviluppatore, tutti i token Recall associati a ogni gioco.

Nota: quando richiedi i token Recall, l'API non restituisce stringhe che rappresentano l'utente tipo.

Token di richiamo basati sui giochi

Per recuperare i token Recall dal gioco corrente, 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 in 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 il token recallSessionId dal client e passarlo all'API lastTokenFromAllDeveloperGames, come mostrato nel seguente snippet di codice. Come parte della risposta, puoi ispezionare 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 Recall 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 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 modalità senza profilo

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

1. Attiva il richiamo senza profilo per il tuo progetto di gioco dei servizi per i giochi di Play in Play Console.
2. Consulta i termini aggiuntivi descritti più avanti in questa sezione.
3. Aggiungi il seguente tag di metadati nel file manifest dell'app:

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

Termini aggiuntivi

Oltre ad essere soggetto ai Termini di servizio dei servizi per i giochi di Play, accetti che se utilizzi l'API Recall per utenti senza un profilo dei servizi per i giochi di Play, che consente la condivisione dei dati dell'utente finale con Google senza che questi abbia un profilo dei servizi per i giochi di Play, devi, prima di condividere tali dati con Google, fornire all'utente finale un'informativa appropriata che descriva 1) la condivisione di tali dati con Google Play Giochi e la condivisione dei dati relativi a tali dati, nonché la gestione della funzionalità di collegamento dell'account di Play Giochi da parte tua.