Esta página foi traduzida pela API Cloud Translation.

Adicionar jogos salvos ao seu jogo

Após a descontinuação da API Login do Google, vamos remover o SDK dos serviços relacionados a jogos v1 em 2026. A partir de fevereiro de 2025, não será mais possível publicar no Google Play títulos que foram integrados ao SDK dos serviços relacionados a jogos do Google Play V1. Recomendamos que você use o SDK do Google Play Games v2.
Embora os títulos atuais com as integrações anteriores da v1 de jogos continuem funcionando por alguns anos, recomendamos que você migre para a v2 a partir de junho de 2025.
Este guia é para usar o SDK dos serviços relacionados a jogos do Google Play v1. O SDK C++ para os serviços relacionados a jogos do Google Play v2 ainda não está disponível.

Este guia mostra como salvar e carregar os dados de progresso de um jogador usando o serviço de Jogos salvos em um aplicativo C++. Você pode usar esse serviço para carregar e salvar automaticamente o progresso do jogo do jogador a qualquer momento durante a jogabilidade. Esse serviço também permite que os jogadores acionem uma interface do usuário para atualizar ou restaurar um jogo salvo ou criar um novo.

Antes de começar

Caso ainda não tenha feito isso, recomendamos consultar os conceitos de jogos salvos.

Antes de começar a programar usando a API Saved Games:

Formatos de dados e compatibilidade entre plataformas

Os dados de jogos salvos que você salva nos servidores do Google precisam estar no formato std::vector<uint8_t>. O serviço Jogos salvos cuida da codificação dos seus dados para compatibilidade entre plataformas. Os aplicativos Android podem ler esses mesmos dados como uma matriz de bytes sem problemas de compatibilidade entre plataformas.

Evite usar formatos específicos da plataforma ao escolher um formato de dados para seus dados de Jogos salvos. Recomendamos usar um formato de dados, como XML ou JSON, que tenha suporte de biblioteca em várias plataformas.

Ativar o serviço Jogos salvos

Antes de usar o serviço de Jogos salvos, é necessário ativar o acesso a ele. Para fazer isso, chame EnableSnapshots() ao criar o serviço com gpg::GameServices::Builder. Isso vai ativar os escopos de autenticação adicionais necessários pelos Jogos salvos no próximo evento de autenticação.

Mostrar jogos salvos

No jogo, você pode oferecer uma opção que os jogadores podem acionar para salvar ou restaurar jogos salvos. Quando os jogadores selecionam essa opção, o jogo precisa mostrar uma tela com os slots de salvamento disponíveis e permitir que os jogadores salvem ou carreguem um desses slots ou criem um novo jogo salvo. Use o seguinte método para fazer isso:

  SnapshotManager::ShowSelectUIOperation(...)

A interface de seleção de jogos salvos permite que os jogadores criem um novo jogo salvo, vejam detalhes sobre os já existentes e carreguem os 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);
}

O exemplo a seguir ilustra como abrir a UI padrão de jogos salvos e processar a seleção de UI do jogador:

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

Se, no exemplo acima, ALLOW_CREATE_SNAPSHOT for true e MAX_SNAPSHOTS for maior que o número real de snapshots que o usuário criou, a interface padrão do Snapshot vai oferecer aos jogadores um botão para criar um novo jogo salvo, em vez de selecionar um já existente. Quando mostrado, o botão fica na parte de baixo da interface. Quando um jogador clica nesse botão, a resposta SnapshotSelectUIResponse é válida, mas não tem dados.

Abrir e ler jogos salvos

Para acessar um jogo salvo e ler ou modificar o conteúdo dele, primeiro abra o objeto SnapshotMetadata que representa esse jogo salvo. Em seguida, chame o método SnapshotManager::Read*().

O exemplo a seguir mostra como abrir um jogo salvo:

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

Detectar e resolver conflitos de dados

Ao abrir um objeto SnapshotMetadata, o serviço de Jogos salvos detecta se existe um jogo salvo conflitante. Conflitos de dados podem ocorrer quando o jogo salvo no dispositivo local de um jogador está dessincronizado com a versão remota armazenada nos servidores do Google.

A política de conflitos especificada ao abrir um jogo salvo informa ao serviço de Jogos salvos como resolver automaticamente um conflito de dados. A política pode ser uma das seguintes:

Política de conflitos	Descrição
`SnapshotConflictPolicy::MANUAL`	Indica que o serviço de jogos salvos não deve realizar nenhuma ação de resolução. Em vez disso, o jogo vai realizar uma fusão personalizada.
`SnapshotConflictPolicy::LONGEST_PLAYTIME`	Indica que o serviço Jogos salvos deve escolher o jogo salvo com o maior valor de tempo de jogo.
`SnapshotConflictPolicy::BASE_WINS`	Indica que o serviço Jogos salvos deve escolher o jogo salvo básico.
`SnapshotConflictPolicy::REMOTE_WINS`	Indica que o serviço Jogos salvos deve escolher o jogo salvo remoto. A versão remota é uma versão do jogo salvo detectada em um dos dispositivos do jogador e tem um carimbo de data/hora mais recente do que a versão base.

Se você especificou uma política de conflito diferente de GPGSnapshotConflictPolicyManual, o serviço de jogos salvos vai mesclar o jogo salvo e retornar a versão atualizada pelo valor SnapshotManager::OpenResponse resultante. O jogo pode abrir o jogo salvo, gravar nele e chamar o método SnapshotManager::Commit(...) para confirmar o jogo salvo nos servidores do Google.

Fazer uma junção personalizada

Se você especificou SnapshotConflictPolicy::MANUAL como a política de conflito, seu jogo precisa resolver qualquer conflito de dados detectado antes de realizar outras operações de leitura ou gravação no jogo salvo.

Nesse caso, quando um conflito de dados é detectado, o serviço retorna os seguintes parâmetros usando SnapshotManager::OpenResponse:

Um conflict_id para identificar exclusivamente esse conflito. Você vai usar esse valor ao confirmar a versão final do jogo salvo.
A versão de base conflitante do jogo salvo e
A versão remota conflitante do jogo salvo.

Seu jogo precisa decidir quais dados salvar e chamar o método SnapshotManager::ResolveConflictBlocking() para confirmar/resolver a versão final nos servidores do Google.

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

Gravar jogos salvos

Para gravar um jogo salvo, primeiro abra o objeto SnapshotMetadata que representa esse jogo salvo, resolva os conflitos de dados detectados e chame o método SnapshotManager::Commit() para confirmar as mudanças do jogo salvo.

O exemplo a seguir mostra como criar uma mudança e confirmar um jogo salvo.

Primeiro, abra o snapshot que você quer editar e escolha a base para resolver todos os conflitos.

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

Em seguida, crie uma mudança de jogo salvo que inclua os dados de imagem usados para a imagem da capa:

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

Por fim, confirme as mudanças salvas no jogo.
```
gpg::SnapshotManager::CommitResponse commitResponse =
    service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());
```
O parâmetro "data" contém todos os dados do jogo salvo que você está armazenando. A mudança também contém outros metadados de jogos salvos, como tempo jogado e uma descrição do jogo salvo.

Se a operação de commit for concluída com êxito, os jogadores poderão ver o jogo salvo na UI de seleção de jogos salvos.