Weryfikowanie linków aplikacji

Gdy element android:autoVerify="true" jest obecny w co najmniej jednym filtrze intencji aplikacji, zainstalowanie aplikacji na urządzeniu z Androidem 6.0 (poziom interfejsu API 23) lub nowszym powoduje, że system automatycznie weryfikuje hosty powiązane z adresami URL w filtrach intencji aplikacji. Na Androidzie 12 i nowszych możesz też wywołać proces weryfikacji ręcznie, aby przetestować logikę weryfikacji.

Automatyczna weryfikacja

Automatyczna weryfikacja systemu obejmuje:

1. System sprawdza wszystkie filtry intencji, które zawierają dowolny z tych elementów:
   • Działanie: android.intent.action.VIEW
   • Kategorie: android.intent.category.BROWSABLE i android.intent.category.DEFAULT
   • Schemat danych: http lub https
2. W przypadku każdej unikalnej nazwy hosta znalezionej w filtrach intencji Android wysyła do odpowiednich witryn zapytanie o plik Digital Asset Links pod adresem https://hostname/.well-known/assetlinks.json.

Uwaga: na Androidzie 11 (poziom interfejsu API 30) i starszych system ustawia aplikację jako domyślny moduł obsługi określonych wzorców adresów URL tylko wtedy, gdy znajdzie pasujący plik Digital Asset Links dla wszystkich hostów w pliku manifestu.

Po potwierdzeniu listy witryn, które chcesz powiązać z aplikacją, i sprawdzeniu, czy hostowany plik JSON jest prawidłowy, zainstaluj aplikację na urządzeniu. Odczekaj co najmniej 20 sekund na zakończenie asynchronicznego procesu weryfikacji. Aby sprawdzić, czy system zweryfikował aplikację i ustawił prawidłowe zasady obsługi linków, użyj tego polecenia:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Weryfikacja ręczna

Począwszy od Androida 12, możesz ręcznie wywołać weryfikację domeny w przypadku aplikacji zainstalowanej na urządzeniu. Możesz to zrobić niezależnie od tego, czy aplikacja jest kierowana na Androida 12.

Nawiąż połączenie z internetem.

Aby przeprowadzić weryfikację domeny, urządzenie testowe musi być połączone z internetem.

Obsługa zaktualizowanego procesu weryfikacji domeny

Jeśli aplikacja jest kierowana na Androida 12 lub nowszego, system automatycznie używa zaktualizowanego procesu weryfikacji domeny.

Możesz też ręcznie włączyć zaktualizowany proces weryfikacji. Aby to zrobić, uruchom w oknie terminala to polecenie:

adb shell am compat enable 175408749 PACKAGE_NAME

Resetowanie stanu linków aplikacji na Androida na urządzeniu

Zanim ręcznie wywołasz weryfikację domeny na urządzeniu, musisz zresetować stan linków do aplikacji na Androida na urządzeniu testowym. Aby to zrobić, uruchom w oknie terminala to polecenie:

adb shell pm set-app-links --package PACKAGE_NAME 0 all

To polecenie przywraca urządzenie do stanu, w którym było, zanim użytkownik wybrał domyślne aplikacje dla domen.

Wywoływanie procesu weryfikacji domeny

Po zresetowaniu stanu linków aplikacji na Androida na urządzeniu możesz przeprowadzić weryfikację. Aby to zrobić, uruchom w oknie terminala to polecenie:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Uwaga: zanim sprawdzisz wyniki tego polecenia, poczekaj kilka minut, aż agent weryfikacji zakończy żądania związane z weryfikacją domeny.

Sprawdzanie wyników weryfikacji

Po upływie czasu potrzebnego agentowi weryfikacji na zakończenie żądań sprawdź wyniki weryfikacji. Aby to zrobić, uruchom to polecenie:

adb shell pm get-app-links PACKAGE_NAME

Wynik tego polecenia jest podobny do tego:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

