Pierwsze kroki z usługami gier Play 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.

Witamy w świecie tworzenia gier na Androida z usługami gier Google Play.

Pakiet SDK do gier Play udostępnia usługi gier Google Play na różnych platformach, które umożliwiają łatwą integrację popularnych funkcji gier, takich jak osiągnięcia, tablice wyników i zapisane gry, z grami na tablety i telefony komórkowe.

Z tego szkolenia dowiesz się, jak zainstalować przykładową aplikację z grą na Androida i szybko rozpocząć tworzenie własnej gry na Androida. Przykładowa aplikacja Type-a-Number Challenge pokazuje, jak zintegrować osiągnięcia i tablice wyników z grą.

Zanim zaczniesz

Aby przygotować aplikację, wykonaj czynności opisane w poniższych sekcjach.

Wymagania wstępne dotyczące aplikacji

Sprawdź, czy w pliku kompilacji Twojej aplikacji znajdują się te wartości:

• wartość minSdkVersion wynosząca co najmniej 19.
• wartość compileSdkVersion wynosząca co najmniej 28.

Konfigurowanie gry w Konsoli Google Play

W Konsoli Google Play możesz zarządzać usługami gier Google Play w swojej grze i konfigurować metadane do autoryzacji i uwierzytelniania gry. Więcej informacji znajdziesz w artykule Konfigurowanie Usług gier Google Play.

Konfigurowanie aplikacji

W sekcjach buildscript i allprojects pliku build.gradle na poziomie projektu dodaj repozytorium Maven firmy Google i centralne repozytorium Maven:

  buildscript {
    repositories {
      google()
      mavenCentral()
    }
  }

  allprojects {
    repositories {
      google()
      mavenCentral()
    }
  }

Dodaj zależność Usług Google Play do pakietu SDK Usług gier Play do pliku build.gradle modułu. Jest to zwykle:app/build.gradle

  dependencies {
    implementation 'com.google.android.gms:play-services-games:23.2.0'
  }

Przewodnik po przykładowej aplikacji

Z tego szkolenia dowiesz się, jak zainstalować przykładową aplikację z grą na Androida i szybko rozpocząć tworzenie własnej gry na Androida. Przykładowa aplikacja Type-a-Number Challenge pokazuje, jak zintegrować osiągnięcia i tablice wyników z grą.

Krok 1. Pobierz przykładową aplikację

Aby skorzystać z tego przewodnika dla deweloperów, musisz pobrać przykładową aplikację na Androida Type-a-Number Challenge.

Aby pobrać i skonfigurować przykładową aplikację w Android Studio:

1. Pobierz przykłady na Androida ze strony pobierania przykładów.
2. Zaimportuj android-basic-samples projekt. Ten projekt zawiera TypeANumber i inne przykłady gier na Androida. Aby to zrobić w Android Studio:
   1. Kliknij Plik > Importuj projekt.
   2. Na komputerze deweloperskim przejdź do katalogu, w którym pobrano android-basic-samples. Wybierz plik android-basic-samples/build.gradle i kliknij OK.
3. W module TypeANumber otwórz AndroidManifest.xml i zmień nazwę pakietu z com.google.example.games.tanc na inną. Nowa nazwa pakietu nie może zaczynać się od znaków com.google, com.example ani com.android.

Krok 2. Skonfiguruj grę w Konsoli Google Play

W Konsoli Google Play możesz zarządzać usługami gier Google Play w swojej grze i konfigurować metadane do autoryzacji i uwierzytelniania gry.

Aby skonfigurować przykładową grę w Konsoli Google Play:

