Inizia a utilizzare i servizi per i giochi di Play per C++

L'SDK C++ di Google Play Games Services fornisce un'API C++ da usare con i servizi per i giochi di Google Play ed è destinato agli sviluppatori che hanno già un'implementazione C++ del proprio gioco.

Attualmente, l'SDK implementa i seguenti servizi:

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

Concetti

In linea generale, puoi utilizzare l'SDK seguendo questi passaggi:

  1. Imposta una configurazione della piattaforma per Android.
  2. Utilizzare 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 è riuscito, 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 per i giochi di Play, tra cui:

    • Accedi (dopo la mancata autorizzazione dell'autorizzazione): StartAuthorizationUI()
    • Sblocca obiettivi: Achievements().Unlock()
    • Mostra gli obiettivi utilizzando l'UI integrata: Achievements().ShowAllUI()
    • Invia un punteggio elevato: 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 sull'inizializzazione specifiche della piattaforma. Su Android, la configurazione della piattaforma contiene la VM Java e un puntatore al Activity attuale:

    // 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. Crea un oggetto GameServices: questo oggetto è il punto di contatto 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 persisterà per tutto il tempo in cui il tuo ambiente C lo farà; non è necessario inizializzarlo nuovamente quando Activity Android viene messo 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 Gestore per gestire l'oggetto GameServices. È possibile accedere ai gestori da un'istanza GameServices e raggruppare le funzionalità correlate. Alcuni esempi sono Gestori e Classifica. Non contengono nessuno stato visibile agli utenti. I gestori vengono restituiti per riferimento e l'istanza contenente GameServices controlla il loro ciclo di vita. Il cliente non deve mai conservare un riferimento all'account amministratore. Il tuo client dovrebbe invece mantenere l'istanza GameServices.

    I gestori restituiscono i dati tramite oggetti di tipo valore immutabili. Questi valori riflettono una visualizzazione coerente dei dati sottostanti nel momento in cui è stata effettuata 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 richiamando reset() sul dispositivo unique_ptr di sua proprietà o lasciando che unique_ptr lo elimini automaticamente quando non rientra nell'ambito.

Modello di thread

Salvo indicazione contraria, tutti i metodi GameServices e Manager utilizzano implementazioni asincrone in base al thread. Possono essere chiamate su qualsiasi thread senza blocco esterno ed eseguite in un ordine coerente con il loro ordine di chiamata.

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

// 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 piattaforma per "thread principale" o "thread dell'interfaccia utente". Dovresti inoltre assicurarti che i callback degli utenti vengano eseguiti rapidamente; un thread di callback bloccato potrebbe causare problemi visibili all'utente (ad esempio, il ritardo nel completamento di una richiesta di disconnessione).

Informazioni specifiche della piattaforma

Per iniziare a utilizzare l'SDK Play Giochi C++ su Android, continua con la guida rapida.

Per approfondire

Assicurati di leggere la documentazione relativa alla classe fornita nell'SDK C++ dei servizi per i giochi di Google Play per ulteriori dettagli e consulta gli esempi che mostrano come utilizzare l'SDK.

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