Testowanie linków aplikacji

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

Aby przetestować istniejący plik deklaracji, możesz użyć narzędzia do generowania listy deklaracji i testowania.

W sekcjach poniżej opisujemy, jak ręcznie przetestować weryfikację linków do aplikacji. Jeśli wolisz, możesz przetestować weryfikację za pomocą narzędzia Play Deep Links lub Asystenta linków do aplikacji w Android Studio.

Potwierdź listę hostów do zweryfikowania

Podczas testowania należy potwierdzić 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
  • atrybut android:host ze wzorcem adresu URL domeny
  • element działania android.intent.action.VIEW
  • element kategorii android.intent.category.BROWSABLE

Użyj tej listy, aby sprawdzić, czy plik JSON protokołu Digital Asset Links jest dostępny na każdym nazwanym hoście i w każdej subdomenie.

Potwierdź pliki protokołu Digital Asset Links

W przypadku każdej witryny użyj interfejsu API Digital Asset Links, 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://<var>domain.name</var>:<var>optional_port</var>&amp;
   relation=delegate_permission/common.handle_all_urls

W przypadku dynamicznych linków do aplikacji możesz też sprawdzić rozszerzenia relacji.

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urls&return_relation_extensions=true

W ramach procesu testowania możesz sprawdzić bieżące ustawienia systemu dotyczące obsługi linków. Aby uzyskać listę istniejących 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 polecenie robi to samo:

adb shell dumpsys package d

Polecenie zwraca listę każdego użytkownika lub profilu zdefiniowanego na urządzeniu, poprzedzoną nagłówkiem w tym formacie:

App linkages for user 0:

Po tym nagłówku dane wyjściowe używają tego formatu, aby wyświetlić ustawienia obsługi linków dla danego użytkownika:

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

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

  • Package (Pakiet) – identyfikuje aplikację według nazwy pakietu zadeklarowanej w jej manifeście.
  • Domains (Domeny) – pokazuje pełną listę hostów, których linki internetowe obsługuje ta aplikacja, używając spacji jako separatorów.
  • Status (Stan) – pokazuje bieżące ustawienie obsługi linków dla 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 w systemie Android dotyczącym preferencji użytkownika w zakresie powiązań aplikacji. Ta wartość nie wskazuje, czy weryfikacja się powiodła.

Przykład testu

Aby weryfikacja linków do aplikacji się powiodła, system musi być w stanie zweryfikować Twoją aplikację w każdej witrynie, którą określisz w danym filtrze intencji spełniającym kryteria linków do aplikacji. Ten przykład pokazuje konfigurację manifestu z kilkoma zdefiniowanymi linkami do aplikacji:

<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 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 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 deklaracji znajdziesz w artykule Tworzenie listy deklaracji.

Od Androida 17 możesz używać flagi --debug-link z poleceniem menedżera aktywności (am start), aby zdiagnozować, jak system rozpoznaje określony adres URL. To narzędzie zawiera szczegółowe informacje o aplikacjach, które pasują do intencji, oraz o konkretnych regułach z manifestu aplikacji i pliku assetlinks.json (w przypadku dynamicznych linków do aplikacji), które zostały sprawdzone podczas rozpoznawania.

Aby przetestować rozpoznawanie linków w przypadku konkretnego adresu URL, uruchom to polecenie w oknie terminala:

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

