Erste Schritte mit Play-Spieldiensten für C++

Das C++ SDK der Google Play-Spieldienste bietet eine C++ API für Google Play-Spieldienste und ist für Entwickler gedacht, die eine C++-Implementierung für ihr Spiel haben.

Derzeit implementiert das SDK die folgenden Dienste:

  • Autorisierung
  • Erfolge
  • Bestenlisten
  • Events
  • Gespeicherte Spiele
  • Nearby Connections (nur Android)
  • Spielerstatistiken

Konzepte

Auf übergeordneter Ebene verwenden Sie das SDK folgendermaßen:

  1. Richten Sie eine Plattformkonfiguration für Android ein.
  2. Mit GameServices::Builder können Sie ein GameServices-Objekt konfigurieren und erstellen. Das GameServices-Objekt versucht automatisch, sich anzumelden, und gibt das Ergebnis über einen OnAuthActionFinished()-Callback zurück. Notieren Sie sich das vom Callback zurückgegebene Ergebnis. Wenn der automatische Anmeldeversuch fehlgeschlagen ist, können Sie eine Schaltfläche anzeigen, über die sich Nutzer anmelden können.

  3. Nach dem Empfang des OnAuthActionFinished()-Ergebnisses können Sie das GameServices-Objekt und seine untergeordneten Manager verwenden, um Play Spiele-Dienstaufrufe auszuführen, einschließlich:

    • Anmelden (nach fehlgeschlagener Autorisierung): StartAuthorizationUI()
    • Erfolge freischalten: Achievements().Unlock()
    • Erfolge über die integrierte Benutzeroberfläche anzeigen: Achievements().ShowAllUI()
    • Highscore senden: Leaderboards().SubmitScore()
    • Abmelden: SignOut()

  4. Wenn Sie das GameServices-Objekt nicht mehr verwenden möchten, setzen Sie es zurück oder löschen Sie es.

Detailliertere Informationen:

  1. Plattformkonfiguration initialisieren: Dies ist ein Objekt, das plattformspezifische Initialisierungsinformationen enthält. Unter Android enthält die Plattformkonfiguration die Java-VM und einen Verweis auf den aktuellen Activity:

    // 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. Erstellen Sie ein GameServices-Objekt: Dieses Objekt ist der Haupteinstiegspunkt für die Funktionalität der Google Play-Spieldienste. GameServices-Instanzen werden mit GameServices::Builder erstellt.

    In den meisten Implementierungen bleibt ein GameServices-Objekt so lange bestehen wie Ihre C-Umgebung. Sie müssen es nicht neu initialisieren, wenn Ihr Android-Activity pausiert und fortgesetzt wird.

    // 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. Mit den Manager-Klassen können Sie Ihr GameServices-Objekt verwalten. Der Zugriff auf Manager erfolgt über eine GameServices-Instanz und gruppenbezogene Funktionen. Beispiele hierfür sind die Manager für Erfolge und Bestenlisten. Sie enthalten selbst keinen für den Nutzer sichtbaren Status. Administratoren werden per Referenz zurückgegeben und die enthaltende GameServices-Instanz steuert ihren Lebenszyklus. Ihr Kunde sollte niemals eine Managerreferenz zur Hand haben. Stattdessen sollte Ihr Client an der Instanz GameServices warten.

    Manager geben Daten über unveränderliche Objekttypen zurück. Diese Werte spiegeln eine konsistente Ansicht der zugrunde liegenden Daten zum Zeitpunkt der Abfrage wider.

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

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

  4. Wenn Sie das GameServices-Objekt nicht mehr benötigen, bereinigen Sie es, indem Sie reset() bei dem unique_ptr aufrufen, zu dem es gehört, oder unique_ptr das Objekt automatisch löschen lassen, wenn es nicht mehr zum Umfang gehört.

Threading-Modell

Sofern nicht anders angegeben, haben alle GameServices- und Manager-Methoden threadsichere, asynchrone Implementierungen. Sie können in jedem Thread ohne externe Sperre aufgerufen werden und werden in einer Reihenfolge ausgeführt, die ihrer Aufrufreihenfolge entspricht.

Es gibt zwei Hauptvarianten von Zugriffsmethoden (Methoden zum Lesen). Bei der ersten Methode (mit Namen wie FetchProperty()) werden die Ergebnisse asynchron an einen bereitgestellten Callback übergeben. Bei der zweiten Methode (mit Namen wie FetchPropertyBlocking()) werden die Ergebnisse synchron an den aufrufenden Thread zurückgegeben.

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

Alle Callbacks für Nutzer werden über einen eigenen Callback-Thread aufgerufen. Dieser Thread unterscheidet sich potenziell von jedem Plattformkonzept eines „Hauptthreads“ oder eines „UI-Threads“. Sie sollten auch darauf achten, dass Nutzer-Callbacks schnell ausgeführt werden. Ein angehaltener Callback-Thread kann für den Nutzer sichtbare Probleme verursachen, z. B. die verzögerte Ausführung einer Abmeldeanfrage.

Plattformspezifische Informationen

Informationen zur Verwendung des Play Games C++ SDK unter Android finden Sie in der Kurzanleitung.

Weitere Informationen

Weitere Informationen finden Sie in der Klassendokumentation im C++ SDK der Google Play-Spieldienste und in den Beispielen für die Verwendung des SDKs.

Wenn Ihr Spiel einen Back-End-Server verwendet, finden Sie weitere Informationen unter Serverseitigen Zugriff auf Google Play-Spieldienste aktivieren.