Integra l'API PGS Recall nel tuo gioco

In questa pagina viene spiegato come implementare l'API Recall nel tuo gioco. Spiega prima come configurare il server di gioco e il client per il supporto dell'API, quindi spiega come archiviare e recuperare i token.

Configurazione del server di gioco

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

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

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

Nota: i token di richiamo e gli utenti tipo sono disponibili in base ai singoli progetti PGS. Ciò significa che i token e gli utenti tipo vengono archiviati per ogni progetto PGS e, per i progetti PGS distinti, esistono raccolte separate di link tra i profili e gli 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 protocollo OAuth a tre vie standard utilizzato da altre API Games 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 saperne di più, 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 client di gioco in modo che recuperi gli ID sessione di richiamo utilizzati dal 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 le informazioni corrette, devi richiedere un ID sessione di richiamo all'SDK del 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à completata, configura l'SDK Unity all'interno del client.

Per comunicare con i server di Google le informazioni corrette, devi richiedere un ID sessione di richiamo all'SDK del 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 Recall lato server.

Archivia token

L'utente tipo e il token del gioco possono essere archiviati utilizzando l'oggetto LinkPersonaRequest. Devi utilizzare GoogleCredential per chiamare le API di Google (per saperne di più, consulta la sezione Chiamata alle API di Google). Tieni presente che, in base al vincolo per la cardinalità 1:1, puoi collegare un solo utente tipo a un profilo dei servizi per i giochi di Play alla volta (e viceversa).Ti consigliamo di impostare 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 tipo.

Facoltativamente, puoi scegliere di impostare un TTL sul token per dichiarare il tempo di validità del token utilizzando un oggetto Durations. Puoi scegliere di impostarlo utilizzando SetTtl() (come mostrato di seguito), che consente di impostare la data di scadenza in base al periodo di tempo specificato nel metodo, oppure setExpireTime(), che consente di impostare il momento esatto 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 tipo Persona e token possono contenere al massimo 256 caratteri e possono essere archiviati al massimo 20 token o utenti tipo per giocatore e per partita.

È possibile archiviare un solo token alla volta per utente tipo e giocatore. Se tenti di archiviare un altro token con lo stesso utente tipo, il token originale viene sovrascritto.

Nota: la chiave di crittografia utilizzata per la crittografia dei token deve essere univoca per ogni applicazione. Se il gioco viene trasferito a un altro sviluppatore, la chiave di crittografia deve essere trasmessa al nuovo proprietario. I token di richiamo non possono essere decriptati senza la chiave di crittografia 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 token

Per recuperare il token di richiamo, devi ottenere il 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
}

Nota: le stringhe che rappresentano l'utente tipo non vengono restituite tramite l'API quando si richiedono token di richiamo.

Elimina token richiamo

Se necessario, puoi anche eliminare il token di richiamo 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();

boolean unlinked = unlinkPersonaResponse.isUnlinked();