Rejestrowanie nazw pakietów za pomocą interfejsu API Konsoli programisty Androida

Android Developer Console API to publiczny interfejs, który umożliwia dystrybutorom aplikacji i indywidualnym deweloperom programowe rejestrowanie nazw pakietów w Konsoli programisty Androida.

Możliwości międzyserwerowe jako:

Dystrybutor aplikacji	Indywidualny deweloper
Rejestrowanie nazwy pakietu – klucz w imieniu dewelopera, który publikuje aplikację w sklepie. Rejestrowanie nazwy pakietu za pomocą klucza zarządzanego przez sklep. Potwierdzanie własności klucza powiązanego z nazwą pakietu.	Rejestrowanie nazwy pakietu – klucz w przepływach pracy ciągłego wdrażania. Potwierdzanie własności klucza powiązanego z nazwą pakietu.

Zanim zaczniesz

Zanim zaczniesz, musisz mieć:

1. dostęp administracyjny do projektu Google Cloud;
2. podstawową wiedzę na temat:
   • interfejsów API typu REST,
   • struktury pliku APK,
   • podpisywania aplikacji na Androida,
   • generowania funkcji skrótu SHA-256.

Powinieneś też znać te terminy:

Termin	Definicja
Konto dewelopera	Reprezentuje konto w Konsoli programisty Androida, które może być właścicielem co najmniej 1 nazwy pakietu. Zawiera stan weryfikacji (NOT_VERIFIED lub VERIFIED).
Nazwa pakietu	Konkretna nazwa pakietu na Androida (np. com.example.app) na koncie dewelopera, która może być powiązana z co najmniej 1 kluczem. Zawiera stan rejestracji (DRAFT, IN_REVIEW, REGISTERED lub PENDING_TRANSFER).
Klucz	Konkretny certyfikat publiczny lub klucz używany do podpisywania nazwy pakietu na Androida. Zawiera funkcję skrótu SHA-256 i bieżący stan rejestracji (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED lub PENDING_TRANSFER).

Rozpocznij

Aby uzyskać dostęp do Konsoli programisty Androida API:

Tworzenie projektu Google Cloud

1. Utwórz konto Google Cloud, jeśli jeszcze go nie masz.
2. Otwórz konsolę Google Cloud.
3. Utwórz projekt Google Cloud.

Włączanie interfejsu API w projekcie Google Cloud

1. Otwórz konsolę Google Cloud.
2. W menu nawigacyjnym (☰) wybierz Interfejsy API i usługi > Biblioteka.
3. W menu projektu wybierz projekt Google Cloud, w którym chcesz włączyć interfejs API.
4. Użyj paska wyszukiwania Interfejsy API i usługi , aby wybrać Konsola programisty Androida API.
5. Włącz interfejs API:
   1. Otwórz stronę przeglądu interfejsu API, wybierając go w wynikach wyszukiwania.
   2. Kliknij niebieski przycisk Włącz. Google Cloud aktywuje interfejs API w wybranym projekcie. Zwykle trwa to tylko chwilę. Po włączeniu możesz zacząć go używać.

Uwierzytelnianie interfejsu API

Aby wywoływać Android Developer Console API, musisz uwierzytelnić żądania za pomocą protokołu OAuth 2.0.

Uwierzytelnianie za pomocą protokołu OAuth 2.0

Interfejs API Konsoli programisty Androida wymaga uwierzytelniania OAuth 2.0, aby autoryzować dostęp do zasobów konta dewelopera i nazw pakietów. Ponieważ dane na koncie dewelopera są powiązane z kontem Google użytkownika, a nie z projektem Google Cloud, do uwierzytelniania żądań interfejsu API nie można używać kont usługi, federacji tożsamości zadań ani kluczy interfejsu API.

Zakres protokołu OAuth 2.0

W przypadku wszystkich operacji wymagany jest ten zakres:

Zakres protokołu OAuth 2.0	Opis
https://www.googleapis.com/auth/androiddeveloperconsole	Wyświetlanie nazw pakietów i danych na kontach w Konsoli programisty Androida oraz zarządzanie nimi

Implementowanie przepływu serwera WWW OAuth 2.0

