Ta strona została przetłumaczona przez Cloud Translation API.

Koncepcje na Androida (dla programistów stron internetowych)

Peter Conn

Joyce Toh

Jeśli jesteś programistą stron internetowych i po raz pierwszy korzystasz z Androida i Google Play, pamiętaj o kilku kwestiach. Istnieje już wiele materiałów i dokumentacji na ten temat (dla zespołu Androida), ale tutaj omówimy kilka ważnych kwestii i ich związku z bąbelkami.

Klucz przesyłania a klucz podpisywania

Jeśli zamierzasz użyć dymków do wygenerowania pakietu aplikacji na Androida (AAB) (uwaga: od sierpnia 2021 roku Google Play będzie wymagać, aby wszystkie nowe aplikacje używały formatu Android App Bundle) lub pliku APK do przesyłania i publikowania w Google Play, musisz podpisać aplikację kluczem podpisywania. W Google Play możesz to zrobić na 2 sposoby:

Podpisywanie aplikacji przez Google Play (zdecydowanie zalecane): Google będzie zarządzać kluczem podpisywania Twojej aplikacji i zabezpieczyć go za Ciebie. Służy on do podpisywania plików APK na potrzeby dystrybucji. Podpisywanie aplikacji przez Google Play korzysta z 2 kluczy. „Klucz podpisywania aplikacji”, którym Google będzie zarządzać za Ciebie, oraz „klucz przesyłania”, który przechowujesz i powinien pozostać prywatny. Klucza przesyłania możesz używać do podpisywania aplikacji, którą chcesz przesłać do Konsoli Play. System umożliwia zresetowanie klucza przesyłania w przypadku jego zgubienia lub przejęcia. Aby to zrobić, skontaktuj się z zespołem pomocy Google Play. Obecnie Google Play umożliwia przesyłanie aplikacji w formie pakietu AAB lub pliku APK:
- Android App Bundle (Android App Bundle): przesyłanie pakietu aplikacji na Androida do Konsoli Play powoduje opóźnienie jego tworzenia i generowania w Sklepie Google Play. Gdy użytkownik pobierze i zainstaluje Twoją aplikację, Google Play przekaże mu ją jako podpisany plik APK. Dlatego podpisywanie pakietów APK również musi zostać wykonane przez Google Play. Jeśli więc domyślnie prześlesz do Konsoli Play aplikację w postaci pakietu aplikacji na Androida, będzie ona wymagać korzystania z podpisywania aplikacji przez Google Play.
- APK: w przypadku plików APK możesz włączyć podpisywanie aplikacji przez Google Play. Zdecydowanie zalecamy włączenie podpisywania aplikacji przez Google Play, ponieważ zwiększa to bezpieczeństwo Twojego klucza podpisywania. Jak już wspomnieliśmy, Google Play będzie wkrótce wymagać przesyłania wszystkich nowych aplikacji w formacie AAB, dlatego zalecamy przesyłanie plików APK zamiast przesyłania plików APK.
Zarządzanie własnym kluczem podpisywania: jeśli zdecydujesz się samodzielnie zarządzać swoim kluczem i nie zarejestrujesz się w podpisywaniu aplikacji przez Google Play, ponosisz pełną odpowiedzialność za klucz podpisywania swojej aplikacji. W przeciwieństwie do podpisywania aplikacji przez Google Play, jeśli zgubisz klucz, nie da się go zresetować. Oznacza to, że utrata klucza podpisywania aplikacji oznacza, że stracisz możliwość jej aktualizowania.

