Jeśli jesteś deweloperem stron internetowych i nie znasz jeszcze Androida ani Google Play, zapoznaj się z kilkoma ważnymi informacjami. W tej kwestii istnieje już wiele materiałów i dokumentacji (dzięki zespołowi Androida), ale tutaj omówimy kilka ważnych pojęć i ich zastosowanie w Bubblewrap.
Klucz przesyłania a klucz podpisywania
Jeśli planujesz użyć Bubblewrap do wygenerowania pakietu aplikacji na Androida (AAB) (uwaga: od sierpnia 2021 r. Google Play będzie wymagać, aby wszystkie nowe aplikacje były w formacie Android App Bundle) lub pliku APK, który można przesłać i opublikować w Google Play, musisz podpisać aplikację kluczem podpisywania. Google Play oferuje 2 opcje:
- Podpisywanie aplikacji przez Google Play (zalecane): Google będzie zarządzać kluczem podpisywania Twojej aplikacji i dbać o jego ochronę. Służy on do podpisywania plików APK na potrzeby dystrybucji. Podpisywanie aplikacji przez Google Play używa 2 kluczy. „Klucz podpisywania aplikacji”, którym zarządza Google, oraz „klucz przesyłania”, który należy do Ciebie i powinien pozostać prywatny. Klucza przesyłania używasz do podpisywania aplikacji przed przesłaniem jej do Konsoli Play. Ten system umożliwia zresetowanie klucza przesyłania, jeśli utracisz go lub ktoś go przejmie. Aby to zrobić, skontaktuj się z zespołem pomocy Google Play. Obecnie w Google Play możesz przesłać aplikację jako pakiet aplikacji na Androida lub plik APK:
- Pakiet aplikacji na Androida (AAB): gdy prześlesz pakiet AAB do Konsoli Play, tworzenie i generowanie plików APK zostanie przeniesione do Sklepu Google Play. Gdy użytkownik pobierze i zainstaluje aplikację, Google Play rozpowszechni ją w postaci podpisanego pliku APK. Dlatego Google Play musi też podpisać pliki APK. Jeśli więc dodasz do Konsoli Play aplikację w formie AAB, będziesz musiał(-a) użyć usługi podpisywania aplikacji w Google Play.
- Plik APK: w przypadku plików APK możesz włączyć podpisywanie aplikacji przez Google Play. Zalecamy korzystanie z podpisywania aplikacji przez Google Play, ponieważ zwiększa to bezpieczeństwo klucza podpisywania. Jak już wspomnieliśmy, wkrótce w Google Play będzie wymagane przesyłanie wszystkich nowych aplikacji w formacie AAB, dlatego zalecamy przesyłanie plików AAB zamiast plików APK.
- Zarządzanie własnym kluczem podpisywania: jeśli zdecydujesz się zarządzać własnym kluczem i nie włączysz podpisywania aplikacji przez Google Play, ponosisz pełną odpowiedzialność za klucz podpisywania aplikacji. W odróżnieniu od podpisywania aplikacji przez Google Play nie można go zresetować, jeśli go zgubisz. W związku z tym utrata klucza podpisywania aplikacji spowoduje też utratę możliwości jej aktualizowania.
Podczas konfigurowania bubblewrap init, gdy dojdziesz do sekcji „Informacje o kluczu podpisującym (5 z 5)”, pojawi się prośba o podanie „lokalizacji magazynu kluczy” i „nazwy klucza” lub użycie domyślnych wartości. 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 danej lokalizacji istniejącego magazynu kluczy o podanej nazwie, utworzy nowy magazyn kluczy i poprosi o hasła. Zanotuj hasła, które wpiszesz, ponieważ będziesz ich potrzebować podczas procesu kompilacji (bubblewrap build), w którym klucz zostanie użyty do podpisania aplikacji. Jeśli zdecydujesz się na korzystanie z podpisywania aplikacji przez Google Play, klucz podpisywania wygenerowany przez Bubblewrap i użyty do podpisania aplikacji stanie się „kluczem przesyłania”. Niezależnie od tego, czy zdecydujesz się użyć wygenerowanego przez Bubblewrap klucza jako klucza podpisywania czy klucza przesyłania, musisz chronić ten klucz i utrzymywać go w prywatności.
Nie zalecamy ich akceptowania w ramach kontroli wersji. Zamiast tego ogranicz liczbę osób, które mają do niego dostęp.
Digital Asset Links
Linki do zasobów cyfrowych są potrzebne do zadeklarowania związku między Twoją witryną a aplikacją na Androida. Aby mieć pewność, że aplikacja na Androida wygenerowana przez Bubblewrap zostanie prawidłowo zweryfikowana i uruchomiona jako zaufana aktywność w przeglądarce (zamiast karty niestandardowej Chrome), musisz dodać odpowiedni klucz do pliku assetlinks.json. Następnie prześlij go do swojej witryny pod adresem .well-known/assetlinks.json(w stosunku do katalogu głównego). Plik assetlinks.json powinien mieć 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 palców powiązane z kluczami podpisywania i przesyłania będą się różnić. Pamiętaj o tym, zwłaszcza jeśli widzisz, że aplikacja uruchamia się jako karta niestandardowa Chrome (z widocznym paskiem przeglądarki). W takim przypadku prawdopodobnie plik assetlinks.json nie ma odcisku palca odpowiadającego odpowiedniemu kluczowi.
Warto mieć w pliku assetlinks.json odciski cyfrowe certyfikatu podpisującego i certyfikatu przesyłania, aby łatwiej debugować aplikację lokalnie. Aby dowiedzieć się, jak umieścić oba klucze w pliku assetlinks.json, zapoznaj się z sekcją Dodawanie kolejnych kluczy.
W następnych sekcjach znajdziesz kilka sposobów na uzyskanie odcisku palca. Wszystkie te metody powinny dawać ten sam wynik, więc wybierz tę, która jest dla Ciebie najwygodniejsza.
Za pomocą Konsoli Play
W zależności od tego, czy korzystasz z podpisywania aplikacji przez Google Play, możesz mieć 1 lub 2 klucze. Aby pobrać odpowiedni odcisk cyfrowy SHA-256 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 dla odpowiedniego klucza:
Klucz podpisywania: skopiuj odcisk cyfrowy SHA-256 dla „Certyfikat klucza podpisywania aplikacji”. Ten odcisk palca będzie odpowiadał Twojej aplikacji, jeśli pobierzesz ją ze Sklepu Google Play, ponieważ Google Play rozpowszechnia Twoją aplikację podpisaną kluczem podpisywania.
Klucz przesyłania: skopiuj odcisk cyfrowy SHA-256 dla „Certyfikat klucza przesyłania”. Ten odcisk palca będzie odpowiadał Twojej aplikacji, jeśli zainstalujesz ją lokalnie (np. przez ADB przez USB). Ten pakiet APK (na komputerze lokalnym) został utworzony przez Bubblewrap, a dlatego jest podpisany kluczem, który został utworzony dla Ciebie (podczas konfiguracji
init). Pamiętaj, że może to być klucz podpisywania zainstalowanej lokalnie aplikacji, ale po opublikowaniu aplikacji w Google Play stanie się on „kluczem przesyłania”.
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 APK-iem lub AAB Bubblewrap. Pamiętaj, że ten odcisk palca dotyczy lokalnego klucza podpisywania. Jeśli prześlesz aplikację do Google Play i włączysz podpisywanie aplikacji przez Google Play, ten klucz stanie się „kluczem przesyłania”.
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
Za pomocą narzędzia do łączenia komponentów
Innym sposobem uzyskania odpowiedniego pliku Digital Asset Links dla aplikacji jest użycie narzędzia do łączenia zasobów:
- Zainstaluj narzędzie Asset Link ze Sklepu Play.
- Na tym samym urządzeniu pobierz aplikację ze Sklepu Google Play lub zainstaluj ją lokalnie.
- Otwórz aplikację Asset Link Tool, aby wyświetlić listę wszystkich aplikacji zainstalowanych na urządzeniu według nazwy pakietu. Przefiltruj listę według identyfikatora aplikacji wybranego wcześniej podczas
bubblewrap initi kliknij ten wpis. - Zobaczysz stronę z podpisem aplikacji i wygenerowanym linkiem Digital Asset Link. Kliknij przyciski Kopiuj lub Udostępnij u dołu, aby wyeksportować listę w dowolny sposób (np. zapisać w Google Keep lub wysłać do siebie e-mailem).
To samo dotyczy kluczy podpisywania i kluczy przesyłania. Jeśli aplikacja została zainstalowana ze Sklepu Google Play, narzędzie Asset Link wygeneruje odcisk palca klucza podpisywania aplikacji. Jeśli aplikacja została zainstalowana bezpośrednio z Twojego komputera, odcisk palca jest dla klucza wygenerowanego przez Bubblewrap.
Upewnij się, że plik linków do zasobów jest dostępny
Po przesłaniu pliku sprawdź, czy możesz otworzyć plik linku do zasobu w przeglądarce.
Sprawdź, czy https://example.com/.well-known/assetlinks.json odnosi się do przesłanego właśnie pliku.
Strony internetowe oparte na Jekyllu
Jeśli Twoja witryna jest generowana przez Jekylla (np. GitHub Pages), musisz dodać wiersz konfiguracji, aby katalog .well-known został uwzględniony w wyjściu.
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 plik już istnieje) i wpisz:
# Folders with dotfiles are ignored by default.
include: [.well-known]
Dodawanie większej liczby kluczy
Plik Digital Asset Link może zawierać więcej niż 1 aplikację, a dla każdej z nich może zawierać więcej niż 1 klucz. Aby na przykład dodać drugi klucz, użyj narzędzia do linkowania zasobów, aby określić klucz i dodać go jako drugi wpis. Kod w Chrome, który przetwarza ten plik JSON, jest dość rygorystyczny, więc uważaj, aby nie dodać przypadkowo dodatkowej przecinki 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. Możesz wyświetlić te logi na urządzeniu z Androidem z adb logcat.
Jeśli pracujesz na systemie Linux lub Mac, możesz wyświetlić odpowiednie dzienniki z podłączonego urządzenia:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
Jeśli na przykład zobaczysz komunikat Statement failure matching fingerprint., użyj narzędzia do łączenia zasobów, aby sprawdzić podpis aplikacji i sprawdzić, czy jest on zgodny z podanym w pliku assetlinks.json.