Servizi per i giochi di Play per C++

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.

L'SDK C++ dei servizi per i giochi di Google Play fornisce un'API C++ da utilizzare con i servizi per i giochi di Google Play ed è destinato agli sviluppatori che hanno un'implementazione C++ esistente del proprio gioco.

Attualmente, l'SDK implementa i seguenti servizi:

  • Autorizzazione
  • Obiettivi
  • Classifiche
  • Eventi
  • Partite salvate
  • Connessioni nelle vicinanze (solo Android)
  • Statistiche giocatore

Concetti

A livello generale, per utilizzare l'SDK segui questi passaggi:

  1. Configura una configurazione della piattaforma per Android.
  2. Utilizza un GameServices::Builder per configurare e costruire un oggetto GameServices. L'oggetto GameServices tenta automaticamente di accedere e restituisce il risultato tramite un callback OnAuthActionFinished(). Prendi nota del risultato restituito dal callback. Se il tentativo di accesso automatico non è andato a buon fine, puoi visualizzare un pulsante per consentire agli utenti di accedere.

  3. Dopo aver ricevuto il risultato OnAuthActionFinished(), puoi utilizzare l'oggetto GameServices e i relativi gestori secondari per effettuare chiamate ai servizi Play Giochi, tra cui:

    • Accedi (dopo l'autorizzazione non riuscita): StartAuthorizationUI()
    • Sblocca obiettivi: Achievements().Unlock()
    • Mostra gli obiettivi utilizzando l'interfaccia utente integrata: Achievements().ShowAllUI()
    • Invia un miglior punteggio: Leaderboards().SubmitScore()
    • Esci: SignOut()

  4. Quando hai finito di utilizzare l'oggetto GameServices, reimpostalo o distruggilo.

A un livello più dettagliato:

  1. Inizializza una configurazione della piattaforma: si tratta di un oggetto che contiene informazioni di inizializzazione specifiche della piattaforma. Su Android, la configurazione della piattaforma contiene la VM Java e un puntatore all'Activity corrente:

    // In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);

  2. Costruisci un oggetto GameServices: questo oggetto è il punto di ingresso principale per la funzionalità dei servizi per i giochi di Google Play. Le istanze GameServices vengono create con GameServices::Builder.

    Nella maggior parte delle implementazioni, un determinato oggetto GameServices persiste finché l'ambiente C; non è necessario reinizializzarlo quando Android Activity si mette in pausa e riprende.

    // Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
        .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
        .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
            is_auth_in_progress_ = true;
            started_callback(op);
        })
        .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                     gpg::AuthStatus status) {
            LOGI("Sign in finished with a result of %d", status);
            is_auth_in_progress_ = false;
            finished_callback(op, status);
        })
        .Create(pc);

  3. Utilizza le classi Manager per gestire l'oggetto GameServices. I gestori sono accessibili da un'istanza GameServices e raggruppano le funzionalità correlate. Alcuni esempi includono i gestori di obiettivi e classifiche. Non contengono stati visibili all'utente. I gestori vengono restituiti per riferimento e la relativa istanza GameServices ne controlla il ciclo di vita. Il cliente non deve mai conservare un riferimento all'amministratore. Il tuo cliente deve invece conservare l'istanza GameServices.

    I gestori restituiscono i dati tramite oggetti di tipo valore immutabile. Questi valori riflettono una visione coerente dei dati sottostanti nel momento in cui è stata eseguita la query.

    // Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);

// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();

  4. Quando hai finito di utilizzare l'oggetto GameServices, esegui la pulizia chiamando reset() sull'oggetto unique_ptr che lo possiede o consentendo all'oggetto unique_ptr di distruggerlo automaticamente quando esce dall'ambito.

Modello di threading

Se non diversamente indicato, tutti i metodi GameServices e Manager hanno implementazioni asincrone e thread-safe. Possono essere chiamati su qualsiasi thread senza blocco esterno e verranno eseguiti in un ordine coerente con il loro ordine di invocazione.

I metodi di accesso (quelli che leggono lo stato) sono disponibili in due varianti principali. Il primo tipo di metodo (con nomi come FetchProperty()) fornisce in modo asincrono i risultati a un callback fornito; il secondo (con nomi come FetchPropertyBlocking()) restituisce in modo sincrono i risultati al thread chiamante.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Tutti i callback utente vengono richiamati su un thread di callback dedicato. Questo thread è potenzialmente distinto da qualsiasi concetto di "thread principale" o "thread UI" della piattaforma. Dovresti anche cercare di assicurarti che i callback utente vengano eseguiti rapidamente; un thread di callback bloccato potrebbe causare problemi visibili all'utente (ad esempio, il completamento ritardato di una richiesta di disconnessione).

Informazioni specifiche della piattaforma

Per iniziare a utilizzare l'SDK Play Games C++ su Android, consulta la guida rapida.

Continua a leggere

Per ulteriori dettagli, assicurati di leggere la documentazione della classe inclusa nell'SDK C++ dei servizi per i giochi di Google Play e consulta gli esempi che mostrano come utilizzare l'SDK.

Se il tuo gioco utilizza un server di backend, consulta la sezione Attivare l'accesso lato server ai servizi per i giochi di Google Play.