Aby zintegrować się z Konsolą programisty Androida API, aplikacje muszą używać przepływu serwera WWW protokołu OAuth 2.0. W zależności od typu aplikacji i potrzeb związanych z automatyzacją możesz wybrać jedną z 2 głównych strategii zarządzania danymi logowania:

Opcja A (zalecana): dostęp offline / automatyczny (integracja z CI/CD i serwerem)

Opcja B: dostęp tymczasowy / interaktywny

Ta strategia umożliwia automatycznym procesom (np. potokom CI/CD) działanie w tle bez interwencji człowieka: Jednorazowa konfiguracja zgody użytkownika: podczas wstępnej konfiguracji deweloper lub właściciel konta wykonuje jednorazowy przepływ zgody w przeglądarce. Twoja aplikacja prosi o dostęp offline (access_type=offline) wraz z zakresem interfejsu API. Google zwraca kod autoryzacji, który Twoja aplikacja wymienia na początkowy token dostępu i długoterminowy token odświeżania. Działanie w tle: bezpiecznie przechowuj refresh_token w środowisku wdrożenia lub w menedżerze obiektów tajnych (np. GitHub Actions Secrets, Google Secret Manager). W przypadku kolejnych wywołań interfejsu API zautomatyzowany przepływ pracy używa zapisanego tokena odświeżania, aby na żądanie uzyskać nowy, krótkoterminowy token dostępu, pomijając ręczne logowanie lub prośby o uwierzytelnianie dwuskładnikowe.

Jeśli wolisz unikać przechowywania długoterminowych tokenów odświeżania w swoim środowisku lub jeśli Twoja aplikacja działa w kontekście interaktywnym użytkownika: Prośba o zgodę podczas wykonywania: nie proś o dostęp offline ani nie przechowuj tokena odświeżania. Za każdym razem, gdy narzędzie lub aplikacja jest uruchamiana, poproś użytkownika o uwierzytelnienie, przekierowując go do strony zgody Google OAuth w przeglądarce. Krótkoterminowy dostęp: użytkownik loguje się i wyraża zgodę, a aplikacja otrzymuje bezpośrednio krótkoterminowy token dostępu (lub za pomocą wymiany kodu autoryzacji). Ten token dostępu jest używany do wywoływania interfejsu API i jest odrzucany po wykonaniu. Przyszłe uruchomienia wymagają ponownego uwierzytelnienia użytkownika.

Rejestrowanie nazwy pakietu

Rejestracja nazwy pakietu to proces powiązania klucza z nazwą pakietu. Sposób rejestracji klucza zależy od tego, czy rejestrujesz klucz do nowej czy istniejącej nazwy pakietu na Androida.

Rejestrowanie nowej nazwy pakietu

W przypadku nowej nazwy pakietu, która nigdy nie była używana na Androidzie, możesz podać certyfikat klucza publicznego z pary kluczy podpisywania aplikacji.

Rejestrowanie istniejącej nazwy pakietu

Aby zarejestrować istniejącą nazwę pakietu, musisz udowodnić, że masz prawo własności do znanego prywatnego klucza podpisywania. W przeciwieństwie do nowej rejestracji interfejs API zwraca listę znanych odcisków cyfrowych certyfikatów publicznych, które kwalifikują się do rejestracji. Tych kluczy można używać do bezpośredniej rejestracji.

Jeśli klucz, który rejestrujesz, jest oznaczony jako „wymaga uzasadnienia”, możesz go zarejestrować, ale oprócz potwierdzenia własności deweloper musi też przesłać uzasadnienie użycia nazwy pakietu.

Reguły dotyczące kwalifikowania się kluczy

Lista kwalifikujących się kluczy jest określana przez reguły dotyczące kwalifikowania się nazw pakietów. Reguły te mają na celu ograniczenie udostępniania nazw pakietów i zostały wprowadzone w ramach weryfikacji deweloperów aplikacji na Androida.

W sytuacjach, gdy nazwa pakietu jest używana przez kilku deweloperów lub ma kilka kluczy podpisywania, kryteria kwalifikacji określa się w ten sposób:

