SHA-256 w assetlinks.json po Play App Signing: usuń pasek przeglądarki z TWA

Ten poradnik dotyczy jednej naprawy: powiązania między Twoją stroną a wersją, którą dostarcza Google Play. Nie opisuje budowania samej TWA ani weryfikacji aplikacji przez Google Play, które mają własne poradniki podlinkowane niżej. Każdą cytowaną tu stronę Google sprawdziliśmy 16 października 2026 r., a źródła znajdziesz na końcu.

Dlaczego pasek przeglądarki pojawia się tylko w instalacji z Google Play

Chrome weryfikuje TWA, porównując certyfikat, którym podpisano zainstalowaną aplikację, z odciskami cyfrowymi publikowanymi przez Twoją stronę. Gdy ta kontrola się nie powiedzie, według przewodnika szybkiego startu TWA od Chrome przeglądarka wyświetla Twoją stronę jako Custom Tab. Ten tryb awaryjny to właśnie pasek adresu, który widzisz.

Przy Play App Signing zwykle istnieją dwa certyfikaty. Pakiet, który przesyłasz, podpisujesz swoim kluczem przesyłania, a Google podpisuje dostarczane pliki APK kluczem podpisywania aplikacji. Strona Chrome Android concepts for web developers podaje, że to odcisk klucza podpisywania aplikacji odpowiada Twojej aplikacji pobranej ze Sklepu Play. Plik, który zawiera tylko Twój lokalny certyfikat, przechodzi więc kontrolę na Twoim biurku i zawodzi na każdym telefonie, na którym zainstalowano aplikację z Google Play.

Te dwa klucze nie zawsze się różnią. Dokumentacja podpisywania aplikacji Androida opisuje konfiguracje, w których ten sam klucz pełni rolę klucza podpisywania aplikacji i klucza przesyłania. Rozwiązaniem jest więc porównanie prawdziwych certyfikatów, a nie zgadywanie, który masz.

Znajdź SHA-256 klucza podpisywania aplikacji w Play Console

Dokumentacja Google podaje obecnie dwie nazwy tego samego miejsca. Obie zaczynają się od Protected with Play w lewym menu Twojej aplikacji.

Starsze poradniki, w tym niektóre strony Google, nadal podają Release > Setup > App signing lub Setup > App integrity. Jeśli widzisz tylko te nazwy, szukasz tej samej strony pod starszą nazwą.

Odczytaj odcisk klucza, który masz u siebie

Dla klucza przesyłania lub klucza debug narzędzie keytool z Javy wypisuje odcisk w tym samym formacie. Zastąp plik magazynu kluczy i alias własnymi, a potem skopiuj wiersz oznaczony SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Jeśli zarządzasz wieloma aplikacjami, Google Play Developer API też może zwrócić skrót certyfikatu plików APK wygenerowanych przez Google Play (pole certificateSha256Hash na liście wygenerowanych plików APK). Przy pojedynczej poprawce prościej jest skopiować go z Play Console.

Przygotuj i udostępnij poprawny plik assetlinks.json

Plik to tablica JSON z wpisami (statements). Dla TWA relacja to delegate_permission/common.handle_all_urls, a celem jest Twoja aplikacja na Androida: przestrzeń nazw android_app, Twój dokładny identyfikator aplikacji i tablica odcisków SHA-256. Minimalny plik wygląda tak:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Zastąp com.example.twa swoim identyfikatorem aplikacji, a każdy symbol zastępczy pełnym SHA-256 rozdzielonym dwukropkami. Usuń drugi wpis, jeśli potrzebujesz weryfikacji tylko dla instalacji z Google Play. Wyłącznie ścisły JSON: bez komentarzy, bez przecinków na końcu i bez wartości SHA-1.

Jak według Google trzeba udostępniać plik

• Dokładna lokalizacja. https://your-domain/.well-known/assetlinks.json, z kropką w .well-known. example.com i www.example.com to różne originy; opublikuj plik na każdym, który otwiera Twoja aplikacja. Kopia w podkatalogu, na przykład /app/.well-known/, się nie liczy.
• Bezpośrednia odpowiedź HTTP 200. Dokumentacja Digital Asset Links od Google mówi: „Każda odpowiedź serwera inna niż HTTP 200 jest traktowana jako błąd i skutkuje pustą listą wpisów.”
• Bez przekierowań. Odpowiedzi 301 i 302 nie są śledzone. Dotyczy to także przejścia z http na https oraz z domeny bez www na www.
• HTTPS z prawidłowym łańcuchem certyfikatów oraz nagłówek Content-Type: application/json. Strona logowania albo strona błędu HTML, która odpowiada kodem 200, nie jest prawidłowym plikiem.

Sprawdź aktualną odpowiedź z dowolnego terminala. Pierwszy wiersz statusu musi zawierać 200, typ treści musi być JSON, a przed nim nie może być żadnego 3xx:

curl -sI https://example.com/.well-known/assetlinks.json

Więcej niż jeden odcisk, więcej niż jedna aplikacja

Przewodnik po powiązaniach ze stronami Androida mówi o tablicy odcisków: „To pole obsługuje wiele odcisków cyfrowych, których można użyć do obsługi różnych wersji aplikacji, na przykład wersji debug i produkcyjnej.” Dodawaj odcisk klucza przesyłania lub debug tylko dla wersji, którym ta strona ma naprawdę ufać. Wersja z innym identyfikatorem aplikacji, na przykład osobny pakiet debug, potrzebuje w tablicy własnego wpisu.

Jeśli TWA powstała w Bubblewrap lub PWABuilder

