Usługi gier Play dla C++

Po wycofaniu interfejsu Google Sign-In API w 2026 roku usuniemy pakiet SDK dla gier w wersji 1. Z końcem lutego 2025 r. nie będzie już można publikować w Google Play nowych tytułów, w których zastosowano integrację z wersją 1 pakietu SDK dla gier. Zamiast tego zalecamy używanie pakietu SDK dla gier w wersji 2.
Dotychczasowe tytuły z integracjami gier w wersji 1 będą działać jeszcze przez kilka lat, ale zachęcamy do przejścia na wersję 2 od czerwca 2025 r.
Ten przewodnik dotyczy korzystania z pakietu SDK dla usług gier Play w wersji 1. Pakiet C++ SDK dla usług gier Play w wersji 2 nie jest jeszcze dostępny.

Pakiet C++ SDK dla usług Gier Google Play udostępnia interfejs C++ API do używania z usługami Gier Google Play i jest przeznaczony dla deweloperów, którzy mają już implementację gry w C++.

Obecnie pakiet SDK implementuje te usługi:

  • Autoryzacja
  • Osiągnięcia
  • Tabele wyników
  • Wydarzenia
  • Zapisane gry
  • Połączenia w pobliżu (tylko Android)
  • Statystyki gracza

Pojęcia

Aby używać pakietu SDK, wykonaj te czynności:

  1. Skonfiguruj platformę dla Androida.
  2. Użyj GameServices::Builder, aby skonfigurować i utworzyć obiekt GameServices. Obiekt GameServices automatycznie próbuje zalogować użytkownika i zwraca wynik za pomocą wywołania zwrotnego OnAuthActionFinished(). Zwróć uwagę na wynik zwrócony przez wywołanie zwrotne. Jeśli automatyczna próba zalogowania się nie powiodła, możesz wyświetlić przycisk, który umożliwi użytkownikom zalogowanie się.

  3. Po otrzymaniu wyniku OnAuthActionFinished() możesz użyć obiektu GameServices i jego menedżerów podrzędnych do wykonywania wywołań usług Gier Play, w tym:

    • Logowanie (po nieudanej autoryzacji): StartAuthorizationUI()
    • Odblokuj osiągnięcia: Achievements().Unlock()
    • Wyświetlanie osiągnięć za pomocą wbudowanego interfejsu: Achievements().ShowAllUI()
    • Przesyłanie rekordu: Leaderboards().SubmitScore()
    • Wyloguj się: SignOut()

  4. Gdy skończysz korzystać z obiektu GameServices, zresetuj go lub usuń.

Bardziej szczegółowo:

  1. Zainicjuj konfigurację platformy: jest to obiekt zawierający informacje o inicjowaniu specyficzne dla platformy. Na Androidzie konfiguracja platformy zawiera maszynę wirtualną Java i wskaźnik do bieżącego 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. Utwórz obiekt GameServices: ten obiekt jest głównym punktem wejścia do funkcji usług Gier Google Play. Instancje GameServices są tworzone za pomocą GameServices::Builder.

    W większości implementacji dany obiekt GameServices będzie istniał tak długo, jak długo będzie istniało środowisko C. Nie musisz go ponownie inicjować, gdy Android Activity wstrzymuje i wznawia działanie.

    // 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. Używaj klas menedżera do zarządzania obiektem GameServices. Dostęp do menedżerów uzyskuje się z instancji GameServices, a funkcje związane z grupą są zgrupowane. Przykładami są menedżery osiągnięć i tablic wyników. Same w sobie nie zawierają żadnego stanu widocznego dla użytkownika. Menedżery są zwracane przez odwołanie, a ich cyklem życia zarządza instancja GameServices. Klient nigdy nie powinien przechowywać referencji do menedżera. Zamiast tego powinien przechowywać referencję do instancji GameServices.

    Menedżery zwracają dane za pomocą obiektów typu wartości niezmiennej. Te wartości odzwierciedlają spójny widok danych bazowych w momencie, gdy zostało wykonane zapytanie.

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

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

  4. Gdy skończysz korzystać z obiektu GameServices, wyczyść go, wywołując reset() na obiekcie unique_ptr, do którego należy, lub pozwól, aby obiekt unique_ptr automatycznie go zniszczył po wyjściu poza zakres.

Model wątków

O ile nie zaznaczono inaczej, wszystkie metody GameServices i Menedżera mają bezpieczne wątkowo implementacje asynchroniczne. Można je wywoływać w dowolnym wątku bez blokowania zewnętrznego, a wykonywane są w kolejności zgodnej z kolejnością wywoływania.

Metody dostępu (odczytujące stan) występują w 2 głównych wariantach. Pierwszy typ metody (o nazwach takich jak FetchProperty()) asynchronicznie dostarcza wyniki do podanego wywołania zwrotnego, a drugi (o nazwach takich jak FetchPropertyBlocking()) synchronicznie zwraca wyniki do wątku wywołującego.

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

Wszystkie wywołania zwrotne użytkownika są wywoływane w dedykowanym wątku wywołań zwrotnych. Ten wątek może się różnić od koncepcji „wątku głównego” lub „wątku UI” na danej platformie. Zadbaj też o to, aby wywołania zwrotne użytkownika były wykonywane szybko. Zablokowany wątek wywołania zwrotnego może powodować problemy widoczne dla użytkownika (np. opóźnione zakończenie żądania wylogowania).

Informacje dotyczące konkretnej platformy

Aby rozpocząć korzystanie z pakietu SDK C++ dla Gier Play na Androidzie, przejdź do przewodnika szybkiego startu.

Więcej materiałów

Więcej informacji znajdziesz w dokumentacji klas dołączonej do pakietu C++ SDK dla usług Gier Google Play. Zapoznaj się też z przykładami, które pokazują, jak korzystać z tego pakietu.

Jeśli Twoja gra korzysta z serwera backendu, zapoznaj się z artykułem Włączanie dostępu po stronie serwera do usług Gier Google Play.