Scenariusz	Reguła dotycząca rejestracji bezpośredniej	Reguła dla innych deweloperów
Większościowy posiadacz klucza	Priorytet ma klucz, który odpowiada za ponad 50% wszystkich znanych instalacji.	Wszyscy pozostali deweloperzy muszą podać uzasadnienie.
50 i więcej instalacji	Jeśli żaden klucz nie ma ponad 50% instalacji, kwalifikują się wszystkie klucze z co najmniej 50 instalacjami.	Deweloperzy, których klucze mają mniej niż 50 instalacji, muszą podać uzasadnienie.
Mniej niż 50 instalacji	Jeśli żaden klucz nie osiągnie progu 50 instalacji, każdy klucz może być używany w kolejności zgłoszeń.	Gdy jeden deweloper się zarejestruje, pozostali muszą podać uzasadnienie.

Potwierdzanie własności klucza

Aby dokończyć weryfikację istniejącej nazwy pakietu, interfejs API udostępnia ciąg weryfikacyjny. Ten ciąg weryfikacyjny musi być umieszczony w nowym pliku o nazwie adi-registration.properties w folderze zasobów aplikacji. Następnie musisz podpisać i przesłać plik APK za pomocą klucza prywatnego odpowiadającego kluczowi publicznemu, który rejestrujesz.

Uzasadnianie rejestracji klucza

Jeśli rejestracja klucza wymaga uzasadnienia, deweloperzy muszą przesłać szczegółowe uzasadnienie biznesowe. Google sprawdza to uzasadnienie, a zatwierdzenie rejestracji nazwy pakietu może potrwać do 24 godzin.

Sprawdzone metody zapewniania wygody użytkowników

Aby zapewnić bezproblemową integrację, zalecamy, aby aplikacje korzystające z Android Developer Console API stosowały te wzorce.

Określanie jasnego kontekstu autoryzacji OAuth

Podanie wyraźnego kontekstu przed poproszeniem o autoryzację OAuth pomaga deweloperom zrozumieć, dlaczego wymagany jest dostęp do konta. Aby skutecznie prowadzić użytkowników, przed uruchomieniem ekranu zgody OAuth przedstaw wyraźne wyjaśnienie oczekiwanej funkcjonalności.

Ustrukturyzuj kontekst autoryzacji w tym formacie:

• Tytuł: „Połącz konto w Konsoli programisty Androida”
• Podsumowanie: „Zarządzaj rejestracją nazw pakietów na potrzeby weryfikacji dewelopera aplikacji na Androida w [nazwa-aplikacji]”
• Przycisk działania: „Dalej z Google” lub „Zaloguj się przez Google”

Identyfikowanie kont deweloperów

1. Zintegruj się z metodą interfejsu API ListDeveloperAccounts, aby pobrać i wyświetlić listę wszystkich kont deweloperów, do których dostęp został autoryzowany.
2. Udostępnij selektor kont, aby deweloper mógł wybrać preferowane konto dewelopera.
3. Wyświetlaj nazwę konta displayName, używając numeru rachunku bankowego z pola name jako informacji dodatkowej.
4. Wyświetlaj stany weryfikacji konta (verificationState):
   • VERIFIED: potwierdź zweryfikowaną tożsamość dewelopera za pomocą pozytywnego sygnału wizualnego (np. zielonego znacznika wyboru).
   • NOT_VERIFIED: wskaż, że weryfikacja jest niepełna, i ogranicz rejestrację pakietów na koncie. Opcjonalnie możesz dodać główny przycisk CTA, który po wybraniu konta przekierowuje deweloperów do Konsoli programisty Androida.

Jeśli otrzymasz pustą odpowiedź, ponieważ z kontem Google nie są powiązane żadne konta deweloperów, poproś deweloperów o przejście do Konsoli programisty Androida za pomocą głównego przycisku CTA.

Zarządzanie nazwami pakietów

1. Zintegruj się z punktem końcowym interfejsu API ListAndroidPackages, aby pobrać wszystkie nazwy pakietów powiązane z kontem dewelopera. Udostępnij deweloperom scentralizowany interfejs, np. listę lub tabelę, aby mogli skutecznie monitorować stany pakietów.
2. Wyświetlaj packageName wraz z bieżącym stanem rejestracji (DRAFT, IN_REVIEW, REGISTERED lub PENDING_TRANSFER), stosując różne wskaźniki wizualne dla każdego stanu. Jeśli podczas tworzenia podano i zapisano „przyjazną nazwę”, możesz ją opcjonalnie uwzględnić w wyświetlaniu.