Domeny, które pomyślnie przeszły weryfikację, mają stan weryfikacji domeny verified. Każdy inny stan oznacza, że nie udało się zweryfikować domeny. W szczególności stan none wskazuje, że agent weryfikacji mógł jeszcze nie zakończyć procesu weryfikacji.

Poniższa lista zawiera możliwe wartości zwracane przez weryfikację domeny w przypadku danej domeny:

none

Nie zarejestrowano żadnych danych dotyczących tej domeny. Poczekaj kilka minut, aż agent weryfikacji zakończy żądania związane z weryfikacją domeny, a następnie ponownie wywołaj proces weryfikacji domeny.

verified

Domena została zweryfikowana pod kątem aplikacji deklarującej.

approved

Domena została zatwierdzona wymuszenie, zwykle przez wykonanie polecenia powłoki.

denied

Domena została odrzucona wymuszenie, zwykle przez wykonanie polecenia powłoki.

migrated

System zachował wynik poprzedniego procesu, który korzystał ze starszej wersji weryfikacji domeny.

restored

Domena została zatwierdzona po przywróceniu danych przez użytkownika. Zakładamy, że domena została wcześniej zweryfikowana.

legacy_failure

Domena została odrzucona przez starszy system weryfikacji. Konkretna przyczyna niepowodzenia jest nieznana.

system_configured

Domena została zatwierdzona automatycznie przez konfigurację urządzenia.

Kod błędu 1024 lub wyższy

Niestandardowy kod błędu, który jest specyficzny dla weryfikatora urządzenia.

Sprawdź, czy masz połączenie sieciowe, i ponownie wywołaj proces weryfikacji domeny.

Poproś użytkownika o powiązanie aplikacji z domeną

Innym sposobem na zatwierdzenie aplikacji dla domeny jest poproszenie użytkownika o powiązanie aplikacji z tą domeną.

Uwaga: na danym urządzeniu z określoną domeną może być powiązana tylko jedna aplikacja naraz. Jeśli inna aplikacja została już zweryfikowana dla domeny, użytkownik musi najpierw odłączyć tę aplikację od domeny, zanim będzie mógł powiązać z nią Twoją aplikację.

Sprawdzanie, czy aplikacja została już zatwierdzona w domenie

Zanim wyświetlisz użytkownikowi prośbę, sprawdź, czy Twoja aplikacja jest domyślnym modułem obsługi domen zdefiniowanych w elementach <intent-filter>. Stan zatwierdzenia możesz sprawdzić za pomocą jednej z tych metod:

• Interfejs API DomainVerificationManager (w czasie działania).
• program wiersza poleceń (podczas testowania).

DomainVerificationManager

Ten fragment kodu pokazuje, jak używać interfejsu API DomainVerificationManager:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the
// user has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user
        // has associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Program wiersza poleceń

Podczas testowania aplikacji w trakcie jej tworzenia możesz uruchomić to polecenie, aby sprawdzić stan weryfikacji domen należących do Twojej organizacji:

adb shell pm get-app-links --user cur PACKAGE_NAME

W poniższym przykładowym wyniku, mimo że aplikacja nie przeszła weryfikacji w domenie „example.org”, użytkownik 0 ręcznie zatwierdził aplikację w ustawieniach systemu i żaden inny pakiet nie został zweryfikowany w tej domenie.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Możesz też użyć poleceń powłoki, aby zasymulować proces, w którym użytkownik wybiera aplikację powiązaną z daną domeną. Pełne wyjaśnienie tych poleceń znajdziesz w danych wyjściowych polecenia adb shell pm.

Uwaga: system może powiązać z domeną tylko jedną aplikację naraz, nawet jeśli używasz poleceń powłoki. Niektóre szczególne przypadki, takie jak jednoczesna instalacja 2 wariantów aplikacji, wymagają specjalnego traktowania, aby dany link internetowy otwierał się w odpowiedniej aplikacji.

Podaj kontekst prośby.

