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

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

Możliwości serwer-serwer jako:

Rozpowszechnianie aplikacji Indywidualny deweloper
Zarejestruj nazwę pakietu – klucz w imieniu dewelopera, który publikuje aplikację w sklepie. Zarejestruj nazwę pakietu z kluczem zarządzanym przez sklep. potwierdzić własność klucza powiązanego z nazwą pakietu. Zarejestruj nazwę pakietu – klucz w przepływach pracy ciągłego wdrażania. potwierdzić własność klucza powiązanego z nazwą pakietu.

Zanim zaczniesz

Zanim zaczniesz, musisz mieć:

  1. Dostęp administracyjny do projektu Google Cloud.
  2. Podstawowa znajomość:

Powinny być Ci też znane te pojęcia:

Okres obowiązywania 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 identyfikator SHA-256 i bieżący stan rejestracji (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED lub PENDING_TRANSFER).

Rozpocznij

Aby uzyskać dostęp do interfejsu API Konsoli programisty Androida, wykonaj te czynności:

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 projektów 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. Przejdź na 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, co zwykle zajmuje tylko chwilę. Po włączeniu tej funkcji możesz zacząć z niej korzystać.

Uwierzytelnianie interfejsu API

Aby wywoływać interfejs API Konsoli programisty Androida, musisz uwierzytelniać żą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. Dane konta dewelopera są powiązane z kontem Google użytkownika, a nie z projektem Google Cloud, dlatego do uwierzytelniania żądań do 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 interfejsem API Konsoli programisty Androida, aplikacje muszą używać przepływu serwera WWW 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 CI/CD i serwera) Opcja B. Dostęp tymczasowy lub interaktywny
Ta strategia umożliwia działanie zautomatyzowanych procesów (takich jak potoki CI/CD) w tle bez interwencji człowieka:

Jednorazowa konfiguracja zgody użytkownika: podczas początkowej konfiguracji deweloper lub właściciel konta przechodzi jednorazowy proces wyrażania zgody w przeglądarce. Twoja aplikacja żąda dostępu offline (access_type=offline) wraz z zakresem interfejsu API. Google zwraca kod autoryzacji, który aplikacja wymienia na początkowy token dostępu i ważny przez długi czas token odświeżania.

Wykonywanie w tle: bezpiecznie przechowuj refresh_token w środowisku wdrażania lub 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ótkotrwały token dostępu, pomijając wszelkie prośby o ręczne logowanie lub uwierzytelnianie dwuskładnikowe. 		Jeśli nie chcesz przechowywać w swoim środowisku długotrwałych tokenów odświeżania lub jeśli Twoja aplikacja działa w interaktywnym kontekście użytkownika:

Prośba o podanie danych 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 na stronę zgody Google OAuth w przeglądarce.

Dostęp krótkotrwały: użytkownik loguje się i wyraża zgodę, a aplikacja otrzymuje krótkotrwały token dostępu bezpośrednio (lub za pomocą wymiany kodu autoryzacji). Ten token dostępu jest używany do wywoływania interfejsu API i jest odrzucany po wykonaniu. Kolejne 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 go w przypadku nowej czy istniejącej nazwy pakietu na Androidzie.

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 certyfikatu publicznego, 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”, nadal możesz go zarejestrować, ale oprócz potwierdzenia własności deweloper musi też przesłać uzasadnienie użycia nazwy pakietu.

Kluczowe kryteria kwalifikacji

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.

Weryfikowanie własności klucza

Aby dokończyć weryfikację istniejącej nazwy pakietu, interfejs API udostępnia ciąg weryfikacyjny. Ten ciąg weryfikacyjny musi znajdować się 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 rejestrowanemu kluczowi publicznemu.

Uzasadnianie rejestracji klucza

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

Sprawdzone metody zapewniania wygody użytkowników

Zalecamy, aby aplikacje korzystające z interfejsu API Konsoli programisty Androida stosowały te wzorce, aby zapewnić płynną integrację.

Ustal przejrzysty kontekst autoryzacji OAuth

Podanie wyraźnego kontekstu przed poproszeniem o autoryzację OAuth pomaga deweloperom zrozumieć, dlaczego wymagany jest dostęp do konta. Aby skutecznie kierować użytkowników, przed wyświetleniem ekranu zgody OAuth przedstaw jasne wyjaśnienie oczekiwanych funkcji.

Struktura kontekstu autoryzacji powinna mieć ten format:

  • Tytuł: „Połącz swoje konto w Konsoli programisty Androida”
  • Podsumowanie: „Zarządzaj rejestracją nazw pakietów na potrzeby weryfikacji dewelopera aplikacji na Androida w aplikacji [application-name]”
  • Przycisk polecenia: przycisk „Kontynuuj z Google” lub „Zaloguj się przez Google”.
