Intégrer l'API Recall des services de jeux Play (Play Games Services ou PGS) à votre jeu

Cette page explique comment implémenter l'API Recall dans votre jeu. Il explique d'abord comment configurer votre serveur et votre client de jeu pour qu'ils soient compatibles avec l'API, puis comment stocker et récupérer des jetons.

Configuration du serveur de jeu

Configurez votre serveur de jeu pour effectuer des appels de l'API Recall auprès des serveurs Google.

Configurer votre projet lié aux services de jeux Play

(Si ce n'est pas déjà fait) Suivez les instructions de la section Configurer les services de jeux Google Play.

Remarque : Les jetons de rappel et les personas sont disponibles par projet PGS. Cela signifie que les jetons et les personas sont stockés par projet PGS et que pour des projets PGS distincts, il existe des collections distinctes de liens entre les profils et les personas PGS. Nous vous recommandons de consulter cette documentation pour déterminer comment configurer vos projets PGS.

Configurer un compte de service pour le jeu

Suivez les instructions pour créer un compte de service. À la fin, vous devriez obtenir un fichier JSON contenant les identifiants du compte de service.

Remarque : L'API Recall est une API de serveur à serveur pure. De ce fait, l'API Recall utilise des comptes de service pour authentifier le serveur de jeu, et non le protocole OAuth en trois étapes standard qui est utilisé par d'autres API Jeux pour authentifier à la fois les serveurs de jeu et les utilisateurs finaux.

Télécharger la bibliothèque Java côté serveur pour les services de jeux Play

Téléchargez la dernière bibliothèque google-api-services-games et importez-la sur votre serveur.

Préparer les identifiants pour les appels de l'API Recall

Pour en savoir plus, consultez la section Préparer un appel d'API délégué.

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

Configuration du client de jeu

Configurez votre client de jeu de sorte qu'il récupère les ID de session de rappel utilisés par votre serveur pour communiquer avec les serveurs Google.

SDK Java

Configurez le SDK Java dans votre client et veillez à inclure com.google.android.gms:play-services-games-v2:19.0.0 et com.google.android.gms:play-services-tasks:18.0.2 ou une version ultérieure dans votre fichier Gradle.

Pour communiquer avec les serveurs de Google avec les informations correctes, demandez un ID de session de rappel au SDK client, que vous envoyez au serveur de votre jeu:

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

Utiliser l'API Recall dans votre serveur de jeu

Après avoir configuré votre serveur et votre client, vous pouvez envoyer le recallSessionID de votre client de jeu à votre serveur de jeu, puis suivre les instructions ci-dessous pour commencer à utiliser l'API Java pour stocker, récupérer ou supprimer les jetons de rappel côté serveur.

Stocker des jetons

Stockez le persona et le jeton de jeu de l'utilisateur à l'aide de l'objet LinkPersonaRequest. Utilisez le GoogleCredential pour appeler les API Google. Pour suivre la contrainte de cardinalité individuelle, vous ne pouvez associer qu'un persona à un profil PGS à la fois, et inversement. Définissez la règle de résolution au cas où ce profil PGS a déjà été associé à un autre persona.

Vous pouvez éventuellement choisir de définir une valeur TTL sur le jeton, qui déclare sa durée de validité à l'aide d'un objet Durations. Vous pouvez choisir de définir cela à l'aide de SetTtl() (comme indiqué ci-dessous), qui définit la date d'expiration à partir de la durée spécifiée dans la méthode, ou de setExpireTime(), qui vous permet de définir un délai d'expiration exact des jetons.

Vous devez chiffrer le persona et le jeton de jeu, et ils ne peuvent pas contenir d'informations permettant d'identifier personnellement l'utilisateur. Les chaînes de personas et de jetons peuvent comporter jusqu'à 256 caractères, et 20 jetons ou personas au maximum peuvent être stockés par joueur et par jeu.

Un seul jeton par persona et par joueur peut être stocké à la fois. Si vous essayez de stocker un autre jeton avec le même persona, le système écrase le jeton d'origine.

Remarque : La clé de chiffrement utilisée pour chiffrer les jetons doit être propre à chaque application. Si le jeu est transféré à un autre développeur, la clé de chiffrement doit lui être transmise également. Les jetons de rappel ne peuvent pas être déchiffrés sans la clé de chiffrement d'origine.

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
}

Récupérer des jetons

Pour récupérer le jeton de rappel, récupérez l'recallSessionId auprès du client et transmettez-le à l'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
}

Remarque :Les chaînes représentant le persona ne sont pas renvoyées via l'API lorsque vous demandez des jetons de rappel.

Supprimer le jeton de rappel

Si nécessaire, vous pouvez également supprimer le jeton de rappel à l'aide de l'appel suivant :

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