1. Otwórz Konsolę Google Play w przeglądarce i zaloguj się. Jeśli nie masz jeszcze konta w Konsoli Google Play, pojawi się prośba o jego utworzenie.
2. Aby dodać grę do Konsoli Google Play, postępuj zgodnie z tymi instrukcjami.
   1. Gdy pojawi się pytanie, czy w aplikacji używasz interfejsów API Google, wybierz W swojej grze nie używam jeszcze żadnych interfejsów API Google.
   2. Na potrzeby tego przewodnika dla deweloperów możesz wypełnić formularz własnymi informacjami o grze. Dla wygody możesz użyć ikon zastępczych i zrzutów ekranu dostępnych na stronie Pobrane.
3. Postępuj zgodnie z tymi instrukcjami, aby wygenerować identyfikator klienta OAuth 2.0 dla aplikacji na Androida.
   1. Podczas łączenia aplikacji na Androida podaj dokładną nazwę pakietu, której użyto wcześniej podczas zmiany nazwy pakietu przykładowego.
   2. Jeśli nie masz jeszcze pliku keystore i podpisanego certyfikatu, możesz je wygenerować za pomocą kreatora generowania podpisanego pliku APK w Android Studio. Aby dowiedzieć się, jak uruchomić kreator generowania podpisanego pliku APK, przeczytaj artykuł Podpisywanie aplikacji w Android Studio.
4. Zapisz te informacje, aby móc z nich skorzystać w przyszłości:
   1. Identyfikator aplikacji: ciąg znaków składający się tylko z cyfr (zwykle co najmniej 12), który znajduje się na początku identyfikatora klienta.
   2. Certyfikat podpisywania: zanotuj, którego certyfikatu używasz podczas konfigurowania dostępu do interfejsu API (certyfikat, którego odcisk cyfrowy SHA1 został podany). Podczas testowania lub publikowania aplikacji należy używać tego samego certyfikatu do jej podpisywania.
5. Skonfiguruj osiągnięcia w wyzwaniu „Wpisz liczbę”:
   1. W Konsoli Google Play kliknij kartę Osiągnięcia.
   2. Dodaj te przykładowe osiągnięcia:

      Nazwa	Opis	Instrukcje specjalne
      Prim	Uzyskaj wynik, który jest liczbą pierwszą.	Brak
      Humble	Poproś o wynik 0.	Brak
      Nie bądź taki pewny siebie, dzieciaku.	Poproś o wynik 9999 w dowolnym trybie.	Brak
      OMG U R TEH UBER LEET!	Uzyskaj wynik 1337.	Ustaw to osiągnięcie jako ukryte.
      Znudzenie	Zagraj w grę 10 razy.	Ustaw to osiągnięcie jako wielostopniowe z 10 krokami do odblokowania.
      Bardzo znudzony	Zagraj w grę 100 razy.	Ustaw to osiągnięcie jako wielostopniowe ze 100 krokami do odblokowania.

   3. Zanotuj identyfikatory (długie ciągi alfanumeryczne) każdego utworzonego przez siebie osiągnięcia.
   4. Skonfiguruj osiągnięcia odpowiednie dla Twojej gry. Więcej informacji znajdziesz w artykule Pojęcia związane z osiągnięciami i Jak wdrażać osiągnięcia na Androidzie.
6. Skonfiguruj tabele wyników w wyzwaniu „Wpisz liczbę”:
   1. W Konsoli Google Play kliknij kartę Tabele wyników.
   2. Dodaj 2 przykładowe tabele wyników: jedną o nazwie „Easy High Scores” (Łatwe najlepsze wyniki) i drugą o nazwie „Hard High Scores” (Trudne najlepsze wyniki). Obie tabele wyników powinny używać formatu wyniku „Liczba całkowita” z 0 miejscami po przecinku i typu kolejności Większa wartość jest lepsza.
   3. Zanotuj identyfikatory (długie ciągi alfanumeryczne) każdej utworzonej tablicy wyników.
   4. Skonfiguruj tabele wyników odpowiednie dla Twojej gry. Więcej informacji znajdziesz w artykule Podstawowe informacje o tabelach wyników i Jak zaimplementować tabele wyników na Androidzie.