Okno dialogowe ilustrujące kontekst autoryzacji OAuth na potrzeby łączenia konta.
Rysunek 1. Połącz konto w Konsoli programisty Androida.

Zidentyfikuj konta deweloperów

  1. Zintegruj z metodą interfejsu API ListDeveloperAccounts, aby pobierać i wyświetlać listę wszystkich kont dewelopera, do których masz autoryzowany dostęp.
  2. Udostępnij selektor kont, aby deweloper mógł wybrać preferowane konto dewelopera.
  3. Wyraźnie wyróżnij konto displayName, używając numeru rachunku bankowego z pola name jako informacji dodatkowej.
  4. Wyświetlanie stanów weryfikacji konta (verificationState):
    • VERIFIED: potwierdź zweryfikowaną tożsamość dewelopera za pomocą pozytywnego sygnału wizualnego (np. zielonej ikony potwierdzenia).
    • NOT_VERIFIED: poinformuj, że weryfikacja jest niekompletna, i ogranicz rejestrację pakietów na koncie. Opcjonalnie możesz dodać główny przycisk wezwania do działania, który po wybraniu konta przekieruje deweloperów do Konsoli programisty Androida.
Selektor konta z nazwą konta dewelopera i stanem weryfikacji.
Rysunek 2. Selektor konta wyświetlający konta dewelopera i stan weryfikacji.

Jeśli otrzymasz pustą odpowiedź, ponieważ z kontem Google nie są powiązane żadne konta dewelopera, przekieruj deweloperów do Konsoli programisty Androida za pomocą głównego przycisku wezwania do działania.

Zarządzanie nazwami pakietów

  1. Zintegruj z punktem końcowym interfejsu API ListAndroidPackages, aby pobrać wszystkie nazwy pakietów powiązane z kontem dewelopera. Zapewnij deweloperom scentralizowany interfejs, np. listę lub tabelę, aby mogli skutecznie monitorować stany pakietów.
  2. Wyświetlaj packageName obok bieżącego stanu 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 opcjonalnie uwzględnić ją na wyświetlaczu.
Interfejs wyświetlający nazwy zarejestrowanych pakietów i ich stany.
Rysunek 3. Interfejs do zarządzania nazwami pakietów i stanami rejestracji.

Zarządzaj kluczami

  1. Wywołaj punkt końcowy interfejsu API ListAndroidPackageKeys, aby pobrać wszystkie klucze powiązane z nazwą pakietu. Dzięki temu deweloperzy będą mogli wyświetlić uporządkowane zestawienie (np. tabelę lub listę) i sprawdzić stan rejestracji.
  2. Wyświetlaj certificateFingerprintSha256 dla każdego klucza wraz ze stanem rejestracji (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE lub PENDING_TRANSFER), używając różnych wskaźników wizualnych do rozróżniania stanów.
Lista odcisków cyfrowych certyfikatów i stanów rejestracji kluczy.
Rysunek 4. Przegląd kluczy i ich stanów rejestracji.
  1. Umożliwiaj deweloperom rejestrowanie dodatkowych kluczy pod istniejącą nazwą pakietu przez integrację 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 aplikację (np. za pomocą wcześniejszego promptu).
  2. Wywołaj metodę interfejsu API CreateAndroidPackage, aby zarejestrować nazwę pakietu na koncie dewelopera, i wywołaj metodę interfejsu API GetAndroidPackageRegistrationPolicy, aby określić odpowiednie reguły kwalifikowania kluczy.
  3. W zależności od wyznaczonego keySelectionStrategy dla nazwy pakietu poproś dewelopera o wykonanie jednej z tych czynności:
    • Jeśli parametr keySelectionStrategy ma wartość 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 proces wymaga weryfikacji własności klucza (patrz Weryfikacja własności klucza poniżej).
    • Jeśli zasada keySelectionStrategy jest ustawiona na USE_ANY_KEY: poproś dewelopera o bezpośrednie podanie klucza. W tym przypadku nie jest wymagana weryfikacja własności klucza.
  4. Wywołaj metodę interfejsu API CreateAndroidPackageKey, aby powiązać wybrany klucz z nową nazwą pakietu.
Formularz do rejestrowania nazwy pakietu i wybierania klucza podpisywania.
Rysunek 5. Proces rejestrowania nazwy pakietu i wybierania klucza.

Możesz też skonfigurować aplikację tak, aby automatycznie wykrywała i wyodrębniała nazwę pakietu lub klucz bezpośrednio z przesłanej aplikacji.

Weryfikowanie własności klucza

Gdy zasada keySelectionStrategy ma wartość SELECT_KEY_FROM_LIST, deweloperzy muszą potwierdzić własność prywatnego klucza podpisywania. Aby potwierdzić własność, musisz przesłać podpisany plik APK, który zawiera wygenerowany przez interfejs API ciąg verificationToken.

