Weryfikacja linków aplikacji na Androida

Link aplikacji na Androida to specjalny rodzaj precyzyjnego linku, który umożliwia natychmiastowe otwieranie adresów URL witryny w odpowiedniej treści w aplikacji na Androida bez konieczności wybierania aplikacji przez użytkownika. Linki aplikacji na Androida korzystają z interfejsu Digital Asset Links API, aby potwierdzić, że aplikacja została zatwierdzona przez witrynę do automatycznego otwierania linków do tej domeny. Jeśli system potwierdzi, że jesteś właścicielem adresów URL, automatycznie przekieruje intencje związane z tymi adresami URL do Twojej aplikacji.

Aby potwierdzić, że aplikacja i adresy URL witryny należą do Ciebie, wykonaj te czynności:

  1. Dodaj filtry intencji, które zawierają atrybut autoVerify. Ten atrybut informuje system, że powinien sprawdzić, czy Twoja aplikacja należy do domen URL używanych w filtrach intencji.

  2. Zadeklaruj powiązanie między witryną a filtrami intencji, hostując plik JSON protokołu Digital Asset Links w tej lokalizacji:

    https://domain.name/.well-known/assetlinks.json

Więcej informacji znajdziesz w tych materiałach:

Dodawanie filtrów intencji do weryfikacji linków do aplikacji

Aby włączyć weryfikację obsługi linków w aplikacji, dodaj filtry intencji zgodne z tym formatem:

<!-- Make sure you explicitly set android:autoVerify to "true". -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <!-- If a user clicks on a shared link that uses the "http" scheme, your
         app should be able to delegate that traffic to "https". -->
    <!-- Do not include other schemes. -->
    <data android:scheme="http" />
    <data android:scheme="https" />

    <!-- Include one or more domains that should be verified. -->
    <data android:host="..." />
</intent-filter>

Wystarczy, że w przypadku każdego hosta umieścisz wartość autoVerify w tylko jednej deklaracji <intent-filter>, nawet jeśli ten host jest używany w innych nieoznaczonych deklaracjach. Jednak dla zachowania spójności zalecamy dodanie wartości autoVerify do każdego elementu <intent-filter>. Dzięki temu po usunięciu lub refaktoryzacji elementów w pliku manifestu aplikacja pozostanie powiązana ze wszystkimi domenami, które nadal definiujesz.

Proces weryfikacji domeny wymaga połączenia z internetem i może trochę potrwać. Aby zwiększyć skuteczność tego procesu, system weryfikuje domenę aplikacji kierowanej na Androida 12 lub nowszego tylko wtedy, gdy znajduje się ona w elemencie <intent-filter>, który zawiera dokładny format określony w poprzednim fragmencie kodu. Na przykład schematy inne niż „http” i „https”, takie jak <data android:scheme="custom" />, uniemożliwią <intent-filter> wywołanie weryfikacji domeny.

Obsługa łączenia aplikacji z wieloma hostami

System musi być w stanie zweryfikować hosta określonego w elementach danych filtrów intencji adresu URL aplikacji na podstawie plików Digital Asset Links hostowanych w odpowiednich domenach internetowych w tym filtrze intencji. Jeśli weryfikacja się nie powiedzie, system domyślnie podejmuje standardowe działanie, aby rozwiązać intencję, zgodnie z opisem w artykule Tworzenie precyzyjnych linków do treści aplikacji. Aplikacja może jednak nadal być weryfikowana jako domyślny moduł obsługi dowolnego wzorca adresu URL zdefiniowanego w innych filtrach intencji aplikacji.

Uwaga: na Androidzie 11 (poziom API 30) i starszych system nie weryfikuje aplikacji jako domyślnego modułu obsługi, chyba że znajdzie pasujący plik Digital Asset Links dla wszystkich hostów zdefiniowanych w pliku manifestu.