7. Dodaj konta testowe do gry Ten krok jest wymagany tylko w przypadku aplikacji, które nie zostały jeszcze opublikowane w Konsoli Google Play. Zanim aplikacja zostanie opublikowana, logować się mogą tylko konta testowe wymienione w Konsoli Google Play. Gdy aplikacja zostanie opublikowana, każdy będzie mógł się zalogować.

Ostrzeżenie: jeśli spróbujesz wykonać wywołania pakietu SDK Gier Play w przypadku nieopublikowanej gry za pomocą konta, które nie jest wymienione jako konto testowe, Usługi gier Google Play będą się zachowywać tak, jakby gra nie istniała, i otrzymasz kod zwrotny ConnectionResult.SIGN_IN_REQUIRED. Jeśli spróbujesz uruchomić ConnectionResult.startResolutionForResult(), otrzymasz GamesActivityResultCodes.RESULT_SIGN_IN_FAILED.

Krok 3. Zmodyfikuj kod

Aby uruchomić grę, musisz skonfigurować identyfikator aplikacji jako zasób w projekcie Androida. Musisz też dodać metadane gier w pliku AndroidManifest.xml.

1. Otwórz plik res/values/ids.xml i zastąp identyfikatory obiektów zastępczych. Jeśli tworzysz grę na Androida od zera, musisz najpierw utworzyć ten plik.
   1. Określ identyfikator aplikacji w zasobie app_id.
   2. Określ każdy identyfikator osiągnięcia utworzony wcześniej w odpowiednim zasobie achievement_*.
   3. Określ każdy identyfikator tabeli wyników utworzony wcześniej w odpowiednim zasobie leaderboard_*.
2. Otwórz AndroidManifest.xml i wpisz nazwę pakietu w atrybucie package elementu <manifest>. Jeśli tworzysz grę na Androida od zera, pamiętaj, aby dodać ten kod w elemencie <application>:

   <meta-data android:name="com.google.android.gms.games.APP_ID"
       android:value="@string/app_id" />
   <meta-data android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version"/>
   

Krok 4. Przetestuj grę

Aby sprawdzić, czy usługi gier Play działają w Twojej grze prawidłowo, przetestuj aplikację przed opublikowaniem jej w Google Play.

Uwaga: zalecamy testowanie na fizycznym urządzeniu z Androidem. Jeśli jednak nie masz fizycznego urządzenia, możesz przeprowadzić testy w emulatorze Androida. Aby to zrobić, pobierz obraz systemu emulatora, który zawiera Usługi Google Play, w sekcji Android 4.2.2 w Menedżerze SDK.

Aby uruchomić grę na fizycznym urządzeniu testowym:

1. Sprawdź, czy masz skonfigurowane konto testowe, którego używasz do logowania się w aplikacji (zgodnie z opisem w kroku 2).
2. Wyeksportuj plik APK i podpisz go tym samym certyfikatem, którego użyto do skonfigurowania projektu w Konsoli Google Play. Aby wyeksportować podpisany pakiet APK w Android Studio, kliknij Build (Utwórz) > Generate Signed APK (Wygeneruj podpisany pakiet APK).
3. Zainstaluj podpisany plik APK na fizycznym urządzeniu testowym za pomocą narzędzia adb. Aby dowiedzieć się, jak zainstalować aplikację, przeczytaj artykuł Uruchamianie na urządzeniu.

Ostrzeżenie: gdy uruchamiasz aplikację bezpośrednio z Androida Studio, domyślnie podpisuje ją certyfikatem debugowania. Jeśli podczas konfigurowania aplikacji w Konsoli Google Play nie użyjesz tego certyfikatu debugowania, spowoduje to błędy. Uruchom wyeksportowany i podpisany pakiet APK za pomocą certyfikatu, który pasuje do jednego z certyfikatów użytych podczas konfigurowania aplikacji w Konsoli Google Play.