Aby umożliwić weryfikację własności kluczyka, zintegruj metodę interfejsu API VerifyAndroidPackageKeyOwnership i utwórz te komponenty interfejsu:

  • Komponent wyświetlania tokena: wyświetlaj verificationToken w widocznym miejscu w bloku fragmentu kodu, wraz z przydatnym przyciskiem „Kopiuj do schowka”.
  • Instrukcje konfiguracji dla dewelopera: podaj szczegółowe instrukcje, które pomogą deweloperowi umieścić plik adi-registration.properties zawierający verificationToken w folderze zasobów aplikacji.
  • Strefa upuszczania do przesyłania plików APK: udostępnij specjalną strefę upuszczania do przesyłania plików, aby otrzymywać podpisane pliki APK.
Strefa upuszczania i wyświetlanie tokena do weryfikacji własności klucza.
Rysunek 6. UI components for verifying key ownership with signed APK upload.

Uzasadnianie rejestracji klucza

Jeśli pole justificationRequired znanego klucza ma wartość 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 aplikacji zawiera specjalny obszar do wprowadzania tekstu, w którym deweloper może podać uzasadnienie, i poinformuj go, że przed przesłaniem prośby o rejestrację klucza musi podać uzasadnienie. Google sprawdzi przesłane uzasadnienie. Proces zatwierdzania może potrwać do 24 godzin, zanim rejestracja nazwy pakietu zostanie zakończona.

Automatyzacja weryfikacji kluczy zarządzanych

Jeśli Twoja aplikacja zarządza kluczem podpisywania dewelopera, deweloper nie może ręcznie podpisać pakietu APK w celu weryfikacji własności. Zamiast tego musisz automatycznie wywołać interfejs API VerifyAndroidPackageKeyOwnership w ich imieniu.

Dzięki automatycznemu dołączaniu tokena i przesyłaniu pliku APK aplikacja eliminuje te ręczne czynności. Pamiętaj, aby poinformować deweloperów, że weryfikacja własności klucza jest bezproblemowo zarządzana przez Twoją aplikację za pomocą klucza przechowywanego w Twoim systemie.

Przestrzeganie wskazówek dotyczących marki

Aby utrzymać zaufanie użytkowników i zapewnić przejrzystość, wszystkie aplikacje zintegrowane z interfejsem API Konsoli programisty Androida muszą być zgodne z tymi wytycznymi dotyczącymi marki.

Terminologia i użycie wielkich liter

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 musi być określany jako weryfikacja dewelopera aplikacji na Androida. We wszystkich kontekstach używaj dokładnie takiej pisowni i wielkości liter.

Aby uniknąć niejednoznaczności w przypadku plików APK lub AAB, używaj terminu „nazwa pakietu”, a nie tylko „pakiet”.

Opisując proces dodawania nazwy pakietu, używaj sformułowania „zarejestruj nazwę pakietu” zamiast „zgłoś prawa do nazwy pakietu”.

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

Uwierzytelnianie OAuth 2.0 w Konsoli programisty Androida opiera się na usługach tożsamości Google. Aby zachować zgodność ze wskazówkami dotyczącymi marki w Google Identity Services, na przycisku autoryzacji musisz użyć wezwania do działania „Kontynuuj z Google” lub „Zaloguj się przez Google”. Ten tekst jest obowiązkowy i nie można go modyfikować, ponieważ dzięki niemu użytkownicy wiedzą, że używają swoich danych logowania Google, aby autoryzować dostęp aplikacji do ich konta Google.

Utrzymywanie 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 spójność marki:

  • Umiejscowienie i hierarchia logo: używaj tylko oficjalnego, zatwierdzonego logo Konsoli programisty Androida. Logo musi zawsze być drugorzędne w stosunku do głównych elementów marki Twojej aplikacji, aby nie wprowadzać użytkowników w błąd, że aplikacja jest oficjalnym produktem Google.
Oficjalne logo Konsoli programisty Androida. Kliknij, aby zapisać plik.
Rysunek 7. Oficjalne logo Konsoli programisty Androida. Kliknij obraz, aby zapisać plik.
  • Styl wizualny i zniekształcenia: komponent musi być zawsze renderowany z zachowaniem pełnego formatu obrazu. Nie wolno zniekształcać, rozciągać, przekrzywiać, przycinać, odwracać ani modyfikować elementów logo. Nie zmieniaj oficjalnej palety kolorów, nie zamieniaj kolorów pierwszego planu i tła ani nie stosuj cieni, efektów blasku czy dekoracyjnych gradientów.
  • Ograniczenia dotyczące użycia: nie dodawaj żadnych elementów marki należących do Google do zasobów 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ć aktywną integrację.

Dodatkowe materiały