Agrega partidas guardadas a tu juego

Tras la baja de la API de Google Sign-In, quitaremos el SDK de juegos de la versión 1 en 2026. Después de febrero de 2025, no podrás publicar títulos que se hayan integrado recientemente con la versión 1 del SDK de juegos en Google Play. Te recomendamos que uses la versión 2 del SDK de juegos.
Si bien los títulos existentes con las integraciones anteriores de la versión 1 de los juegos seguirán funcionando durante un par de años, te recomendamos que migres a la versión 2 a partir de junio de 2025.
Esta guía se aplica al uso del SDK de la versión 1 de los Servicios de juego de Play. El SDK de C++ para la versión 2 de los Servicios de juego de Play aún no está disponible.

En esta guía, se muestra cómo guardar y cargar los datos de progreso de un jugador en el juego con el servicio de Juegos guardados en una aplicación de C++. Puedes usar este servicio para cargar y guardar automáticamente el progreso del jugador en cualquier momento durante el juego. Este servicio también puede permitir que los jugadores activen una interfaz de usuario para actualizar o restablecer una partida guardada existente, o bien crear una nueva.

Antes de comenzar

Si aún no lo hiciste, puede resultarte útil consultar los conceptos de juegos guardados.

Antes de comenzar a programar con la API de Saved Games, haz lo siguiente:

Formatos de datos y compatibilidad multiplataforma

Los datos de Juegos Guardados que guardes en los servidores de Google deben estar en formato std::vector<uint8_t>. El servicio de Juegos guardados se encarga de codificar tus datos para la compatibilidad multiplataforma. Las aplicaciones para Android pueden leer estos mismos datos como un array de bytes sin problemas de compatibilidad multiplataforma.

Evita usar formatos específicos de la plataforma cuando elijas un formato de datos para tus datos de Juegos guardados. Te recomendamos que uses un formato de datos, como XML o JSON, que tenga una gran compatibilidad de bibliotecas en varias plataformas.

Habilita el servicio de Juegos guardados

Antes de usar el servicio de Juegos guardados, primero debes habilitar el acceso a él. Para ello, llama a EnableSnapshots() cuando crees el servicio con gpg::GameServices::Builder. Esto habilitará los alcances de autorización adicionales que requieren los Juegos guardados en el próximo evento de autorización.

Mostrar juegos guardados

En tu juego, puedes proporcionar una opción que los jugadores puedan activar para guardar o restablecer juegos guardados. Cuando los jugadores seleccionen esta opción, tu juego debe mostrar una pantalla en la que se muestren las ranuras de guardado existentes y permitir que los jugadores guarden o carguen el juego desde una de estas ranuras, o bien que creen un nuevo juego guardado. Para ello, usa el siguiente método:

  SnapshotManager::ShowSelectUIOperation(...)

La IU de selección de juegos guardados permite que los jugadores creen un nuevo juego guardado, consulten los detalles de los juegos guardados existentes y carguen los juegos guardados anteriores.

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

En el siguiente ejemplo, se ilustra cómo mostrar la IU de Juegos guardados predeterminada y controlar la selección de la IU del jugador:

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

Si, en el ejemplo anterior, ALLOW_CREATE_SNAPSHOT es true y MAX_SNAPSHOTS es mayor que la cantidad real de instantáneas que el usuario creó actualmente, la IU de instantáneas predeterminada les proporciona a los jugadores un botón para crear una nueva partida guardada, en lugar de seleccionar una existente. (Cuando se muestra, el botón se encuentra en la parte inferior de la IU). Cuando un jugador hace clic en este botón, la respuesta de SnapshotSelectUIResponse es válida, pero no tiene datos.

Abrir y leer juegos guardados

Para acceder a un juego guardado y leer o modificar su contenido, primero abre el objeto SnapshotMetadata que representa ese juego guardado. A continuación, llama al método SnapshotManager::Read*().

En el siguiente ejemplo, se muestra cómo abrir un juego guardado:

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

Detecta y resuelve conflictos de datos

Cuando abres un objeto SnapshotMetadata, el servicio de Juegos guardados detecta si existe un juego guardado en conflicto. Pueden producirse conflictos de datos cuando el juego guardado que se almacenó en el dispositivo local del jugador no se sincroniza con la versión remota que se almacenó en los servidores de Google.

La política de conflictos que especificas cuando abres un juego guardado le indica al servicio de Juegos guardados cómo resolver automáticamente un conflicto de datos. La política puede ser una de las siguientes:

Política de Conflictos Descripción
SnapshotConflictPolicy::MANUAL Indica que el servicio de Juegos guardados no debe realizar ninguna acción de resolución. En cambio, tu juego realizará una combinación personalizada.
SnapshotConflictPolicy::LONGEST_PLAYTIME Indica que el servicio de Juegos guardados debe elegir el juego guardado con el valor de tiempo de juego más alto.
SnapshotConflictPolicy::BASE_WINS Indica que el servicio de Juegos guardados debe elegir el juego guardado base.
SnapshotConflictPolicy::REMOTE_WINS Indica que el servicio de Juegos guardados debe elegir el juego guardado remoto. La versión remota es una versión del juego guardado que se detecta en uno de los dispositivos del jugador y tiene una marca de tiempo más reciente que la versión base.

Si especificaste una política de conflictos que no sea GPGSnapshotConflictPolicyManual, el servicio de Juegos guardados combinará el juego guardado y devolverá la versión actualizada a través del valor SnapshotManager::OpenResponse resultante. Tu juego puede abrir el juego guardado, escribir en él y, luego, llamar al método SnapshotManager::Commit(...) para confirmar el juego guardado en los servidores de Google.

Cómo realizar una combinación personalizada

Si especificaste SnapshotConflictPolicy::MANUAL como política de conflicto, tu juego debe resolver cualquier conflicto de datos detectado antes de realizar más operaciones de lectura o escritura en el juego guardado.

En este caso, cuando se detecta un conflicto de datos, el servicio devuelve los siguientes parámetros a través de SnapshotManager::OpenResponse:

  • Un conflict_id para identificar de forma única este conflicto (usarás este valor cuando confirmes la versión final del juego guardado)
  • La versión base en conflicto del juego guardado
  • Es la versión remota en conflicto del juego guardado.

Tu juego debe decidir qué datos guardar y, luego, llamar al método SnapshotManager::ResolveConflictBlocking() para confirmar o resolver la versión final en los servidores de Google.

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

Escribe los juegos guardados

Para escribir un juego guardado, primero abre el objeto SnapshotMetadata que representa ese juego guardado, resuelve los conflictos de datos detectados y, luego, llama al método SnapshotManager::Commit() para confirmar los cambios del juego guardado.

En el siguiente ejemplo, se muestra cómo crear un cambio y confirmar un juego guardado.

  1. Primero, abre la instantánea que deseas editar y asegúrate de que todos los conflictos se resuelvan eligiendo 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. A continuación, crea un cambio de juego guardado que incluya los datos de la imagen que se usará para la imagen de portada:

    gpg::SnapshotMetadataChange::Builder builder;
    gpg::SnapshotMetadataChange metadata_change =
        builder.SetDescription("CollectAllTheStar savedata")
                 .SetCoverImageFromPngData(pngData).Create();
    
  3. Por último, confirma los cambios del juego guardado.

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

    El parámetro data contiene todos los datos del juego guardado que almacenas. El cambio también contiene metadatos adicionales del juego guardado, como el tiempo de juego y una descripción del juego guardado.

Si la operación de confirmación se completó correctamente, los jugadores podrán ver el juego guardado en la IU de selección de Juegos guardados.