Zarządzanie kluczami

1. Wywołaj punkt końcowy interfejsu API ListAndroidPackageKeys, aby pobrać wszystkie klucze powiązane z nazwą pakietu, i udostępnij deweloperom uporządkowany przegląd (np. tabelę lub listę), aby mogli monitorować stan rejestracji.
2. Wyświetlaj certificateFingerprintSha256 dla każdego klucza wraz z jego stanem rejestracji (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE lub PENDING_TRANSFER), stosując różne wskaźniki wizualne, aby odróżnić stany.

1. Umożliw deweloperom rejestrowanie dodatkowych kluczy pod istniejącą nazwą pakietu, integrując się z metodą interfejsu API CreateAndroidPackageKey.

Rejestrowanie nazwy pakietu

1. Użyj układu opartego na formularzu, w którym deweloperzy wpisują nazwę pakietu w polu tekstowym, pod warunkiem że te informacje nie zostały już zebrane przez Twoją aplikację (np. za pomocą wcześniejszego monitu).
2. Wywołaj metodę interfejsu API CreateAndroidPackage, aby zarejestrować nazwę pakietu na koncie dewelopera, i wywołaj metodę interfejsu API GetAndroidPackageRegistrationPolicy , aby określić obowiązujące reguły dotyczące kwalifikowania się kluczy.
3. W zależności od wyznaczonej keySelectionStrategy dla nazwy pakietu poproś dewelopera o wykonanie jednej z tych czynności:
   • Jeśli keySelectionStrategy jest ustawiona na SELECT_KEY_FROM_LIST: poproś dewelopera o wybranie klucza do rejestracji z podanej listy knownKeys (zawierającej odciski cyfrowe certyfikatów SHA-256), np. za pomocą przycisków opcji. Ten przepływ wymaga potwierdzenia własności klucza (patrz Potwierdzanie własności klucza poniżej).
   • Jeśli keySelectionStrategy jest ustawiona na USE_ANY_KEY: poproś dewelopera o bezpośrednie podanie klucza. W tym przypadku nie jest wymagane potwierdzenie własności klucza.
4. Wywołaj metodę interfejsu API CreateAndroidPackageKey, aby powiązać wybrany klucz z nową nazwą pakietu.

Opcjonalnie Twoja aplikacja może automatycznie wykrywać i wyodrębniać nazwę pakietu lub klucz bezpośrednio z przesłanej aplikacji.

Potwierdzanie własności klucza

Gdy keySelectionStrategy jest ustawiona na SELECT_KEY_FROM_LIST, deweloperzy muszą udowodnić, że mają prawo własności do prywatnego klucza podpisywania. Potwierdzenie własności wymaga przesłania podpisanego pliku APK, który zawiera wygenerowany przez interfejs API verificationToken.

Aby obsługiwać potwierdzanie własności klucza, zintegruj metodę interfejsu API VerifyAndroidPackageKeyOwnership i utwórz te komponenty interfejsu użytkownika:

• Komponent wyświetlania tokena: wyświetlaj verificationToken w widocznym miejscu w bloku fragmentu kodu, w tym wygodny przycisk „Kopiuj do schowka”.
• Instrukcje konfiguracji dla dewelopera: podaj szczegółowe instrukcje, jak umieścić plik adi-registration.properties zawierający verificationToken w folderze zasobów aplikacji.
• Strefa upuszczania do przesyłania pliku APK: udostępnij specjalną strefę upuszczania plików do przesyłania podpisanego pliku APK.

Uzasadnianie rejestracji klucza

Gdy w przypadku znanego klucza pole justificationRequired jest ustawione na REQUIRED, zarejestrowanie tego klucza wraz z nazwą pakietu wymaga od deweloperów przesłania szczegółowego uzasadnienia biznesowego.

