Weryfikowanie linków aplikacji

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

Automatyczna weryfikacja

Automatyczna weryfikacja systemu obejmuje te czynności:

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żdego unikalnego hosta znalezionego w filtrach intencji Android wysyła zapytanie do odpowiednich witryn o plik Digital Asset Links pod adresem https://hostname/.well-known/assetlinks.json.

Gdy potwierdzisz listę witryn, które mają być powiązane z Twoją aplikacją, i sprawdzisz, czy hostowany plik JSON jest prawidłowy, zainstaluj aplikację na urządzeniu. Zaczekaj co najmniej 20 sekund, aż zakończy się asynchroniczny proces weryfikacji. Aby sprawdzić, czy system zweryfikował Twoją 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

Od Androida 12 możesz ręcznie wywołać weryfikację domeny w przypadku aplikacji zainstalowanej na urządzeniu. Możesz przeprowadzić ten proces niezależnie od tego, czy Twoja aplikacja jest kierowana na Androida 12.

Nawiązywanie połączenia z internetem

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

Obsługa zaktualizowanego procesu weryfikacji domeny

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

W przeciwnym razie możesz ręcznie włączyć zaktualizowany proces weryfikacji. Aby to zrobić, uruchom to polecenie w oknie terminala:

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 aplikacji na Androida na urządzeniu testowym. Aby to zrobić, uruchom to polecenie w oknie terminala:

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

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

Wywoływanie procesu weryfikacji domeny

Gdy zresetujesz stan linków aplikacji na Androida na urządzeniu, możesz przeprowadzić samą weryfikację. Aby to zrobić, uruchom to polecenie w oknie terminala:

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

Sprawdzanie wyników weryfikacji

Po odczekaniu, aż agent weryfikacji zakończy żądania, 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 przejdą weryfikację, mają stan weryfikacji domeny verified. Każdy inny stan oznacza, że nie można było przeprowadzić weryfikacji domeny. W szczególności stan none oznacza, że agent weryfikacji mógł jeszcze nie zakończyć procesu weryfikacji.

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

none

Nie zarejestrowano żadnych informacji o tej domenie. Poczekaj jeszcze 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 w przypadku deklarującej aplikacji.

approved

Domena została zatwierdzona na siłę, zwykle przez wykonanie polecenia powłoki.

denied

Domena została odrzucona na siłę, zwykle przez wykonanie polecenia powłoki.

migrated

System zachował wynik poprzedniego procesu, który korzystał z weryfikacji domeny starszego typu.

restored

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

legacy_failure

Domena została odrzucona przez weryfikator starszego typu. Konkretna przyczyna niepowodzenia jest nieznana.

system_configured

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

Kod błędu 1024 lub większy

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

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

Prośba o powiązanie aplikacji z domeną

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

Sprawdzanie, czy Twoja aplikacja jest już zatwierdzona w domenie

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

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

DomainVerificationManager

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

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 }

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 programowania 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 tym przykładzie, mimo że weryfikacja aplikacji w domenie „example.org” nie powiodła się, użytkownik 0 ręcznie zatwierdził aplikację w ustawieniach systemu i żadna inna paczka nie jest zweryfikowana 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.

Podawanie kontekstu żądania

Zanim wyślesz prośbę o zatwierdzenie domeny, podaj użytkownikowi kontekst. Możesz na przykład wyświetlić ekran powitalny, okno dialogowe lub podobny element interfejsu, który wyjaśni użytkownikowi, dlaczego Twoja aplikacja powinna być domyślnym modułem obsługi danej domeny.

Wysyłanie prośby

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

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)

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ń Otwieraj domyślnie. Ten ekran zawiera opcję Otwieraj obsługiwane linki, jak pokazano na ilustracji 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. Użytkownicy mogą tu wybrać domeny, które chcą powiązać z Twoją aplikacją. Mogą też wybrać Dodaj link, aby dodać domeny, jak pokazano na ilustracji 2. Gdy użytkownicy wybiorą później dowolny link w dodanych przez siebie domenach, link otworzy się automatycznie w Twojej aplikacji.

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

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

Rozważ też wprowadzenie okna dialogowego lub aktywności trampoliny, która umożliwi użytkownikowi otwarcie linku w aplikacji własnej, jeśli użytkownik będzie tego wolał, działając jako serwer proxy. Zanim skonfigurujesz takie okno dialogowe lub aktywność trampoliny, skonfiguruj aplikację tak, aby miała widoczność pakietu w aplikacjach własnych, które pasują do filtra intencji internetowej Twojej aplikacji.

Opóźnienie aktualizacji Digital Asset Links

Gdy zaktualizujesz plik assetlinks.json na serwerze WWW, czas, jaki upłynie, zanim te zmiany zostaną odzwierciedlone na urządzeniach użytkowników końcowych, zależy od wersji systemu operacyjnego:

• Android 15 (poziom API 35) i nowsze: system okresowo ponownie weryfikuje domeny w tle. Z powodu buforowania i zaplanowanej ponownej weryfikacji przez system wprowadzenie zmian na wszystkich urządzeniach użytkowników może potrwać do 7 dni.
• Android 14 (poziom API 34) i starsze: system nie przeprowadza okresowej ponownej weryfikacji w tle. Aktualizacje pliku są zwykle wykrywane tylko wtedy, gdy aplikacja jest instalowana lub aktualizowana.

Testowanie aktualizacji

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