Ajouter des jeux enregistrés à votre jeu

Suite à l'arrêt de l'API Google Sign-In, nous allons supprimer le SDK v1 pour les jeux en 2026. Après février 2025, vous ne pourrez plus publier de titres qui viennent d'être intégrés au SDK v1 de Jeux sur Google Play. Nous vous recommandons d'utiliser plutôt le SDK v2 de Jeux.
Bien que les titres existants avec les intégrations de jeux v1 précédentes continuent de fonctionner pendant quelques années, nous vous encourageons à migrer vers la v2 à partir de juin 2025.
Ce guide explique comment utiliser la version 1 du SDK des services de jeux Play. Le SDK C++ pour les services de jeux Play v2 n'est pas encore disponible.

Ce guide explique comment enregistrer et charger les données de progression d'un joueur à l'aide du service Jeux enregistrés dans une application C++. Vous pouvez utiliser ce service pour charger et enregistrer automatiquement la progression du joueur à tout moment pendant le jeu. Ce service peut également permettre aux joueurs de déclencher une interface utilisateur pour mettre à jour ou restaurer une partie enregistrée existante, ou en créer une.

Avant de commencer

Si ce n'est pas déjà fait, n'hésitez pas à revoir les concepts de jeux enregistrés.

Avant de commencer à coder à l'aide de l'API Saved Games :

• Installez le SDK Play Jeux pour C++.
• Configurez votre environnement de développement C++.
• Téléchargez et examinez l'exemple de code C++.
• Activez le service Jeux enregistrés dans la Google Play Console.

Formats de données et compatibilité multiplate-forme

Les données de jeux enregistrés que vous enregistrez sur les serveurs de Google doivent être au format std::vector<uint8_t>. Le service Jeux enregistrés se charge d'encoder vos données pour assurer la compatibilité multiplate-forme. Les applications Android peuvent lire ces mêmes données sous forme de tableau d'octets sans aucun problème de compatibilité multiplate-forme.

Évitez d'utiliser des formats spécifiques à une plate-forme lorsque vous choisissez un format de données pour vos données Jeux enregistrés. Nous vous encourageons vivement à utiliser un format de données, comme XML ou JSON, qui est bien pris en charge par les bibliothèques sur plusieurs plates-formes.

Activer le service Jeux enregistrés

Avant de pouvoir utiliser le service Jeux enregistrés, vous devez d'abord activer l'accès à celui-ci. Pour ce faire, appelez EnableSnapshots() lorsque vous créez le service avec gpg::GameServices::Builder. Cela permettra d'activer les autres niveaux d'autorisation requis par les jeux enregistrés lors du prochain événement d'authentification.

Afficher les jeux enregistrés

Dans votre jeu, vous pouvez proposer une option que les joueurs peuvent déclencher pour enregistrer ou restaurer des jeux enregistrés. Lorsque les joueurs sélectionnent cette option, votre jeu doit afficher un écran qui présente les emplacements de sauvegarde existants et leur permettre d'enregistrer ou de charger une partie à partir de l'un de ces emplacements, ou de créer un nouveau jeu enregistré. Pour ce faire, utilisez la méthode suivante :

  SnapshotManager::ShowSelectUIOperation(...)

L'UI de sélection de jeux enregistrés permet aux joueurs de créer un jeu enregistré, de consulter les détails des jeux enregistrés existants et de charger de précédents jeux enregistrés.

  SnapshotManager::SnapshotSelectUIResponse response;
  if (IsSuccess(response.status)) {
  if (response.data.Valid()) {
    LogI("Description: %s", response.data.Description().c_str());
    LogI("FileName %s", response.data.FileName().c_str());
    //Opening the snapshot data
    …
  } else {
    LogI("Creating new snapshot");
    …
  }
} else {
  LogI("ShowSelectUIOperation returns an error %d", response.status);
}

