Zdarzenia w grach na Androida

Po wycofaniu interfejsu Google Sign-In API w 2026 roku usuniemy pakiet SDK do 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 gier. Zamiast tego zalecamy używanie pakietu SDK do 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 usług gier Play w wersji 1. Informacje o najnowszej wersji pakietu SDK znajdziesz w dokumentacji wersji 2.

Z tego przewodnika dowiesz się, jak zbierać dane o rozgrywce na potrzeby analizy gier za pomocą interfejsów API zdarzeń udostępnianych przez Usługi gier Google Play. Interfejsy API znajdziesz w com.google.android.gms.games.event i com.google.android.gms.games.

Zanim zaczniesz

Jeśli jeszcze tego nie zrobiono, warto zapoznać się z pojęciami dotyczącymi gier z wydarzeniami.

Zanim zaczniesz pisać kod z użyciem interfejsów API zdarzeń:

Pobieranie klienta zdarzeń

Aby zacząć korzystać z interfejsów API zdarzeń, gra musi najpierw uzyskać obiekt EventsClient. Aby to zrobić, wywołaj metodę Games.getEventsClient() i przekaż do niej aktywność oraz GoogleSignInAccount bieżącego gracza. Aby dowiedzieć się, jak pobrać informacje o koncie gracza, przeczytaj artykuł Logowanie się w grach na Androida.

Przesyłanie zdarzeń

Możesz dodać do gry kod, który będzie powiadamiał usługi gier Google Play o każdym zdarzeniu istotnym dla Twojej gry.

Aby wysłać aktualizację zdarzenia, wywołaj funkcję EventsClient.increment() z wartością eventId i liczbą całkowitą incrementAmount, która jest równa lub większa od 0.

  • Identyfikator eventId jest generowany przez usługi gier Google Play, gdy po raz pierwszy zdefiniujesz zdarzenie w Konsoli Google Play. Służy on do jednoznacznego identyfikowania tego zdarzenia w grze.
  • Za pomocą danych wejściowych incrementAmount możesz określić ilościowy postęp gracza w realizacji określonego celu w grze. Jeśli na przykład zdarzeniem, które gra chce śledzić, jest „Pokonaj 500 potworów o wyłupiastych oczach”, wartość incrementAmount może być liczbą potworów zabitych przez gracza w jednej bitwie.

Oto przykład przesyłania zdarzenia z wartością przyrostową 1:

public void submitEvent(String eventId) {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .increment(eventId, 1);
}

Pobieranie zdarzeń

Możesz pobrać wszystkie dane zdarzeń przechowywane na serwerach Google dotyczące Twojej gry, wywołując funkcję EventsClient.load(). W wywołaniu metody przekaż wartość logiczną, aby wskazać, czy Usługi gier Google Play mają wyczyścić lokalnie buforowane dane na urządzeniu użytkownika.

Aby pobrać dane dotyczące konkretnych zdarzeń zdefiniowanych w Konsoli Google Play, wywołaj funkcję EventsClient.loadByIds() i przekaż tablicę identyfikatorów zdarzeń w parametrach wejściowych.

Ten fragment kodu pokazuje, jak wysłać do usług gier Google Play zapytanie o listę wszystkich zdarzeń w Twojej grze:

public void loadEvents() {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .load(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<EventBuffer>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<EventBuffer>> task) {
          if (task.isSuccessful()) {
            // Process all the events.
            for (Event event : task.getResult().get()) {
              Log.d(TAG, "loaded event " + event.getName());
            }
          } else {
            // Handle Error
            Exception exception = task.getException();
            int statusCode = CommonStatusCodes.DEVELOPER_ERROR;
            if (exception instanceof ApiException) {
              ApiException apiException = (ApiException) exception;
              statusCode = apiException.getStatusCode();
            }
            showError(statusCode);
          }
        }
      });
}