Na przykład aplikacja z tymi filtrami intencji przejdzie weryfikację tylko w przypadku https://www.example.com, jeśli plik assetlinks.json zostanie znaleziony w lokalizacji https://www.example.com/.well-known/assetlinks.json, ale nie w lokalizacji https://www.example.net/.well-known/assetlinks.json:

<application>

  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name=”SecondActivity”>
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

Uwaga: wszystkie elementy <data> w tym samym filtrze intencji są łączone, aby uwzględnić wszystkie odmiany połączonych atrybutów. Na przykład pierwszy filtr intencji powyżej zawiera element <data>, który deklaruje tylko schemat HTTPS. Jest on jednak połączony z innym elementem <data>, dzięki czemu filtr intencji obsługuje zarówno http://www.example.com, jak i https://www.example.com. Dlatego musisz utworzyć osobne filtry intencji, jeśli chcesz zdefiniować konkretne kombinacje schematów URI i domen.

Obsługa łączenia aplikacji w przypadku wielu subdomen

Protokół Digital Asset Links traktuje subdomeny w filtrach intencji jako unikalne, oddzielne hosty. Jeśli więc filtr intencji zawiera wiele hostów z różnymi subdomenami, musisz opublikować prawidłowy plik assetlinks.json w każdej domenie. Na przykład ten filtr intencji zawiera www.example.commobile.example.com jako akceptowane hosty URL intencji. Prawidłowy adres assetlinks.json musi być opublikowany zarówno na stronie https://www.example.com/.well-known/assetlinks.json, jak i https://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

Jeśli zadeklarujesz nazwę hosta za pomocą symbolu wieloznacznego (np. *.example.com), musisz opublikować plik assetlinks.json w głównej nazwie hosta (example.com). Na przykład aplikacja z tym filtrem intencji przejdzie weryfikację w przypadku dowolnej subdomeny example.com (np. foo.example.com), o ile plik assetlinks.json zostanie opublikowany w domenie https://example.com/.well-known/assetlinks.json:

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Sprawdzanie, czy z tą samą domeną jest powiązanych kilka aplikacji

Jeśli opublikujesz kilka aplikacji powiązanych z tą samą domeną, każda z nich może zostać zweryfikowana. Jeśli jednak aplikacje mogą rozpoznawać dokładnie tę samą domenę i ścieżkę, jak w przypadku wersji lite i pełnej aplikacji, tylko aplikacja zainstalowana ostatnio może rozpoznawać intencje internetowe dla tej domeny.

W takim przypadku sprawdź, czy na urządzeniu użytkownika nie ma aplikacji, które mogą powodować konflikt, pod warunkiem że masz niezbędną widoczność pakietu. Następnie w aplikacji wyświetl niestandardowe okno wyboru zawierające wyniki wywołania funkcji queryIntentActivities(). Użytkownik może wybrać preferowaną aplikację z listy pasujących aplikacji, która pojawi się w oknie.

Deklarowanie powiązań z witrynami

W witrynie musi być opublikowany plik JSON Digital Asset Links, który wskazuje aplikacje na Androida powiązane z witryną i weryfikuje intencje adresów URL aplikacji. Plik JSON zawiera te pola, które służą do identyfikowania powiązanych aplikacji:

  • package_name: Identyfikator aplikacji zadeklarowany w pliku build.gradle aplikacji.
  • sha256_cert_fingerprints: odciski cyfrowe SHA256 certyfikatu podpisywania aplikacji. Aby wygenerować odcisk palca za pomocą narzędzia Java keytool, możesz użyć tego polecenia:
    keytool -list -v -keystore my-release-key.keystore
    
    To pole obsługuje wiele odcisków palców, których można używać do obsługi różnych wersji aplikacji, np. wersji debugowania i produkcyjnej.

    Jeśli używasz podpisywania aplikacji w Google Play, odcisk cyfrowy certyfikatu wygenerowany przez uruchomienie keytool lokalnie zwykle nie będzie zgodny z odciskiem na urządzeniach użytkowników. Aby sprawdzić, czy w przypadku Twojej aplikacji używasz podpisywania aplikacji w Google Play, otwórz konto dewelopera w Konsoli Play i kliknij Release > Setup > App signing. Jeśli używasz tej usługi, na tej samej stronie znajdziesz też prawidłowy fragment kodu JSON protokołu Digital Asset Links dla swojej aplikacji.

