Jeśli jesteś deweloperem stron internetowych i nie znasz jeszcze Androida ani Google Play, zapoznaj się z kilkoma ważnymi informacjami. Istnieje już wiele materiałów i dokumentacji na ten temat (podziękowania dla zespołu Androida), ale tutaj omówimy kilka ważnych koncepcji i ich związek z aplikacją 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. Dzięki temu możesz zresetować klucz przesyłania, jeśli go utracisz lub zostanie przejęty. Wystarczy skontaktować 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, przetwarzanie 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 też pliki APK muszą być podpisane przez Google Play. 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, Google Play wkrótce zacznie wymagać, aby wszystkie nowe aplikacje były przesyłane w formacie AAB. Zalecamy przesyłanie plików w tym formacie zamiast plików APK.
- Zarządzanie własnym kluczem podpisywania: jeśli zdecydujesz się zarządzać swoim kluczem i nie włączysz podpisywania aplikacji przez Google Play, ponosisz pełną odpowiedzialność za klucz podpisywania swojej aplikacji. W przeciwieństwie do podpisywania aplikacji przez Google Play nie można go zresetować w przypadku utraty klucza. W związku z tym utrata klucza podpisywania aplikacji spowoduje też utratę możliwości jej aktualizowania.
Podczas konfiguracji bubblewrap init, gdy dojdziesz do części „Informacje o kluczu podpisywania (5/5)”, pojawi się prośba o podanie „lokalizacji magazynu kluczy” i „nazwy kluczy” lub użycie wartości domyślnych. Domyślną lokalizacją magazynu kluczy jest 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 tej nazwie, utworzy nowy magazyn kluczy i poprosi o hasła. Zanotuj wpisane hasła, ponieważ będą Ci potrzebne podczas procesu kompilacji (bubblewrap build), w którym będzie używany klucz do podpisywania aplikacji. Jeśli włączysz podpisywanie aplikacji przez Google Play, klucz podpisywania wygenerowany i używany do podpisywania aplikacji przez Bubblewrap 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 utrzymać go w prywatności.
Nie zalecamy ich zatwierdzania w systemie 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 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 Twojej aplikacji. Pamiętaj, że odciski palców powiązane z kluczami podpisywania i przesyłania będą się różnić. Pamiętaj o tym rozróżnieniu, zwłaszcza jeśli aplikacja uruchamia się jako karta niestandardowa Chrome (z widocznym paskiem przeglądarki). Następnie najprawdopodobniej w pliku assetlinks.json nie ma odcisku palca odpowiadającego odpowiedniemu klawiszowi.
Aby ułatwić lokalne debugowanie aplikacji, warto umieścić odcisk cyfrowy certyfikatu podpisywania i przesyłania w pliku assetlinks.json. 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 SHA256 dla certyfikatu 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 aplikacji instalowanej lokalnie, ale gdy opublikujesz aplikację 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. - Wyświetli się strona z podpisem aplikacji i wygenerowanym linkiem do zasobu cyfrowego. 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 Tool pobierze odcisk cyfrowy klucza podpisywania aplikacji. Jeśli aplikacja została zainstalowana bezpośrednio na komputerze lokalnym, odcisk cyfrowy klucza jest generowany dla wygenerowanego Bubblewrap.
Sprawdzanie, czy plik linku do zasobów jest dostępny
Po przesłaniu pliku sprawdź, czy możesz go otworzyć 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 w przypadku każdej aplikacji 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 i możesz wyświetlić dzienniki na urządzeniu z Androidem za pomocą adb logcat.
Jeśli pracujesz nad projektem w Linuxie lub na Macu, możesz wyświetlić odpowiednie logi 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.