Tabele wyników w grach na Androida

Ten przewodnik pokazuje, jak korzystać z interfejsów API tabel wyników w aplikacji na Androida, aby tworzyć wizualne tabele wyników, rejestrować wynik gracza i porównywać go z wynikiem z poprzednich sesji gry. Interfejsy API znajdziesz w pakietach com.google.android.gms.games i com.google.android.gms.games.leaderboards.

Zanim zaczniesz

Jeśli jeszcze tego nie zrobisz, warto zapoznać się z koncepcjami dotyczącymi tabel wyników.

Zanim zaczniesz pisać kod przy użyciu interfejsów API tabel wyników:

Postępuj zgodnie z instrukcjami instalowania i konfigurowania aplikacji do korzystania z usług gier Google Play w przewodniku Konfigurowanie pakietu SDK usług Google Play.
Zdefiniuj tabele wyników, które mają być wyświetlane lub aktualizowane w grze, zgodnie z instrukcjami w przewodniku po Konsoli Google Play.
Pobierz i przejrzyj przykłady kodu tabel wyników na stronie z przykładami na Androida w GitHubie.
Zapoznaj się z zaleceniami opisanymi w Checkliście jakości.

Pobieranie klienta tabel wyników

Aby zacząć korzystać z interfejsu API tabel wyników, gra musi najpierw uzyskać obiekt LeaderboardsClient. Możesz to zrobić, wywołując metodę PlayGames.getLeaderboardsClient() i przekazując aktywność.

Aktualizowanie wyniku gracza

Gdy wynik gracza się zmieni (np. gdy gracz ukończy grę), gra może zaktualizować jego wynik w tabeli wyników, wywołując metodę LeaderboardsClient.submitScore(), i przekazując identyfikator tabeli wyników oraz wartość wyniku.

Poniższy fragment kodu pokazuje, jak aplikacja może zaktualizować wynik gracza:

PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);

Dobrym rozwiązaniem jest zdefiniowanie identyfikatora tabeli wyników w pliku strings.xml, aby gra mogła odwoływać się do tabel wyników za pomocą identyfikatora zasobu. Podczas wywoływania funkcji aktualizujących i wczytujących wyniki graczy pamiętaj też o przestrzeganiu tych sprawdzonych metod, aby nie przekroczyć limitu interfejsu API.

Wyświetlanie tabeli wyników

Aby wyświetlić tabelę wyników, wywołaj LeaderboardsClient.getLeaderboardIntent(), aby uzyskać Intent do utworzenia domyślnego interfejsu tabeli wyników. Następnie gra może wyświetlić interfejs, wywołując startActivityForResult.

Poniższy fragment kodu pokazuje, jak aplikacja może zaktualizować wynik gracza. W tym fragmencie kodu RC_LEADERBOARD_UI to dowolna liczba całkowita oznaczająca kod żądania.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

Musisz użyć metody startActivityForResult, nawet jeśli nie zwraca ona żadnego wyniku. Umożliwia to interfejsowi API uzyskanie tożsamości pakietu wywołującego. Na ilustracji poniżej znajdziesz przykład domyślnego interfejsu tabeli wyników.

Przykład domyślnego interfejsu tablicy wyników — Przykład domyślnego interfejsu tabeli wyników.