Play-Spieldienste für C++

Nach der Einstellung der Google-Anmeldung-API wird das games v1 SDK im Jahr 2026 entfernt. Ab Februar 2025 kannst du bei Google Play keine Titel mehr veröffentlichen, die neu in Games SDK V1 integriert wurden. Wir empfehlen, stattdessen das Games SDK V2 zu verwenden.
Bestehende Titel mit den vorherigen Integrationen für Spiele v1 funktionieren zwar noch einige Jahre, aber wir empfehlen Ihnen, ab Juni 2025 zu Version 2 zu migrieren.
In diesem Leitfaden wird die Verwendung des Play Games Services SDK V1 beschrieben. Das C++ SDK für Play Games Services v2 ist noch nicht verfügbar.

Das C++ SDK für die Google Play-Spieldienste bietet eine C++ API für die Verwendung mit den Google Play-Spieldiensten und ist für Entwickler gedacht, die bereits eine C++-Implementierung ihres Spiels haben.

Derzeit implementiert das SDK die folgenden Dienste:

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

Concepts

Auf übergeordneter Ebene verwenden Sie das SDK so:

  1. Richten Sie eine Plattformkonfiguration für Android ein.
  2. Verwenden Sie ein GameServices::Builder-Objekt, um ein GameServices-Objekt zu konfigurieren und zu 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 einblenden, über die sich Nutzer anmelden können.

  3. Nachdem Sie das OnAuthActionFinished()-Ergebnis erhalten haben, können Sie das GameServices-Objekt und seine untergeordneten Manager verwenden, um Play Games-Dienste aufzurufen, darunter:

    • Anmelden (nachdem die Autorisierung fehlgeschlagen ist): StartAuthorizationUI()
    • Erfolge freischalten: Achievements().Unlock()
    • Erfolge über die integrierte Benutzeroberfläche anzeigen: Achievements().ShowAllUI()
    • Highscore einreichen: Leaderboards().SubmitScore()
    • Abmelden: SignOut()

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

Auf detaillierterer Ebene:

  1. Plattformkonfiguration initialisieren: Dies ist ein Objekt, das plattformspezifische Initialisierungsinformationen enthält. Unter Android enthält die Plattformkonfiguration die Java VM und einen Zeiger auf die aktuelle 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. GameServices-Objekt erstellen: Dieses Objekt ist der Haupteinstiegspunkt für die Funktionen der Google Play-Spieldienste. GameServices-Instanzen werden mit GameServices::Builder erstellt.

    In den meisten Implementierungen bleibt ein bestimmtes GameServices-Objekt so lange bestehen, wie Ihre C-Umgebung. Sie müssen es nicht neu initialisieren, wenn Ihre 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. Verwenden Sie die Manager-Klassen, um Ihr GameServices-Objekt zu verwalten. Auf Manager wird über eine GameServices-Instanz zugegriffen. Sie fassen gruppenbezogene Funktionen zusammen. Beispiele hierfür sind die Achievement- und Leaderboard-Manager. Sie enthalten keinen für Nutzer sichtbaren Status. Manager werden per Referenz zurückgegeben und ihr Lebenszyklus wird von der enthaltenden GameServices-Instanz gesteuert. Ihr Client sollte niemals eine Manager-Referenz behalten. Stattdessen sollte Ihr Kunde die GameServices-Instanz behalten.

    Manager geben Daten über unveränderliche Werttypobjekte 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, rufen Sie reset() für das zugehörige unique_ptr auf oder lassen Sie es automatisch zerstören, wenn es nicht mehr im Gültigkeitsbereich ist.unique_ptr

Threading-Modell

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

Accessor-Methoden (die den Status lesen) gibt es in zwei Hauptvarianten. Die erste Art von Methode (mit Namen wie FetchProperty()) stellt ihre Ergebnisse asynchron über einen bereitgestellten Callback bereit. Die zweite Art (mit Namen wie FetchPropertyBlocking()) gibt ihre Ergebnisse synchron an den aufrufenden Thread zurück.

// 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 Nutzer-Callbacks werden in einem dedizierten Callback-Thread aufgerufen. Dieser Thread unterscheidet sich möglicherweise vom Plattformkonzept eines „Hauptthreads“ oder „UI-Threads“. Außerdem sollten Sie darauf achten, dass Nutzer-Callbacks schnell ausgeführt werden. Ein blockierter Callback-Thread kann zu für Nutzer sichtbaren Problemen führen, z. B. zu einer verzögerten Ausführung einer Abmeldeanfrage.

Plattformspezifische Informationen

Wenn Sie das Play Games C++ SDK unter Android verwenden möchten, lesen Sie die Kurzanleitung.

Weitere Informationen

Weitere Informationen finden Sie in der Klassendokumentation, die im Google Play-Spieldienste C++ SDK enthalten ist. Außerdem können Sie sich die Beispiele ansehen, in denen die Verwendung des SDKs veranschaulicht wird.

Wenn Ihr Spiel einen Backend-Server verwendet, lesen Sie den Abschnitt Serverseitigen Zugriff auf die Google Play-Spieldienste aktivieren.