Aggiungere partite salvate al tuo gioco

A seguito del ritiro dell'API Google Sign-In, rimuoveremo l'SDK v1 per i giochi nel 2026. Dopo febbraio 2025, non potrai pubblicare su Google Play titoli che sono stati integrati di recente con l'SDK v1 per i giochi. Ti consigliamo di utilizzare l'SDK v2 per i giochi.
Anche se i titoli esistenti integrati in precedenza con l'SDK v1 per i giochi continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione all'SDK v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK Play Games Services v1. L'SDK Play Games Services v2 C++ non è ancora disponibile.

Questa guida mostra come salvare e caricare i dati dei progressi di un giocatore utilizzando il servizio Partite salvate in un'applicazione C++. Puoi utilizzare questo servizio per caricare e salvare automaticamente i progressi di gioco del giocatore in qualsiasi momento durante il gameplay. Questo servizio può anche consentire ai giocatori di attivare un'interfaccia utente per aggiornare o ripristinare una partita salvata esistente o crearne una nuova.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile esaminare i concetti di gioco di Saved Games.

Prima di iniziare a scrivere codice utilizzando l'API Saved Games:

Formati dei dati e compatibilità multipiattaforma

I dati dei giochi salvati che salvi sui server di Google devono essere nel formato std::vector<uint8_t>. Il servizio Giochi salvati si occupa della codifica dei dati per la compatibilità multipiattaforma; le applicazioni Android possono leggere gli stessi dati come array di byte senza problemi di compatibilità multipiattaforma.

Evita di utilizzare formati specifici della piattaforma quando scegli un formato di dati per i dati dei giochi salvati. Ti consigliamo vivamente di utilizzare un formato di dati, come XML o JSON, che abbia un forte supporto di librerie su più piattaforme.

Attiva il servizio Partite salvate

Prima di poter utilizzare il servizio Giochi salvati, devi prima abilitarne l'accesso. Per farlo, chiama EnableSnapshots() quando crei il servizio con gpg::GameServices::Builder. In questo modo, al successivo evento di autenticazione verranno abilitati gli ambiti di autenticazione aggiuntivi richiesti da Giochi salvati.

Visualizzare le partite salvate

Nel tuo gioco, puoi fornire un'opzione che i giocatori possono attivare per salvare o ripristinare le partite salvate. Quando i giocatori selezionano questa opzione, il gioco dovrebbe mostrare una schermata che visualizza gli slot di salvataggio esistenti e consentire ai giocatori di salvare o caricare uno di questi slot o creare una nuova partita salvata. Per farlo, utilizza il seguente metodo:

  SnapshotManager::ShowSelectUIOperation(...)

L'interfaccia utente per la selezione delle partite salvate consente ai giocatori di creare una nuova partita salvata, visualizzare i dettagli delle partite salvate esistenti e caricare le partite salvate in precedenza.

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

Il seguente esempio mostra come visualizzare l'interfaccia utente predefinita del servizio Partite salvate e gestire la selezione dell'interfaccia utente del giocatore:

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

Se, nell'esempio precedente, ALLOW_CREATE_SNAPSHOT è true e MAX_SNAPSHOTS è maggiore del numero effettivo di snapshot che l'utente ha creato attualmente, la UI predefinita di Snapshot offre ai giocatori un pulsante per creare un nuovo salvataggio, anziché selezionarne uno esistente. Quando viene visualizzato, il pulsante si trova nella parte inferiore dell'interfaccia utente. Quando un giocatore fa clic su questo pulsante, la risposta SnapshotSelectUIResponse è valida, ma non contiene dati.

Aprire e leggere le partite salvate

Per accedere a una partita salvata e leggere o modificare i relativi contenuti, apri prima l'oggetto SnapshotMetadata che la rappresenta. Quindi, chiama il metodo SnapshotManager::Read*().

Il seguente esempio mostra come aprire una partita salvata:

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

Rilevare e risolvere i conflitti di dati

Quando apri un oggetto SnapshotMetadata, il servizio Partite salvate rileva se esiste una partita salvata in conflitto. I conflitti di dati possono verificarsi quando la partita salvata memorizzata sul dispositivo locale di un giocatore non è sincronizzata con la versione remota memorizzata sui server di Google.

La norma sui conflitti specificata all'apertura di una partita salvata indica al servizio Partite salvate come risolvere automaticamente un conflitto di dati. Il criterio può essere uno dei seguenti:

Norme relative ai conflitti Descrizione
SnapshotConflictPolicy::MANUAL Indica che il servizio Partite salvate non deve eseguire alcuna azione di risoluzione. Il gioco eseguirà invece un'unione personalizzata.
SnapshotConflictPolicy::LONGEST_PLAYTIME Indica che il servizio Partite salvate deve scegliere la partita salvata con il valore di tempo di gioco più alto.
SnapshotConflictPolicy::BASE_WINS Indica che il servizio Partite salvate deve scegliere la partita salvata di base.
SnapshotConflictPolicy::REMOTE_WINS Indica che il servizio Partite salvate deve scegliere la partita salvata remota. La versione remota è una versione della partita salvata che viene rilevata su uno dei dispositivi del giocatore e ha un timestamp più recente rispetto alla versione di base.

Se hai specificato un criterio di conflitto diverso da GPGSnapshotConflictPolicyManual, il servizio Giochi salvati unirà la partita salvata e restituirà la versione aggiornata tramite il valore SnapshotManager::OpenResponse risultante. Il tuo gioco può aprire la partita salvata, scriverci e poi chiamare il metodo SnapshotManager::Commit(...) per eseguire il commit della partita salvata sui server di Google.

Eseguire un'unione personalizzata

Se hai specificato SnapshotConflictPolicy::MANUAL come norma di conflitto, il gioco deve risolvere qualsiasi conflitto di dati rilevato prima di eseguire ulteriori operazioni di lettura o scrittura sulla partita salvata.

In questo caso, quando viene rilevato un conflitto di dati, il servizio restituisce i seguenti parametri tramite SnapshotManager::OpenResponse:

  • Un conflict_id per identificare in modo univoco questo conflitto (utilizzerai questo valore quando esegui il commit della versione finale della partita salvata);
  • La versione base in conflitto della partita salvata.
  • La versione remota in conflitto della partita salvata.

Il gioco deve decidere quali dati salvare, quindi chiamare il metodo SnapshotManager::ResolveConflictBlocking() per eseguire il commit/risolvere la versione finale sui server di Google.

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

Scrivere le partite salvate

Per scrivere una partita salvata, apri prima l'oggetto SnapshotMetadata che la rappresenta, risolvi eventuali conflitti di dati rilevati, quindi chiama il metodo SnapshotManager::Commit() per eseguire il commit delle modifiche alla partita salvata.

L'esempio seguente mostra come creare una modifica ed eseguire il commit di una partita salvata.

  1. Innanzitutto, apri lo snapshot che vuoi modificare e assicurati che tutti i conflitti siano risolti scegliendo 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. Successivamente, crea una modifica della partita salvata che includa i dati dell'immagine utilizzati per l'immagine di copertina:

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

  3. Infine, esegui il commit delle modifiche al salvataggio.

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

    Il parametro data contiene tutti i dati di salvataggio del gioco che stai archiviando. La modifica contiene anche metadati aggiuntivi delle partite salvate, come il tempo di gioco e una descrizione della partita salvata.

Se l'operazione di commit è stata completata correttamente, i giocatori possono vedere la partita salvata nell'interfaccia utente per la selezione delle partite salvate.