L'exemple suivant montre comment afficher l'UI de jeux enregistrés par défaut et gérer la sélection de l'UI par le joueur :

  service_->Snapshots().ShowSelectUIOperation(
  ALLOW_CREATE_SNAPSHOT,
  ALLOW_DELETE_SNAPSHOT,
  MAX_SNAPSHOTS,
  SNAPSHOT_UI_TITLE,
  [this](gpg::SnapshotManager::SnapshotSelectUIResponse const & response) {
  …
      }

Si, dans l'exemple ci-dessus, ALLOW_CREATE_SNAPSHOT est défini sur true et que MAX_SNAPSHOTS est supérieur au nombre réel d'instantanés que l'utilisateur a créés, l'UI d'instantané par défaut fournit aux joueurs un bouton permettant de créer une sauvegarde plutôt que d'en sélectionner une existante. (Lorsqu'il s'affiche, le bouton se trouve en bas de l'interface utilisateur.) Lorsqu'un joueur clique sur ce bouton, la réponse SnapshotSelectUIResponse est valide, mais ne contient aucune donnée.

Ouvrir et lire des jeux enregistrés

Pour accéder à un jeu enregistré et lire ou modifier son contenu, commencez par ouvrir l'objet SnapshotMetadata représentant ce jeu enregistré. Appelez ensuite la méthode SnapshotManager::Read*().

L'exemple suivant montre comment ouvrir un jeu enregistré :

  LogI("Opening file");
  service_->Snapshots()
  .Open(current_snapshot_.FileName(),
               gpg::SnapshotConflictPolicy::BASE_WINS,
        [this](gpg::SnapshotManager::OpenResponse const & response) {
           LogI("Reading file");
           gpg::SnapshotManager::ReadResponse responseRead =
           service_->Snapshots().ReadBlocking(response.data);
          …
        }

Détecter et résoudre les conflits de données

Lorsque vous ouvrez un objet SnapshotMetadata, le service Jeux enregistrés détecte s'il existe un jeu enregistré en conflit. Des conflits de données peuvent se produire lorsque le jeu enregistré stocké sur l'appareil local d'un joueur n'est plus synchronisé avec la version distante stockée sur les serveurs de Google.

La règle de conflit que vous spécifiez lorsque vous ouvrez un jeu enregistré indique au service Jeux enregistrés comment résoudre automatiquement un conflit de données. La règle peut être l'une des suivantes :

Si vous avez spécifié une stratégie de conflit autre que GPGSnapshotConflictPolicyManual, le service Jeux enregistrés fusionne le jeu enregistré et renvoie la version mise à jour via la valeur SnapshotManager::OpenResponse résultante. Votre jeu peut ouvrir le jeu enregistré, y écrire, puis appeler la méthode SnapshotManager::Commit(...) pour enregistrer le jeu sur les serveurs de Google.

Effectuer une fusion personnalisée

Si vous avez spécifié SnapshotConflictPolicy::MANUAL comme règle de conflit, votre jeu doit résoudre tout conflit de données détecté avant d'effectuer d'autres opérations de lecture ou d'écriture sur la partie enregistrée.

Dans ce cas, lorsqu'un conflit de données est détecté, le service renvoie les paramètres suivants via SnapshotManager::OpenResponse :

• Un conflict_id permettant d'identifier de manière unique ce conflit (vous utiliserez cette valeur lorsque vous validerez la version finale du jeu enregistré) ;
• La version de base du jeu enregistré qui est en conflit.
• Version distante conflictuelle du jeu enregistré.

Votre jeu doit déterminer les données à enregistrer, puis appeler la méthode SnapshotManager::ResolveConflictBlocking() pour valider/résoudre la version finale sur les serveurs Google.

    //Resolve conflict
    gpg::SnapshotManager::OpenResponse resolveResponse =
        manager.ResolveConflictBlocking(openResponse.conflict_base, metadata_change,
                                  openResponse.conflict_id);

Écrire des jeux enregistrés

Pour écrire un jeu enregistré, commencez par ouvrir l'objet SnapshotMetadata représentant ce jeu enregistré, résolvez les conflits de données détectés, puis appelez la méthode SnapshotManager::Commit() pour valider les modifications apportées à votre jeu enregistré.

L'exemple suivant montre comment créer une modification et valider une partie enregistrée.

1. Pour commencer, ouvrez l'instantané que vous souhaitez modifier et assurez-vous que tous les conflits sont résolus en choisissant la base.

   service_->Snapshots().Open(
         file_name,
         gpg::SnapshotConflictPolicy::BASE_WINS,
         [this](gpg::SnapshotManager::OpenResponse const &response) {
           if (IsSuccess(response.status)) {
             // metadata : gpg::SnapshotMetadata
             metadata = response.data;
           } else {
             // Handle snapshot open error here
           }
         });
   

2. Ensuite, créez une modification de jeu enregistré qui inclut les données d'image utilisées pour l'image de couverture :

   gpg::SnapshotMetadataChange::Builder builder;
   gpg::SnapshotMetadataChange metadata_change =
       builder.SetDescription("CollectAllTheStar savedata")
                .SetCoverImageFromPngData(pngData).Create();
   

3. Enfin, validez les modifications apportées à la partie enregistrée.

   gpg::SnapshotManager::CommitResponse commitResponse =
       service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());
   

   Le paramètre "data" contient toutes les données de jeu enregistrées que vous stockez. La modification contient également des métadonnées de jeu enregistré supplémentaires, telles que le temps de jeu et une description du jeu enregistré.

Si l'opération d'envoi a abouti, les joueurs peuvent voir le jeu enregistré dans l'UI de sélection des jeux enregistrés.