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 con le precedenti integrazioni di giochi v1 continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione alla v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK v1 dei servizi per i giochi di Play. L'SDK C++ per i servizi per i giochi di Play v2 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:

• Installa l'SDK Play Games C++.
• Configura l'ambiente di sviluppo C++.
• Scarica e rivedi l'esempio di codice C++.
• Attiva il servizio Partite salvate in Google Play Console.

Formati dei dati e compatibilità multipiattaforma

I dati di Saved Games che salvi sui server di Google devono essere in 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.

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

Attivare 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 con gli slot di salvataggio esistenti e consentire ai giocatori di salvare o caricare una partita da uno di questi slot oppure creare una nuova partita salvata. Per farlo, utilizza il seguente metodo:

  SnapshotManager::ShowSelectUIOperation(...)

L'interfaccia utente di selezione dei giochi salvati consente ai giocatori di creare una nuova partita salvata, visualizzare i dettagli delle partite salvate esistenti e caricare le partite salvate precedenti.

  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 delle 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, l'interfaccia utente predefinita di Snapshot fornisce ai giocatori un pulsante per creare un nuovo file di salvataggio, anziché selezionarne uno esistente. Se 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, devi prima aprire l'oggetto SnapshotMetadata che rappresenta la partita salvata. 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 il salvataggio del gioco memorizzato sul dispositivo locale di un giocatore non è sincronizzato con la versione remota memorizzata sui server di Google.

Le norme sui conflitti che specifichi quando apri una partita salvata indicano al servizio Partite salvate come risolvere automaticamente un conflitto di dati. Il criterio può essere uno dei seguenti:

Se hai specificato un criterio di conflitto diverso da GPGSnapshotConflictPolicyManual, il servizio Giochi salvati unirà il gioco salvato e restituirà la versione aggiornata tramite il valore SnapshotManager::OpenResponse risultante. Il gioco può aprire la partita salvata, scriverci e quindi 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 del salvataggio);
• La versione base in conflitto del gioco salvato.
• La versione remota in conflitto del gioco salvato.

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 rappresenta la partita salvata, risolvi eventuali conflitti di dati rilevati, quindi chiama il metodo SnapshotManager::Commit() per applicare le modifiche alla partita salvata.

L'esempio seguente mostra come creare una modifica e salvare una partita.

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 della partita salvata, 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 di selezione delle partite salvate.