Prześlij to uzasadnienie, wywołując metodę interfejsu API JustifyAndroidPackageKeyRegistration. Upewnij się, że interfejs użytkownika Twojej aplikacji zawiera specjalny obszar wprowadzania tekstu, w którym deweloper może podać uzasadnienie, i poinformuj go, że przed przesłaniem prośby o rejestrację klucza wymagane jest podanie uzasadnienia. Google sprawdza przesłane uzasadnienie. Zatwierdzenie może potrwać do 24 godzin, zanim rejestracja nazwy pakietu zostanie zakończona.

Automatyzowanie weryfikacji kluczy zarządzanych

Jeśli Twoja aplikacja zarządza kluczem podpisywania dewelopera, deweloper nie może ręcznie podpisać pliku APK na potrzeby potwierdzenia własności. Zamiast tego musisz automatycznie wykonać VerifyAndroidPackageKeyOwnership wywołanie interfejsu API w ich imieniu.

Dzięki automatycznemu obsłudze procesu dodawania tokena i przesyłania pliku APK Twoja aplikacja eliminuje te ręczne czynności. Poinformuj deweloperów, że potwierdzanie własności klucza jest bezproblemowo zarządzane przez Twoją aplikację za pomocą klucza przechowywanego w Twoim systemie.

Przestrzeganie wskazówek dotyczących marki

Aby zachować zaufanie użytkowników i zapewnić przejrzystość, wszystkie aplikacje integrujące się z API Konsoli programisty Androida muszą przestrzegać tych wskazówek dotyczących marki.

Terminologia i użycie wielkich liter

Gdy odwołujesz się do usługi w materiałach lub dokumentacji dla użytkowników, zawsze używaj pełnej nazwy Konsola programisty Androida. Nie używaj skrótu „ADC”.

Program należy określać jako weryfikacja dewelopera aplikacji na Androida. We wszystkich kontekstach używaj dokładnie takiej samej pisowni i użycia wielkich liter.

Aby uniknąć niejasności związanych z plikami APK lub AAB, używaj terminu „nazwa pakietu”, a nie tylko „pakiet”.

Opisując proces dodawania nazwy pakietu, używaj wyrażenia „zarejestruj nazwę pakietu” zamiast „zastrzeż nazwę pakietu”.

Używanie wezwania do działania „Zaloguj się”

Uwierzytelnianie OAuth 2.0 w Konsoli programisty Androida opiera się na usługach Google Identity Services. Aby zachować zgodność ze wskazówkami dotyczącymi marki usług Google Identity Services, musisz użyć wezwania do działania „Dalej z Google” lub „Zaloguj się przez Google” na przycisku autoryzacji. Ten tekst jest obowiązkowy i nie można go modyfikować, ponieważ zapewnia, że użytkownicy rozumieją, że używają swoich danych logowania Google, aby autoryzować Twoją aplikację do uzyskiwania dostępu do ich konta Google.

Zachowanie tożsamości i integralności marki

Podczas integrowania logo Konsoli programisty Androida z interfejsem aplikacji musisz przestrzegać tych specyfikacji, aby zachować tożsamość wizualną i integralność marki:

• Umiejscowienie i hierarchia logo: używaj tylko oficjalnego, zatwierdzonego logo Konsoli programisty Androida. Logo musi zawsze pozostawać drugorzędne w stosunku do głównych elementów marki Twojej aplikacji, aby nie sugerować, że aplikacja jest oficjalną usługą Google.

• Styl wizualny i zniekształcenia: zasób musi być zawsze renderowany z zachowaniem proporcji. Nie wolno zniekształcać, rozciągać, przekrzywiać, przycinać, odwracać ani modyfikować komponentów logo. Nie zmieniaj oficjalnej palety kolorów, nie zamieniaj kolorów pierwszego planu ani tła, nie stosuj cieni, efektów poświaty ani dekoracyjnych gradientów.
• Ograniczenia dotyczące użycia: nie używaj żadnych elementów marki należących do Google w zasobach własnej aplikacji. Zasób logo Konsoli programisty Androida może być używany tylko w kontekście układu aplikacji, aby wyraźnie wskazywać na aktywną integrację.

Dodatkowe materiały

• Sprawdzanie stanu rejestracji aplikacji za pomocą Android Developer ID Status API
• Rejestracja w Konsoli programisty Androida
• Rejestracja w Konsoli Google Play
• Podpisywanie aplikacji