W istniejącym projekcie Bubblewrap dodaj odcisk z Google Play i wygeneruj plik ponownie:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Wygenerowanie pliku to jeszcze nie wdrożenie: prześlij nowy assetlinks.json na swoją stronę i sprawdź go przez curl. bubblewrap validate sprawdza Twoją PWA pod kątem kryteriów jakości; nie sprawdza powiązania podpisu, więc pozytywny wynik nic nie mówi o odcisku. Aktualne instrukcje PWABuilder mówią to samo o podpisywaniu: „Po przesłaniu pliku .aab Google Play ponownie podpisuje Twoją aplikację”, i każą dodać odcisk z Google Play do wygenerowanego pliku. Poprawka odcisku to zmiana na Twojej stronie, a nie w pliku binarnym aplikacji.

Zweryfikuj powiązanie, potem przetestuj instalację z Google Play

W grę wchodzą cztery warstwy: plik na Twojej stronie, Digital Asset Links API od Google, weryfikacja linków w samym Androidzie i przeglądarka, która uruchamia Twoją TWA. Przejście jednej warstwy nie dowodzi przejścia następnej, więc sprawdzaj je po kolei i zakończ na urządzeniu.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

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

App Links Assistant w Android Studio (Tools > App Links Assistant) sprawdza powiązanie Android App Links i Twój manifest. Przydaje się do tego, ale nie powie Ci, czy Twoja TWA otwiera się na pełnym ekranie; to pokaże tylko test na urządzeniu.

Zaawansowane: stan weryfikacji w samym Androidzie

Na Androidzie 12 i nowszym przewodnik po weryfikacji Androida dokumentuje te polecenia dla App Links. Zastąp nazwę pakietu, uruchom dwa pierwsze polecenia, odczekaj kilka minut, a potem odczytaj stan:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified opisuje weryfikację domeny w Androidzie, a nie to, czy Twoja TWA otwiera się bez interfejsu przeglądarki. Kody 1024 i wyższe to błędy specyficzne dla weryfikatora, a nie diagnoza błędnego SHA-256. Dla samej TWA korzystaj z logu Chrome opisanego wyżej.

Odcisk się zgadza, ale pasek zostaje

Widoczny pasek nie dowodzi, że SHA-256 jest błędny. Gdy powyższe sprawdzenie zwraca linked: true, a pasek nadal jest widoczny, przejdź po kolei przez te przyczyny.

Po jakim czasie poprawiony plik zaczyna działać

Google nie podaje jednego czasu oczekiwania dla TWA, ponieważ w grę wchodzi kilka pamięci podręcznych, a każda ma własne zasady:

• Twój serwer lub CDN może nadal serwować stary plik. Wyczyść pamięć podręczną i potwierdź aktualną odpowiedź przez curl.
• Digital Asset Links API podaje w polu maxAge, jak długo każda odpowiedź pozostaje ważna.
• Android App Links ma osobne terminy. Przewodnik po weryfikacji Androida mówi, że na Androidzie 15 i nowszym zmiany mogą potrzebować do siedmiu dni, aby dotrzeć do wszystkich urządzeń, a na Androidzie 14 i starszym plik jest zwykle pobierany przy instalacji lub aktualizacji aplikacji.
• Przeglądarka może przechowywać własny stan. Jeden deweloper zgłosił, że pomogło mu wyczyszczenie danych Chrome.

Wyczyść więc pamięć podręczną, potwierdź aktualny plik i zainstaluj aplikację ponownie z Google Play. Na urządzeniu testowym świeża instalacja lub wyczyszczenie danych przeglądarki pozwala wykluczyć zapisany stan; to krok diagnostyczny, a nie coś, o co należy prosić każdego użytkownika. Nie planuj w oparciu o stałą liczbę godzin.

Odrzucenie, weryfikacja i testy zamknięte

Brakujący lub błędny assetlinks.json nie jest udokumentowany jako samodzielna przyczyna odrzucenia. Dokumentacja opisuje natomiast przejście na Custom Tab z interfejsem przeglądarki. Weryfikacja to osobna kwestia: zasady dotyczące funkcjonalności Google Play mówią: „Nie zezwalamy na aplikacje, które ulegają awarii, wymuszają zamknięcie, zawieszają się lub w inny sposób działają nieprawidłowo”, i dotyczy to aplikacji niezależnie od stanu powiązania. Poprawny odcisk usuwa pasek; nie rozstrzyga weryfikacji. Jeśli otrzymałeś odrzucenie, zacznij od zasady wskazanej w e-mailu.

Niektóre starsze artykuły twierdzą, że Chrome zamknie awaryjnie TWA, która nie przejdzie kontroli jakości. Chromium usunął kod QualityEnforcer 4 maja 2023 r., więc traktuj tę radę jako historyczną, a nie jako opis dzisiejszych przeglądarek.

Jeśli otrzymałeś odrzucenie, pracuj na podstawie powodu podanego w powiadomieniu: odrzucenie za Broken Functionality omawia krok po kroku najczęstsze powiadomienie dotyczące funkcjonalności. Nie przebudowuj TWA na WebView tylko z powodu paska przeglądarki. Jeśli Twoja aplikacja powstała w kreatorze AI, poradnik publikowanie aplikacji z vibe codingu w Google Play opisuje całą drogę od projektu do Google Play.

Najczęściej zadawane pytania

Podsumowanie

Nazwy menu Play Console to najszybciej zmieniający się fakt na tej stronie. Jeśli powyższe ścieżki nie pasują już do Twojej Konsoli, szukaj Play app signing w sekcji Protected with Play albo wyszukaj w Konsoli frazę app signing.