Dane wyjściowe diagnostyki są drukowane pod nagłówkiem App Link Resolution Debug i zawierają te sekcje, które pomagają zrozumieć proces rozpoznawania:

  • Target details (Szczegóły miejsca docelowego) – identyfikuje każdą pasującą aplikację według nazwy pakietu i aktywności docelowej.
  • Dopasowanie filtra intencji (AndroidManifest.xml): Pokazuje, które atrybuty statyczne w filtrze intencji manifestu (np. scheme, host, path, pathPrefix lub pathPattern) pasują do identyfikatora URI.
  • App Link Verification (Weryfikacja linków do aplikacji) – pokazuje bieżący stan weryfikacji domeny (np. STATE_SUCCESS).
  • Dynamic App Links (Dynamiczne linki do aplikacji) – jeśli aplikacja używa reguł dopasowywania dynamicznych linków do aplikacji w pliku assetlinks.json, ta sekcja zawiera listę wszystkich reguł, które zostały sprawdzone w odniesieniu do identyfikatora URI. Każda reguła wskazuje pasujące filtry identyfikatorów URI (np. prefiksy ścieżek lub wzorce) oraz pole allow:
    • allow = 0– reguła zezwalająca/uwzględniająca (allow: true). Jeśli ta reguła pasuje, aplikacja może otworzyć identyfikator URI.
    • allow = 1 – reguła blokująca/wykluczająca (allow: false / exclude: true). Jeśli ta reguła pasuje, aplikacja nie może otworzyć identyfikatora URI.
    • Uwaga: pusty ciąg filtra (filter =) oznacza pusty prefiks ścieżki, który pasuje do wszystkich ścieżek w domenie (działa jak symbol wieloznaczny lub reguła domyślna).

Przykładowe dane wyjściowe debugowania

Rozważmy aplikację (com.example.xyzapp) powiązaną z domeną https://xyz.com, która definiuje reguły dynamiczne w pliku assetlinks.json, aby wykluczyć /foo*, a jednocześnie zezwolić na wszystkie inne ścieżki:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.xyzapp",
      "sha256_cert_fingerprints": ["..."]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"/": "/foo*", "exclude": true},
          {"/": "*"}
        ]
      }
    }
  }
]

Podczas diagnozowania adresu URL https://xyz.com/foo za pomocą flagi --debug-link:

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

Polecenie wyświetla następujące zestawienie diagnostyczne:

--- App Link Resolution Debug ---

URI: https://xyz.com/foo
Resolution: Ambiguous (Multiple apps or Browser fallback)
This usually happens when multiple apps can handle the link and no default is set.

All Matching Candidates:

Target:
  Package: com.example.xyzapp
  Activity: com.example.xyzapp.MainActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"
    Host: 'xyz.com' matched android:host="xyz.com"

App Link Verification:
  Verification status: STATE_SUCCESS
  Dynamic App Links:
    -> Matched Rule 0: UriRelativeFilterGroup { allow = 1, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter = /foo }},  }
    -> Matched Rule 1: UriRelativeFilterGroup { allow = 0, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter =  }},  }

Target:
  Package: org.chromium.webview_shell
  Activity: org.chromium.webview_shell.WebViewBrowserActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"

---------------------------------

Starting: Intent { act=android.intent.action.VIEW dat=https://xyz.com/foo }

W tym przykładzie system sprawdził 2 reguły dynamicznych linków aplikacji z pliku assetlinks.json:

  • Reguła 0 (allow = 1, filter = /foo): wygenerowana na podstawie {"/": "/foo*", "exclude": true}, reguła wykluczająca (allow: false) blokująca adresy URL zaczynające się od prefiksu ścieżki /foo.
  • Reguła 1 (allow = 0, filter =): wygenerowana na podstawie {"/": "*"} reguła zezwalająca (allow: true) z pustym prefiksem ścieżki (filter =), która pasuje do wszystkich ścieżek w domenie xyz.com (reguła domyślna).

Jak działa rozpoznawanie w tym scenariuszu:

  1. Zarówno Reguła 0, jak i Reguła 1 pasują do adresu URL https://xyz.com/foo.
  2. Reguły dynamicznych linków aplikacji są sprawdzane po kolei od góry do dołu (zastosowanie ma pierwsza pasująca reguła).
  3. Ponieważ Reguła 0 pojawia się jako pierwsza na liście deklaracji i jest regułą wykluczającą (allow = 1), ma pierwszeństwo przed ogólną regułą zezwalającą (Reguła 1).
  4. W związku z tym aplikacja jest wykluczona z obsługi adresu URL https://xyz.com/foo, co powoduje, że system wraca do przeglądarki lub wyświetla okno wyboru aplikacji.