Gdy podczas konfiguracji bubblewrap init dojdziesz do sekcji „Informacje o kluczu podpisywania (5/5)”, zobaczysz prośbę o wpisanie wartości „Lokalizacja magazynu kluczy” i „Nazwa klucza” lub użycia wartości domyślnych. Domyślna lokalizacja magazynu kluczy to plik android.keystore w katalogu projektu, a domyślna nazwa klucza to android. Jeśli Bubblewrap nie znajdzie w lokalizacji istniejącego magazynu kluczy o takiej nazwie, utworzy go za Ciebie i poprosi o podanie haseł. Zwróć uwagę na hasła wpisane przez Ciebie, ponieważ będą one potrzebne podczas procesu kompilacji (bubblewrap build), gdzie będzie ona używać klucza do podpisywania aplikacji. Jeśli włączysz podpisywanie aplikacji przez Google Play, klucz podpisywania wygenerowany przez Bubblewrap i użyty do podpisywania aplikacji stanie się „kluczem przesyłania”. Niezależnie od tego, czy zdecydujesz się na użycie wygenerowanego klucza do podpisywania lub przesyłania, pamiętaj o ochronie klucza i utrzymaniu jego prywatności. Nie zalecamy ustawiania w niej kontroli wersji. Zamiast tego ogranicz liczbę osób, które mają do niego dostęp.

Digital Asset Links

Linki do zasobów cyfrowych są niezbędne do zadeklarowania relacji między Twoją witryną a aplikacją na Androida. Aby mieć pewność, że aplikacja na Androida wygenerowana przez Bubblewrap jest prawidłowo zweryfikowana i uruchamiana jako zaufana aktywność w internecie (a nie jako karta niestandardowa w Chrome), musisz dodać odpowiedni klucz do pliku assetlinks.json. Następnie prześlij go do swojej witryny pod adresem .well-known/assetlinks.json (względem katalogu głównego). Plik assetlinks.json powinien mieć ten format:

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

Pobieranie odcisku cyfrowego certyfikatu SHA256

Aby utworzyć plik assetlinks.json, musisz mieć odcisk cyfrowy certyfikatu SHA 256 powiązany z kluczem podpisywania aplikacji. Pamiętaj, że odciski cyfrowe powiązane z kluczami podpisywania i przesyłania będą inne. Pamiętaj o tym rozróżnieniu, zwłaszcza jeśli obserwujesz uruchamianie aplikacji jako kartę niestandardową Chrome (z widocznym paskiem przeglądarki). Prawdopodobnie w pliku assetlinks.json nie ma odcisku palca powiązanego z odpowiednim kluczem.

Dobrze jest umieścić w pliku assetlinks.json odcisk cyfrowy certyfikatu podpisywania i przesyłania, aby ułatwić debugowanie aplikacji lokalnie. Więcej informacji o umieszczeniu obu kluczy w pliku assetlinks.json znajdziesz w sekcji Dodawanie kolejnych kluczy poniżej.

Odcisk można uzyskać na kilka sposobów. Opisaliśmy je w następnych sekcjach. Na każdym z nich trzeba mieć te same odciski palców, więc możesz wybrać najwygodniejszą metodę.

W Konsoli Play

W zależności od tego, czy włączysz podpisywanie aplikacji przez Google Play, możesz mieć 1 lub 2 klucze. Aby pobrać odpowiedni odcisk cyfrowy SHA256 dla każdego klucza:

Otwórz Konsolę Play.
Wybierz aplikację, która Cię interesuje
W menu nawigacyjnym po lewej stronie w sekcji Wersja kliknij Konfiguracja -> Integralność aplikacji.
Skopiuj SHA256 odpowiedniego klucza:

Pobierz odpowiedni odcisk cyfrowy certyfikatu SHA256 na potrzeby klucza podpisywania lub klucza przesyłania

Klucz podpisywania: skopiuj odcisk cyfrowy SHA256 z pola „Certyfikat klucza podpisywania aplikacji”. Odcisk cyfrowy będzie odpowiadać Twojej aplikacji pobranej ze Sklepu Google Play, ponieważ Google Play rozpowszechnia aplikację podpisaną kluczem podpisywania.
Klucz przesyłania: skopiuj odcisk cyfrowy SHA256 z pola „Prześlij certyfikat klucza”. Odcisk będzie odpowiadać aplikacji, jeśli zainstalujesz ją lokalnie (np. przez ADB przez USB). Ten plik APK (na komputerze lokalnym) został utworzony przez Bubblewrap, a następnie został podpisany kluczem, który dla Ciebie utworzył (podczas konfiguracji init). Pamiętaj, że może to być klucz podpisywania Twojej lokalnej aplikacji, ale w rzeczywistości staje się on „kluczem przesyłania” po opublikowaniu aplikacji w Google Play.

