Integra l'API PGS Recall nel tuo gioco

In questa pagina viene spiegato come implementare l'API Recall nel tuo gioco. In primo luogo descrive la configurazione del server e del client di gioco per il supporto dell'API, poi descrive 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 di Google.

Configura il progetto dei servizi per i giochi di Play

(Se non l'hai già fatto) Segui le istruzioni nell'articolo Configurare i servizi per i giochi di Google Play.

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.

Scarica la libreria Java lato server per i servizi per i giochi di Play

Scarica l'ultima libreria di google-api-services-games e caricala sul tuo server.

Preparare le credenziali per le chiamate API Recall

Per saperne di più, consulta Preparazione per effettuare una chiamata API delegata.

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 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, richiedi un ID sessione di richiamo all'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
  });

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

Dopo aver configurato il server e il client, puoi inviare recallSessionID dal client del 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 Recall lato server.

Archivia token

Archivia l'utente tipo e il token del gioco utilizzando l'oggetto LinkPersonaRequest. Usa GoogleCredential per chiamare le API di Google. Per seguire il 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. Imposta i criteri di risoluzione nel caso in cui questo profilo dei servizi per i giochi di Play sia già stato collegato a un altro utente.

Facoltativamente, puoi scegliere di impostare un TTL sul token, che dichiara il periodo di validità del token utilizzando un oggetto Durations. Puoi scegliere di impostarlo utilizzando SetTtl() (come mostrato di seguito), che imposta la data di scadenza sulla quantità di tempo specificata nel metodo, oppure setExpireTime(), che ti consente di impostare un'ora esatta di scadenza dei token.

Devi criptare l'utente tipo e il token del gioco, che non possono 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 per giocatore per partita.

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

import com.google.api.services.games.Games.Recall.LinkPersona;
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

Per recuperare il token Recall, ottieni il valore recallSessionId dal client e trasmettilo all'API retrieveTokens:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

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
}

Elimina token richiamo

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

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

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

// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();