Zanim poprosisz o zatwierdzenie domeny, podaj użytkownikowi pewne informacje. Możesz na przykład wyświetlić ekran powitalny, okno lub podobny element interfejsu, który wyjaśnia użytkownikowi, dlaczego Twoja aplikacja powinna być domyślnym modułem obsługi danej domeny.

Wysyłanie żądania

Gdy użytkownik zrozumie, o co prosi aplikacja, wyślij prośbę. Aby to zrobić, wywołaj intencję, która zawiera działanie intencji ACTION_APP_OPEN_BY_DEFAULT_SETTINGS i ciąg danych pasujący do package:com.example.pkg dla aplikacji docelowej, jak pokazano w tym fragmencie kodu:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Gdy intencja zostanie wywołana, użytkownicy zobaczą ekran ustawień o nazwie Otwieraj domyślnie. Na tym ekranie znajduje się przycisk opcji Otwieraj obsługiwane linki, jak pokazano na rysunku 1.

Gdy użytkownik włączy opcję Otwieraj obsługiwane linki, w sekcji Linki do otwierania w tej aplikacji pojawi się zestaw pól wyboru. W tym miejscu użytkownicy mogą wybrać domeny, które chcą powiązać z Twoją aplikacją. Mogą też kliknąć Dodaj link, aby dodać domeny, jak pokazano na rysunku 2. Gdy użytkownicy klikną później dowolny link w dodanych przez siebie domenach, link automatycznie otworzy się w Twojej aplikacji.

Rysunek 1. Ekran ustawień systemowych, na którym użytkownicy mogą wybrać, które linki mają być domyślnie otwierane w Twojej aplikacji.

Rysunek 2. Okno, w którym użytkownicy mogą wybrać dodatkowe domeny do powiązania z aplikacją.

Otwieranie w aplikacji domen, których aplikacja nie może zweryfikować

Główną funkcją aplikacji może być otwieranie linków jako aplikacja innej firmy, bez możliwości weryfikacji obsługiwanych domen. W takim przypadku wyjaśnij użytkownikom, że po wybraniu linku internetowego nie mogą wybrać między aplikacją własną a Twoją (aplikacją innej firmy). Użytkownicy muszą ręcznie powiązać domeny z Twoją aplikacją.

Dodatkowo rozważ wprowadzenie okna lub aktywności trampoliny, która umożliwia użytkownikowi otwarcie linku w aplikacji własnej, jeśli użytkownik woli to zrobić, działając jako serwer proxy. Zanim skonfigurujesz takie okno lub aktywność trampoliny, skonfiguruj aplikację tak, aby miała widoczność pakietu w aplikacjach własnych, które pasują do filtra intencji internetowych Twojej aplikacji.

Opóźnienie aktualizacji Digital Asset Links

Gdy zaktualizujesz plik assetlinks.json na serwerze WWW, czas potrzebny na odzwierciedlenie tych zmian na urządzeniach użytkowników będzie zależeć od wersji systemu operacyjnego:

• Android 15 (poziom API 35) i nowsze: system okresowo ponownie weryfikuje domeny w tle. Zastosowanie zmian na wszystkich urządzeniach użytkowników może potrwać do 7 dni ze względu na buforowanie systemu i zaplanowaną ponowną weryfikację.
• Android 14 (poziom interfejsu API 34) i starsze: system nie przeprowadza okresowej ponownej weryfikacji w tle. Aktualizacje pliku są zwykle pobierane tylko podczas instalowania lub aktualizowania aplikacji.

Aktualizacje dotyczące testowania

Aby wymusić ponowną weryfikację na konkretnym urządzeniu podczas testowania, możesz odinstalować i ponownie zainstalować aplikację. Pamiętaj jednak, że pamięć podręczna po stronie serwera może nadal opóźniać dostarczenie zaktualizowanego pliku assetlinks.json na urządzenie, nawet po ponownej instalacji. Pamięć podręczna jest oparta na czasie, więc opóźnienie zwykle znika automatycznie, jeśli spróbujesz ponownie po kilku godzinach.