Weryfikowanie linków aplikacji

Gdy w co najmniej jednym filtrze intencji aplikacji występuje element android:autoVerify="true", zainstalowanie aplikacji na urządzeniu z Androidem 6.0 (poziom interfejsu API 23) lub nowszym powoduje automatyczną weryfikację przez system hostów powiązanych z adresami URL w filtrach intencji aplikacji. Na urządzeniach z Androidem 12 lub nowszym możesz też ręcznie wywołać proces weryfikacji, aby przetestować logikę weryfikacji.

Automatyczna weryfikacja

Automatyczna weryfikacja przez system 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 powyżej Android wysyła zapytanie do odpowiednich witryn o plik Digital Asset Links pod adresem https:///.well-known/assetlinks.json.

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

Po potwierdzeniu listy witryn do powiązania z aplikacją i sprawdzeniu, 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ł 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 przeznaczona 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ć, wykonaj w oknie terminala to polecenie:

adb shell am compat enable 175408749 PACKAGE_NAME

Resetowanie stanu linków do 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 w oknie terminala to polecenie:

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łaj proces weryfikacji domeny.

Po zresetowaniu stanu linków aplikacji 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 przetwarzanie żądań związanych z weryfikacją domeny.

Sprawdzanie wyników weryfikacji

Po upływie czasu potrzebnego agentowi weryfikacyjnemu na wykonanie żą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 przeszły weryfikację, mają stan weryfikacji domeny verified. Każdy inny stan oznacza, że nie udało się przeprowadzić weryfikacji domeny. W szczególności stan none oznacza, że agent weryfikacyjny mógł jeszcze nie ukończyć procesu weryfikacji.

Poniżej znajdziesz listę możliwych wartości zwracanych przez weryfikację domeny w przypadku danej domeny:

none

W przypadku tej domeny nic nie zostało zarejestrowane. Poczekaj jeszcze kilka minut, aż agent weryfikacyjny zakończy przetwarzanie żądań związanych z weryfikacją domeny, a następnie ponownie wywołaj proces weryfikacji domeny.

verified

Domena została zweryfikowana w przypadku aplikacji zgłaszającej.

approved

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

denied

Domena została odrzucona, zwykle przez wykonanie polecenia w powłoce.

migrated

System zachował wynik poprzedniego procesu, w którym użyto starszej metody 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 większy

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

Sprawdź, czy masz połączenie z siecią, i ponownie uruchom 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ą.

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

Sprawdzanie, czy aplikacja jest już zatwierdzona w przypadku domeny

Zanim wyświetlisz użytkownikowi prośbę, sprawdź, czy Twoja aplikacja jest domyślnym programem obsługującym domeny zdefiniowane 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

Poniższy 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ładzie danych wyjściowych, mimo że weryfikacja aplikacji w domenie „example.org” nie powiodła się, użytkownik 0 ręcznie zatwierdził aplikację w ustawieniach systemu, a w tej domenie nie ma zweryfikowanych innych pakietów.

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 jednoczesne instalowanie dwóch wariantów aplikacji, wymagają specjalnego postępowania, aby otworzyć dany link w odpowiedniej aplikacji.

Podaj kontekst żądania

Zanim poprosisz o zatwierdzenie domeny, podaj użytkownikowi kontekst. Możesz na przykład wyświetlić ekran powitalny, okno lub podobny element interfejsu, który wyjaśni użytkownikowi, dlaczego Twoja aplikacja powinna być domyślnym programem obsługującym daną domenę.

Wysyłanie prośby

Gdy użytkownik zrozumie, o co prosisz, poproś go o wykonanie działania. 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 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ę opcja 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. W tym miejscu użytkownicy mogą wybrać domeny, które chcą powiązać z aplikacją. Mogą też kliknąć 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.

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

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

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

Główną funkcją aplikacji może być otwieranie linków jako podmiot zewnętrzny bez możliwości weryfikacji obsługiwanych domen. W takim przypadku poinformuj użytkowników, że w momencie kliknięcia linku nie mogą oni wybrać między aplikacją własną a Twoją aplikacją (firmy zewnętrznej). Muszą ręcznie powiązać domeny z Twoją aplikacją.

Możesz też wprowadzić okno lub aktywność trampoliny, które umożliwią użytkownikowi otwarcie linku w aplikacji własnej, jeśli będzie tego chciał, działając jako serwer proxy. Zanim skonfigurujesz takie okno lub aktywność pośredniczącą, skonfiguruj aplikację tak, aby miała widoczność pakietu w aplikacjach własnych, które pasują do filtra intencji internetowej Twojej aplikacji.