Ten przykładowy plik assetlinks.json przyznaje uprawnienia do otwierania linków aplikacji na Androida:com.example

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Powiązywanie witryny z wieloma aplikacjami

Witryna może deklarować powiązania z wieloma aplikacjami w tym samym pliku assetlinks.json. Poniższy przykład przedstawia plik z oświadczeniem, który deklaruje powiązanie z 2 aplikacjami oddzielnie i znajduje się pod adresem https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Różne aplikacje mogą obsługiwać linki do różnych zasobów w ramach tego samego hosta internetowego. Na przykład aplikacja 1 może zadeklarować filtr intencji dla https://example.com/articles, a aplikacja 2 może zadeklarować filtr intencji dla https://example.com/videos.

Uwaga: wiele aplikacji powiązanych z domeną może być podpisanych tym samym lub różnymi certyfikatami.

Powiązywanie wielu witryn z jedną aplikacją

Wiele witryn może deklarować powiązania z tą samą aplikacją w odpowiednich plikach assetlinks.json. Poniższe listy plików pokazują przykład deklarowania powiązania domen example.com i example.net z aplikacją app1. Pierwsza pozycja pokazuje powiązanie domeny example.com z aplikacją app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Kolejna lista pokazuje powiązanie domeny example.net z aplikacją app1. Różni się tylko lokalizacja, w której są hostowane te pliki (.com.net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Publikowanie pliku weryfikacyjnego JSON

Musisz opublikować plik weryfikacyjny JSON w tej lokalizacji:

https://domain.name/.well-known/assetlinks.json

Upewnij się, że:

  • assetlinks.json Plik jest udostępniany z nagłówkiem content-type application/json.
  • assetlinks.json Plik musi być dostępny przez połączenie HTTPS, niezależnie od tego, czy filtry intencji aplikacji wskazują HTTPS jako schemat danych.
  • Plik assetlinks.json musi być dostępny bez przekierowań (bez przekierowań 301 lub 302).
  • Jeśli linki do aplikacji obsługują wiele domen hosta, musisz opublikować plik assetlinks.json w każdej domenie. Zobacz Obsługa linkowania aplikacji w przypadku wielu hostów.
  • Nie publikuj aplikacji z adresami URL deweloperskimi/testowymi w pliku manifestu, które mogą być niedostępne publicznie (np. takie, które są dostępne tylko przez VPN). W takich przypadkach można skonfigurować warianty kompilacji, aby generować inny plik manifestu dla kompilacji deweloperskich.

Weryfikacja linków aplikacji na Androida

Jeśli w co najmniej jednym filtrze intencji aplikacji występuje symbol android:autoVerify="true", zainstalowanie aplikacji na urządzeniu z Androidem 6.0 (poziom interfejsu API 23) lub nowszym spowoduje 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 w systemie 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.BROWSABLEandroid.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://hostname/.well-known/assetlinks.json.

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 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 jakim znajdowało się przed wybraniem przez użytkownika domyślnych aplikacji dla dowolnych domen.

Wywołaj proces weryfikacji domeny.

Po zresetowaniu stanu linków do 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

Sprawdzanie wyników weryfikacji

Po upływie czasu potrzebnego na wykonanie żądań przez agenta weryfikacyjnego 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ą.

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:

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.

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ę przycisk opcji 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 Twoją 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.

Gdy opcja jest włączona, w sekcji u dołu znajdują się pola wyboru oraz przycisk „Dodaj link”.
Rysunek 1. ekran ustawień systemu, na którym użytkownicy mogą wybrać, które linki mają być domyślnie otwierane w Twojej aplikacji.
Każde pole wyboru reprezentuje domenę, którą możesz dodać. Przyciski w oknie to „Anuluj” i „Dodaj”.
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ą.

Rozważ też wprowadzenie okna lub aktywności trampoliny, które umożliwią użytkownikowi otwarcie linku w aplikacji własnej, jeśli będzie on tego chciał. Będzie to działać 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 internetowych Twojej aplikacji.

Testowanie linków aplikacji

Podczas wdrażania funkcji łączenia aplikacji należy przetestować funkcję łączenia, aby upewnić się, że system może powiązać aplikację z witrynami i obsługiwać żądania URL zgodnie z oczekiwaniami.

Aby przetestować istniejący plik z wyciągiem, możesz użyć narzędzia Generator i tester listy wyciągów.

Potwierdź listę hostów do zweryfikowania

Podczas testowania sprawdź listę powiązanych hostów, które system powinien zweryfikować w przypadku Twojej aplikacji. Utwórz listę wszystkich adresów URL, których odpowiednie filtry intencji zawierają te atrybuty i elementy:

  • atrybut android:scheme o wartości http lub https;
  • android:host atrybut ze wzorcem adresu URL domeny,
  • android.intent.action.VIEW element działania
  • Element kategorii android.intent.category.BROWSABLE

Skorzystaj z tej listy, aby sprawdzić, czy w przypadku każdego wymienionego hosta i subdomeny podano plik JSON protokołu Digital Asset Links.

Potwierdź pliki Digital Asset Links

W przypadku każdej witryny użyj interfejsu Digital Asset Links API, aby potwierdzić, że plik JSON protokołu Digital Asset Links jest prawidłowo hostowany i zdefiniowany:

https://digitalassetlinks.googleapis.com/v1/statements:list?
   source.web.site=https://domain.name:optional_port&
   relation=delegate_permission/common.handle_all_urls

W ramach procesu testowania możesz sprawdzić bieżące ustawienia systemu dotyczące obsługi linków. Aby wyświetlić listę zasad obsługi linków dla wszystkich aplikacji na połączonym urządzeniu, użyj tego polecenia:

adb shell dumpsys package domain-preferred-apps

To samo można osiągnąć za pomocą tego kodu:

adb shell dumpsys package d

Uwaga: po zainstalowaniu aplikacji odczekaj co najmniej 20 sekund, aby system mógł zakończyć proces weryfikacji.

Polecenie zwraca listę wszystkich użytkowników lub profili zdefiniowanych na urządzeniu, poprzedzoną nagłówkiem w tym formacie:

App linkages for user 0:

Po tym nagłówku dane wyjściowe mają następujący format, który zawiera listę ustawień obsługi linków dla danego użytkownika:

Package: com.android.vending
Domains: play.google.com market.android.com
Status: always : 200000002

Ta lista pokazuje, które aplikacje są powiązane z którymi domenami w przypadku danego użytkownika:

  • Package – identyfikuje aplikację na podstawie nazwy pakietu zadeklarowanej w manifeście.
  • Domains – wyświetla pełną listę hostów, których linki internetowe obsługuje ta aplikacja, używając spacji jako separatorów.
  • Status – pokazuje bieżące ustawienie obsługi linków w tej aplikacji. Aplikacja, która przeszła weryfikację i której manifest zawiera android:autoVerify="true", ma stan always. Liczba szesnastkowa po tym stanie jest powiązana z zapisem preferencji użytkownika dotyczących powiązania aplikacji w systemie Android. Ta wartość nie wskazuje, czy weryfikacja się powiodła.

Uwaga: jeśli użytkownik zmieni ustawienia linku do aplikacji przed zakończeniem weryfikacji, może pojawić się fałszywie pozytywny wynik weryfikacji, mimo że weryfikacja się nie powiodła. Ten błąd weryfikacji nie ma jednak znaczenia, jeśli użytkownik wyraźnie zezwolił aplikacji na otwieranie obsługiwanych linków bez pytania. Wynika to z tego, że ustawienia użytkownika mają pierwszeństwo przed weryfikacją automatyczną (lub jej brakiem). W rezultacie link prowadzi bezpośrednio do aplikacji, bez wyświetlania okna, tak jakby weryfikacja się powiodła.

Przykładowy test

Aby weryfikacja linku aplikacji zakończyła się powodzeniem, system musi być w stanie zweryfikować Twoją aplikację w przypadku każdej witryny określonej w danym filtrze intencji, który spełnia kryteria linków aplikacji. Poniższy przykład pokazuje konfigurację pliku manifestu z kilkoma zdefiniowanymi linkami do aplikacji:

<application>

    <activity android:name=”MainActivity”>
        <intent-filter android:autoVerify="true">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:scheme="https" />
            <data android:host="www.example.com" />
            <data android:host="mobile.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="www.example2.com" />
        </intent-filter>
    </activity>

    <activity android:name=”SecondActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="account.example.com" />
        </intent-filter>
    </activity>

      <activity android:name=”ThirdActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="https" />
            <data android:host="map.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="market" />
            <data android:host="example.com" />
        </intent-filter>
      </activity>

</application>

Lista hostów, które platforma będzie próbować zweryfikować na podstawie powyższego pliku manifestu:

www.example.com
mobile.example.com
www.example2.com
account.example.com

Lista hostów, których platforma nie będzie próbować zweryfikować na podstawie powyższego pliku manifestu:

map.example.com (it does not have android.intent.category.BROWSABLE)
market://example.com (it does not have either an "http" or "https" scheme)

Więcej informacji o listach instrukcji znajdziesz w artykule Tworzenie listy instrukcji.

Rozwiązywanie typowych błędów implementacji

Jeśli nie możesz potwierdzić linków do aplikacji na Androida, sprawdź, czy nie występują te typowe błędy. W tej sekcji jako zastępczej nazwy domeny używamy example.com. Podczas przeprowadzania tych testów zastąp example.com rzeczywistą nazwą domeny serwera.

Nieprawidłowo skonfigurowany filtr intencji
Sprawdź, czy w elemencie <intent-filter> znajduje się adres URL, który nie należy do Twojej aplikacji.
Nieprawidłowa konfiguracja serwera

Sprawdź konfigurację JSON serwera i upewnij się, że wartość SHA jest prawidłowa.

Sprawdź też, czy example.com. (z kropką na końcu) wyświetla tę samą treść co example.com.

Przekierowania po stronie serwera

System nie weryfikuje żadnych linków aplikacji na Androida w Twojej aplikacji, jeśli skonfigurujesz przekierowanie, np. takie:

  • Od http://example.com do https://example.com
  • Od example.com do www.example.com

Takie działanie chroni bezpieczeństwo aplikacji.

Odporność serwera

Sprawdź, czy serwer może łączyć się z aplikacjami klienckimi.

Linków, których nie można zweryfikować

Do celów testowych możesz celowo dodać linki, których nie można zweryfikować. Pamiętaj, że w przypadku Androida 11 i starszych wersji te linki powodują, że system nie weryfikuje wszystkich linków aplikacji na Androida w Twojej aplikacji.

Nieprawidłowy podpis w pliku assetlinks.json

Sprawdź, czy podpis jest prawidłowy i zgodny z podpisem używanym do podpisywania aplikacji. Typowe błędy to:

  • Podpisywanie aplikacji certyfikatem debugowania i posiadanie tylko podpisu wersji w assetlinks.json.
  • podpisanie dokumentu małymi literami w assetlinks.json, Podpis powinien być zapisany wielkimi literami.
  • Jeśli używasz podpisywania aplikacji przez Google Play, upewnij się, że używasz podpisu, którego Google używa do podpisywania wszystkich wersji Twojej aplikacji. Możesz sprawdzić te szczegóły, w tym pełny fragment kodu JSON, postępując zgodnie z instrukcjami dotyczącymi deklarowania powiązań z witryną.