przez `keytool`

keytool to narzędzie do zarządzania kluczami i certyfikatami. Za pomocą narzędzia keytool możesz wyodrębnić odcisk cyfrowy SHA 256 powiązany z wygenerowanym plikiem APK lub dymkiem AAB. Pamiętaj, że ten odcisk cyfrowy służy do lokalnego klucza podpisywania. Jeśli prześlesz aplikację do Google Play i włączysz podpisywanie aplikacji przez Google Play, stanie się on „kluczem przesyłania”.

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

Za pomocą narzędzia do łączenia zasobów

Innym sposobem na uzyskanie prawidłowego pliku Digital Asset Links dla Twojej aplikacji jest użycie narzędzia Asset Link Tool:

Zainstaluj narzędzie Asset Link Tool ze Sklepu Play.
Na tym samym urządzeniu pobierz aplikację ze Sklepu Google Play lub zainstaluj ją lokalnie.
Otwórz aplikację Asset Link Tool. Zobaczysz listę wszystkich aplikacji zainstalowanych na urządzeniu, uporządkowaną według nazwy pakietu. Przefiltruj listę według identyfikatora aplikacji wybranego wcześniej podczas bubblewrap init i kliknij ten wpis.
Wyświetli się strona z podpisem aplikacji i wygenerowanym linkiem Digital Asset Link. Kliknij przycisk Kopiuj lub Udostępnij u dołu, aby wyeksportować plik w dowolny sposób (np. zapisać go w Google Keep albo wysłać do siebie e-mailem).

Obowiązują te same zasady co wcześniej w przypadku kluczy podpisywania lub przesyłania. Jeśli aplikacja została zainstalowana ze Sklepu Google Play, narzędzie Asset Link pobierze odcisk cyfrowy klucza podpisywania aplikacji. Jeśli aplikacja została zainstalowana bezpośrednio z komputera lokalnego, odcisk cyfrowy służy do klucza wygenerowanego Bubblewrap.

Dopilnuj, aby plik z linkami do komponentów był dostępny

Po przesłaniu pliku sprawdź, czy możesz otworzyć go w przeglądarce. Sprawdź, czy adres https://example.com/.well-known/assetlinks.json odpowiada przesłanemu plikowi.

Witryny w stylu Jekyll

Jeśli witryna jest generowana przez Jekyll (np. strony GitHub), musisz dodać wiersz konfiguracji, aby katalog .well-known został uwzględniony w danych wyjściowych. Więcej informacji na ten temat znajdziesz w Centrum pomocy GitHuba. Utwórz plik o nazwie _config.yml w katalogu głównym witryny (lub dodaj go, jeśli już istnieje) i wpisz:

# Folders with dotfiles are ignored by default.
include: [.well-known]

Dodawanie kolejnych kluczy

Plik Digital Asset Link może zawierać więcej niż jedną aplikację oraz dla każdej z nich więcej niż jeden klucz. Aby na przykład dodać drugi klucz, zidentyfikuj go za pomocą narzędzia Asset Link, a następnie dodaj go jako drugi wpis. Kod w Chrome, który analizuje ten plik JSON, jest dość rygorystyczny, dlatego uważaj, by przypadkiem nie dodać dodatkowego przecinka na końcu listy.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

Rozwiązywanie problemów

Chrome rejestruje przyczynę niepowodzenia weryfikacji Digital Asset Links. Dzienniki możesz wyświetlić na urządzeniu z Androidem za pomocą adb logcat. Jeśli programujesz w systemie Linux lub Mac, możesz przejrzeć odpowiednie dzienniki z połączonego urządzenia:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

Jeśli np. widzisz komunikat Statement failure matching fingerprint., za pomocą narzędzia Asset Link możesz sprawdzić podpis aplikacji i sprawdzić, czy jest on zgodny z tym w pliku assetlinks.json.