Z tego dokumentu dowiesz się, jak zintegrować osiągnięcia z grą za pomocą Konsoli Google Play lub wywołań interfejsu API. Zawiera on podstawowe elementy i stany osiągnięć oraz opisuje, jak je tworzyć, importować i nimi zarządzać.
Zanim zaczniesz
Zapoznaj się ze wskazówkami dotyczącymi projektowania osiągnięć wysokiej jakości.
Zapoznaj się z terminologią w podstawowych informacjach o osiągnięciach.
Tworzenie i importowanie nowych osiągnięć
Aby zaimplementować osiągnięcia od zera, wykonaj te czynności:
Dodaj osiągnięcia
Istnieją 2 sposoby tworzenia osiągnięć po raz pierwszy w Konsoli Google Play:
- Tworzenie osiągnięcia: dodaj po kolei definicje i metadane dotyczące każdego osiągnięcia.
- Importowanie osiągnięć: w jednym kroku możesz zaimportować definicje i inne metadane dotyczące wielu osiągnięć.
Tworzenie osiągnięcia
Aby utworzyć osiągnięcie dla nowej, nieopublikowanej gry, wykonaj te czynności:
- W Konsoli Google Play wybierz grę.
- Na stronie Usługi gier Play – osiągnięcia (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia) kliknij Utwórz osiągnięcie.
- Na stronie Dodaj osiągnięcia wypełnij formularz.
- Kliknij Zapisz jako wersję roboczą.
- Po utworzeniu osiągnięcia musisz opublikować osiągnięcia.
Importuj osiągnięcia
Aby dodać do gry kilka osiągnięć naraz, wykonaj te czynności:
- Utwórz plik .zip zawierający Twoje osiągnięcia.
- Prześlij plik.
Więcej informacji o pliku ZIP znajdziesz w wytycznych dotyczących plików ZIP.
Aby zaimportować osiągnięcia:
- W Konsoli Google Play wybierz grę.
- Na stronie Usługi gier Play – osiągnięcia (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia) kliknij Importuj osiągnięcia.
- Na stronie Importuj osiągnięcia kliknij Prześlij.
- Wybierz plik ZIP, który chcesz przesłać.
- Kliknij Zapisz jako wersję roboczą.
- Po zaimportowaniu osiągnięć musisz opublikować grę.
Wytyczne dotyczące plików ZIP
W pliku ZIP możesz zaimportować kilka osiągnięć naraz. Dokładne nazwy plików do użycia w pliku ZIP znajdziesz w tabeli:
| Nazwa pliku | Wymagany czy opcjonalny | Akceptowane wartości |
|---|---|---|
AchievementsMetadata.csv
|
Wymagane | Metadane dotyczące każdego osiągnięcia. Zobacz Atrybuty. |
AchievementsLocalizations.csv
|
Opcjonalny | Zawiera tłumaczenia nazw i opisów osiągnięć. |
AchievementsIconMappings.csv
|
Opcjonalny | Mapuje osiągnięcia na pliki ikon. |
| Pliki ikon | Opcjonalne | Ikony w formacie PNG, JPEG lub JPG. |
Wymagania dotyczące pliku ZIP:
- Brak podkatalogów.
- Unikalne nazwy plików.
- Tylko pliki CSV, PNG, JPEG lub JPG.
- Pliki CSV nie mogą zawierać wiersza nagłówka.
- Rozmiar każdego pliku musi być mniejszy niż 1 MB.
- Plik ZIP nie powinien zawierać więcej niż 203 plików.
- Łączny rozmiar pliku ZIP nie może przekraczać 200 MB.
Format pliku AchievementsMetadata.csv
Plik AchievementsMetadata.csv zawiera metadane dotyczące każdego osiągnięcia. Plik powinien zawierać informacje w postaci wartości rozdzielonych przecinkami w tej kolejności:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
Pola są opisane w tej tabeli:
| Nagłówki kolumn CSV | Wymagane czy opcjonalne | Akceptowane wartości |
|---|---|---|
| Nazwa | Wymagane | Może mieć maksymalnie 100 znaków. |
| Opis | Opcjonalne | Może mieć maksymalnie 500 znaków. |
| Wartość przyrostowa | Opcjonalny | True lub False
|
| Wymagane kroki | Wymagane, jeśli pole Incremental Value ma wartość True.
|
Liczba (bez ułamków zwykłych ani dziesiętnych) |
| Stan początkowy | Wymagane | Hidden lub Revealed
|
| Punkty | Wymagane | Liczba, która jest wielokrotnością 5 i mieści się w zakresie od 5 do 200 |
| Kolejność na liście | Opcjonalne | Liczba (bez ułamków zwykłych ani dziesiętnych, większa od 0) |
Wymagania dotyczące pliku AchievementsMetadata.csv:
- Każdy wiersz musi zawierać 7 wartości. Jeśli chcesz pominąć wartość, pozostaw to pole puste.
- Pola
NameiDescriptionsą używane jako język domyślny. - Pole
Namepowinno być unikalne dla wszystkich osiągnięć. - Pola
NameiDescriptionnie powinny zawierać przecinków.
Przykładowy plik AchievementsMetadata.csv:
Achievement1,Achievement One,True,100,Hidden,5,20 Achievement2,Achievement Two,False,,Revealed,10,30
Format pliku AchievementsLocalizations.csv
Plik AchievementsLocalizations.csv to opcjonalny plik, który zawiera wszystkie dane potrzebne do opisania każdego osiągnięcia dla użytkowników korzystających z różnych wersji regionalnych. Osiągnięcia są tłumaczone zgodnie z ustawieniami regionalnymi gry.
Plik powinien zawierać informacje w postaci wartości rozdzielonych przecinkami w tej kolejności:
Name, Localized name, Localized description, locale
Pola są opisane w tej tabeli:
| Nagłówki kolumn CSV | Wymagane czy opcjonalne | Opis | Akceptowane wartości |
|---|---|---|---|
| Nazwa | Wymagane | Musi być zgodna z kolumną Name w pliku AchievementsMetadata.csv.
|
Może mieć maksymalnie 100 znaków. |
| Zlokalizowana nazwa | Wymagane | Zlokalizowana nazwa osiągnięcia. | Może mieć maksymalnie 100 znaków. |
| Zlokalizowany opis | Opcjonalne | Zlokalizowany opis osiągnięcia w określonym języku. | Może mieć maksymalnie 500 znaków. |
| Język | Wymagane | Kod języka, np. en-US.
|
Zanim określisz język, dodaj tłumaczenia gry. Pamiętaj, że nie możesz określić języka domyślnego.
Obsługiwane kody ustawień regionalnych znajdziesz na liście obsługiwanych języków. |
Wymagania dotyczące plików AchievementsLocalizations.csv:
- Nazwy osiągnięć w grze muszą być niepowtarzalne dla danych ustawień regionalnych.
Jeśli na przykład gra obsługuje wersje językowe angielską (en-US) i francuską (fr-FR), osiągnięcie o nazwie „Achievement1” w języku angielskim (en-US) może mieć również nazwę „Achievement1” w języku francuskim (fr-FR).
- Każdy wiersz powinien zawierać 4 wartości. Jeśli chcesz pominąć wartość Zlokalizowany opis, pozostaw to pole puste.
Przykładowy plik AchievementsLocalizations.csv:
Achievement1,Achievement One,This is the description of achievement one in English.,en-US Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR Achievement2,Achievement Two,Description of achievement two.,en-US Achievement2,Logro Dos,Descripción del logro dos.,es-ES Achievement3,Achievement Three,,en-US Achievement3,Erfolg Drei,,de-DE
Format pliku AchievementsIconMappings.csv
Plik AchievementsIconMappings.csv to opcjonalny plik, który służy do mapowania osiągnięć za pomocą danej ikony. Plik powinien zawierać informacje w postaci wartości rozdzielonych przecinkami w tej kolejności:
Name, icon filename
Pola są opisane w tej tabeli:
| Nagłówki kolumn CSV | Wymagane czy opcjonalne | Opis |
|---|---|---|
| Nazwa | Wymagane | Musi być zgodna z kolumną Name w pliku AchievementsMetadata.csv.
|
| Nazwa pliku ikony | Wymagane | Nazwa pliku ikony. |
Wymagania dotyczące plików AchievementsIconMappings.csv:
- Każdy wiersz powinien zawierać 2 wartości.
- Pliki ikon mogą mieć tylko format PNG lub JPEG.
Przykładowy plikAchievementsIconMappings.csv:
Valid Achievement,valid-achievement-icon.png Incremental Achievement,incremental-achievement-icon.jpeg No Description,no-description-icon.png Hidden Initial State,hidden-initial-state-icon.png Large Point Value,large-point-value-icon.jpeg
Wytyczne dotyczące ikon
Ikony powinny mieć wymiary 512 x 512 pikseli i format PNG, JPEG lub JPG. Wystarczy, że prześlesz nam ikonę odblokowanego osiągnięcia. Dla ikony osiągnięcia odkrytego automatycznie wygenerujemy wersję w trybie szarości. Dlatego zalecamy, aby ikony osiągnięć zawierały elementy kolorowe – dzięki temu użytkownicy będą mogli odróżnić osiągnięcia odblokowane od odkrytych.
Gdy ikona osiągnięcia jest wyświetlana w [powiadomieniu][a] na urządzeniu z Androidem, jest nałożona na kółko, a jej zewnętrzne rogi są ukryte. Upewnij się, że w takich warunkach ikona nadal dobrze wygląda.
We wszystkich wersjach językowych używana jest ta sama ikona, dlatego nie zalecamy umieszczania na niej tekstu ani treści zlokalizowanych.
Pliki ikon
Ikony, do których odwołujesz się w pliku AchievementsIconMappings.csv, muszą znajdować się w bieżącym importowanym archiwum ZIP.
Aktualizowanie gier z dotychczasowymi osiągnięciami
W Konsoli Google Play możesz dodawać do gry kolejne osiągnięcia i aktualizować te, które już istnieją.
Dodawanie kolejnych osiągnięć
Jeśli masz już osiągnięcia i chcesz dodać więcej:
- W Konsoli Google Play wybierz grę.
- Na stronie Usługi gier Play – osiągnięcia (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia) kliknij Dodaj osiągnięcia.
Edytowanie osiągnięć
Jeśli masz już osiągnięcia i chcesz je edytować:
- W Konsoli Google Play wybierz grę.
- Na stronie Usługi gier Play – osiągnięcia (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia) wybierz osiągnięcie.
- Możesz edytować dowolne pole.
- Kliknij Zapisz jako wersję roboczą.
- Na stronie Usługi gier Play – osiągnięcia edytowane osiągnięcie ma stan „Dostępne dla testerów”.
- Po przetestowaniu osiągnięcia kliknij Sprawdź i opublikuj.
Spowoduje to ponowne opublikowanie gry wraz ze wszystkimi zaktualizowanymi osiągnięciami.
Usuwanie osiągnięcia
Opublikowanego osiągnięcia nie można usunąć. Osiągnięcie można usunąć tylko w stanie przed opublikowaniem
- Na stronie Usługi gier Play – osiągnięcia wybierz osiągnięcie.
- Aby usunąć osiągnięcie, kliknij Usuń osiągnięcie.
Resetowanie osiągnięcia
Dane o postępach graczy możesz zresetować tylko w przypadku osiągnięć w wersji roboczej.
- Na stronie Usługi gier Play – osiągnięcia wybierz osiągnięcie.
- Aby zresetować osiągnięcia, kliknij Zresetuj postępy.
- Aby zresetować dane osiągnięć w sposób zautomatyzowany, wywołaj metody
Achievementsinterfejsu Management API.
Dodawanie tłumaczeń osiągnięć
Możesz określić własne tłumaczenia osiągnięć powiązanych z Twoją grą. Zanim to zrobisz, wykonaj czynności opisane w sekcji Dodawanie tłumaczeń gry.
Tłumaczenia do gry możesz dodać na 2 sposoby:
Aby przesłać tłumaczenia kilku nowych osiągnięć naraz, możesz użyć opcji importuj osiągnięcia. Nie możesz użyć tej opcji do przesłania tłumaczeń już istniejących osiągnięć.
Możesz dodać tłumaczenia każdego osiągnięcia w grze. Aby dodać własne tłumaczenie każdego osiągnięcia:
- W Konsoli Google Play otwórz kartę Osiągnięcia swojej gry, a następnie wybierz istniejące osiągnięcie.
- Na stronie z informacjami o osiągnięciach wybierz kartę języka, który został wcześniej dodany na karcie Informacje o grze.
- Na stronie z informacjami o osiągnięciu w danym języku wpisz swoje tłumaczenie dotyczące tego osiągnięcia.
- Aby zapisać przetłumaczone informacje o osiągnięciu, kliknij Zapisz.
Implementacje klienta
Aby dowiedzieć się, jak wdrożyć osiągnięcia na swojej platformie, zapoznaj się z tymi materiałami:
Testowanie osiągnięć
Aby sprawdzić, czy osiągnięcia działają zgodnie z oczekiwaniami, wykonaj te czynności:
- Skonfiguruj ścieżkę testu wewnętrznego.
- Dodaj konta testowe do projektu gry dla testerów.
- Utwórz profil w Usługach gier Play na jednym z kont testowych za pomocą aplikacji Gry Play.
- Otwórz grę, używając tego samego konta testowego, dla którego utworzono profil w Usługach gier Play.
- Sprawdź, czy na ekranie wyświetla się „powiadomienie powitalne” Usług gier Play jako potwierdzenie udanego automatycznego uwierzytelniania podczas uruchamiania gry.
- Graj w grę i wykonuj wymagane czynności, aby odblokować osiągnięcia.
Aby zweryfikować osiągnięcia:
Sprawdź, czy po osiągnięciu celu na ekranie wyświetla się wyskakujące okienko „Osiągnięcie odblokowane”.
Otwórz aplikację Sklep Play i sprawdź, czy w sekcji osiągnięć na karcie Ty wyświetlają się osiągnięcia ukończone i w trakcie realizacji (z informacjami o postępach).
Śledzenie skuteczności osiągnięć w Konsoli Play
Aby zobaczyć szybkie statystyki określonych osiągnięć:
- W Konsoli Google Play.
- Kliknij Ustawienia> Projekty gier.
- Wybierz grę.
- W menu po lewej stronie kliknij Osiągnięcia.
- Na stronie Osiągnięcia znajdziesz statystyki, które pomogą Ci sprawdzić, czy gracze odblokowują osiągnięcia. W przypadku osób, które nie ukryły swoich osiągnięć, możesz zobaczyć, jaki odsetek użytkowników je odblokowuje. W przypadku osiągnięć na wczesnym etapie odblokowania odsetek ten jest zwykle bliższy 100%.
Możesz też śledzić wyniki osiągnięć w szeregach czasowych na stronie Rozwój > Usługi gier Play > Statystyki gry.
publikować osiągnięcia,
Po zakończeniu testowania musisz opublikować grę. Wszystkie osiągnięcia w grze zostaną opublikowane razem z nią. Publikowanie osiągnięć jest wymagane, aby działały one prawidłowo.
Aby opublikować, wykonaj te czynności:
- W Konsoli Google Play wybierz grę.
- Na stronie Usługi gier Play – osiągnięcia (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia) kliknij Sprawdź i opublikuj.
- Na stronie Usługi gier Play – publikowanie (Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Publikowanie) sprawdź działania i rozwiąż problemy.
- Kliknij Opublikuj.
Wszystkie osiągnięcia w grze zostaną opublikowane.
Unikanie typowych błędów
Te punkty wskazują typowe błędy, których należy unikać podczas wdrażania osiągnięć w grze. Podkreślają one znaczenie:
W Konsoli Play kliknij Rozwój > Usługi gier Play > Konfiguracja i zarządzanie > Osiągnięcia.
- Przed opublikowaniem sprawdź, czy osiągnięcia skonfigurowane w Konsoli Play nie mają stanu „Wersja robocza”.
- Nie dodawaj do kodu gry wartości identyfikatorów osiągnięć z Konsoli Play. Zamiast tego użyj implementacji klienta.
Upewnij się, że logika odblokowywania została wdrożona również na kliencie.
- Odtwarzacze nie mogą pominąć kroku aktywacji, w którym wywoływany jest interfejs API odblokowywania. Na przykład ukończenie samouczka jest osiągnięciem, ale gracze mogą pominąć sam samouczek.