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. Elle présente d'abord comment configurer votre serveur et votre client de jeu pour qu'ils prennent en charge 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.

1. Configurer votre projet lié aux services de jeux Play

Si vous ne l'avez pas encore fait, suivez les instructions de la section Configurer les services de jeux Google Play.

2. 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.

3. Télécharger la bibliothèque Java côté serveur pour PlayGamesServices

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

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

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

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 notre 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, vous devez demander 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
    });

SDK Unity

Si ce n'est pas déjà fait, configurez le SDK Unity dans votre client.

Pour communiquer avec les serveurs de Google avec les informations correctes, vous devez demander un ID de session de rappel au SDK client, puis l'envoyer au serveur de votre jeu.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // 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

Un compte de joueur dans l'API Google Play Jeux Recall se compose de deux informations :

  • un persona servant d'identifiant stable pour un compte de jeu.
  • Un jeton servant de clé pour connecter un joueur de manière sécurisée au compte

Vous pouvez stocker le persona et le jeton d'un utilisateur à l'aide de l'objet LinkPersonaRequest. Utilisez GoogleCredential pour appeler les API Google (consultez Appeler des API Google pour plus de contexte). Un persona est soumis à une contrainte de cardinalité individuelle : un profil PGS ne peut contenir qu'un seul persona, et un persona ne peut exister que dans un seul profil PGS. Définissez la stratégie de résolution des liens conflictuels pour définir comment résoudre les cas de non-respect de la contrainte de cardinalité 1:1.

Vous pouvez également définir le délai d'expiration du jeton. Utilisez SetTtl() avec un objet Durations pour définir un délai avant expiration ou fournir une heure d'expiration exacte avec setExpireTime().

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.

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
}

Récupérer des jetons

Trois options s'offrent à vous pour récupérer un jeton, en fonction des besoins de vos jeux. Vous pouvez demander les éléments suivants :

  • Jetons associés au jeu actuel, y compris les jetons de rappel à portée du jeu.
  • Dernier jeton stocké dans tous les jeux appartenant au compte de développeur.
  • Étant donné une liste de jeux appartenant au compte de développeur, tous les jetons de rappel associés à chaque jeu.

Jetons de rappel limités au jeu

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

Dernier jeton de rappel pour tous les jeux appartenant au compte de développeur

Pour récupérer le jeton le plus récent stocké dans tous les jeux appartenant au compte de développeur dans la Google Play Console, vous devez obtenir le recallSessionId du client et le transmettre à l'API lastTokenFromAllDeveloperGames, comme indiqué dans l'extrait de code suivant. Dans la réponse, vous pouvez inspecter l'ID d'application associé à ce jeton.

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.
}

Tous les jetons de rappel pour une liste donnée de jeux appartenant au compte de développeur

Pour récupérer tous les jetons associés à une liste de jeux appartenant à votre compte de développeur dans la Play Console, récupérez le recallSessionId auprès du client et transmettez-le à l'API gamesPlayerTokens. Fournissez une liste d'ID d'application.

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.
}

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

Activer le mode sans profil

Vous pouvez activer la fonctionnalité limitée de l'API Recall pour les utilisateurs qui n'ont pas de profil PGS en procédant comme suit :

  1. Activez le rappel sans profil pour votre projet de jeu PGS dans la Play Console. Sélectionnez l&#39;option &quot;Activer le stockage&quot;.
  2. Consultez les conditions supplémentaires décrites plus loin dans cette section.
  3. Ajoutez le tag de métadonnées suivant dans le fichier manifeste de votre application :
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Conditions supplémentaires

En plus d'être soumis aux Conditions d'utilisation des services de jeux Play, vous acceptez que si vous utilisez l'API Recall pour les utilisateurs sans profil PGS, qui permet de partager les données des utilisateurs finaux avec Google sans qu'ils aient de profil Services de jeux Play, vous devez, avant de partager ces données avec Google, fournir à l'utilisateur final un avis approprié décrivant les éléments suivants :

  1. Le partage de vos données avec Google pour activer la fonctionnalité d'association de compte Play Jeux.
  2. La disponibilité des paramètres permettant de gérer ce partage, comme ceux des paramètres Play Jeux.
  3. Le traitement de ces données est soumis aux Règles de confidentialité de Google. Vous devez obtenir le consentement approprié des utilisateurs finaux pour ce partage, conformément à toutes les exigences légales applicables.