Dodawanie filtrów intencji do linków do aplikacji

Linki aplikacji to precyzyjne linki, które korzystają ze schematu HTTP lub HTTPS i są weryfikowane przez Androida jako powiązane z Twoją witryną. Aby zarejestrować obsługę linków do aplikacji, wykonaj te czynności:

Dodaj do manifestu aplikacji co najmniej 1 filtr intencji, który określa domenę lub adresy URL Twojej witryny.
Dodaj autoVerify="true"attribute do elementów filtra intencji. Sygnalizuje to systemowi, że powinien spróbować zweryfikować schemat i domenę hosta w odniesieniu do assetlinks.json konfiguracji witryny.
Deklarowanie powiązań z witrynami.

Poniżej znajdziesz przykład deklaracji linku do aplikacji ze schematami i hostami oraz autoVerify="true":

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- 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 link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

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

Najważniejsze informacje o kodzie

AutoVerify: atrybut android:autoVerify="true jest wymagany w przypadku linków do aplikacji. Informuje system, że powinien spróbować zweryfikować powiązanie między aplikacją a schematami i domenami określonymi w tagach <data>. Zalecamy dodanie autoVerify="true do każdego filtra intencji, który ma być weryfikowalny.
Elementy danych: każdy filtr intencji linków do aplikacji musi zawierać co najmniej 1 element <data>, który określa schematy i formaty hostów pasujące do Twojej zweryfikowanej domeny witryny.
Schematy: filtr intencji musi zawierać elementy <data> dla schematów http i https.
Hosty: możesz opcjonalnie dodać elementy <data>, aby dopasować co najmniej jednego hosta. Użyj symbolu wieloznacznego (*), aby dopasować wiele subdomen (np. *.example.com). System spróbuje zweryfikować każdego hosta na podstawie pliku assetlinks.json w Twojej witrynie. Pamiętaj, że wszelkie kierowanie na poziomie ścieżki powinno być obsługiwane przez plik assetlinks.json (patrz sekcja sprawdzonych metod poniżej).
Wiele hostów: jeśli zadeklarujesz wiele domen hostów, system (na Androidzie 12 lub nowszym) spróbuje zweryfikować każdą z nich. Jeśli jakikolwiek host zostanie zweryfikowany, aplikacja stanie się domyślnym programem obsługującym linki z tego zweryfikowanego hosta. Na Androidzie 11 i starszych weryfikacja nie powiedzie się, jeśli nie uda się zweryfikować choćby jednego hosta.
Wiele filtrów intencji: jeśli chcesz zadeklarować unikalne adresy URL (np. konkretną kombinację schematu i hosta), utwórz osobne filtry, ponieważ wiele elementów <data> w tym samym filtrze intencji jest łączonych, aby uwzględnić wszystkie odmiany ich połączonych atrybutów.

Uwagi dotyczące reguł filtrowania pliku manifestu

Jeśli konfigurujesz filtry do użycia z dynamicznymi linkami aplikacji na Androidzie 15 lub nowszym, pamiętaj, że dynamiczne reguły zadeklarowane w pliku assetlinks.json po stronie serwera nie mogą rozszerzać zakresu reguł URL zadeklarowanych statycznie w pliku manifestu aplikacji.

Z tego powodu zalecamy stosowanie tej metody:

W manifeście aplikacji ustaw jak najszerszy zakres, np. deklarując tylko schemat i domenę.
Aby uzyskać dalsze uściślenia, np. routing na poziomie ścieżki, korzystaj z reguł pliku assetlinks.json po stronie serwera.

Dzięki tej idealnej konfiguracji możesz w razie potrzeby dynamicznie dodawać nowe ścieżki linków do aplikacji w pliku assetlinks.json, wiedząc, że będą one mieścić się w szerokim zakresie ustawionym w manifeście aplikacji.

Obsługa linków do aplikacji w przypadku wielu hostów

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

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>

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.com i mobile.example.com jako akceptowane hosty adresów URL intencji. W związku z tym prawidłowy plik assetlinks.json musi być opublikowany zarówno pod adresem 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>

Alternatywnie, 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ę dla każdej podnazwy example.com (np. foo.example.com), o ile plik assetlinks.json zostanie opublikowany pod adresem 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 jako ostatnia 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 queryIntentActivities. Użytkownik może wybrać preferowaną aplikację z listy pasujących aplikacji, która pojawi się w oknie.

Zgodność wsteczna dynamicznych linków aplikacji w Androidzie 14 i starszych wersjach

Funkcje dynamicznych linków do aplikacji, w tym zaawansowane reguły dopasowywania w assetlinks.json i używanie <uri-relative-filter-group>, są w pełni obsługiwane tylko na Androidzie 15 (poziom interfejsu API 35) i nowszych wersjach.

Na Androidzie 14 (API na poziomie 34) i starszym system bierze pod uwagę tylko elementy scheme i host zadeklarowane w elementach <data> pliku manifestu na potrzeby weryfikacji linków aplikacji. Reguły, wykluczenia i dynamiczne aktualizacje dotyczące konkretnych ścieżek z pliku assetlinks.json nie są stosowane.

Oznacza to, że jeśli plik manifestu zawiera tylko scheme i host, aplikacja może nieoczekiwanie przechwytywać wszystkie ścieżki w zweryfikowanej domenie na urządzeniach z Androidem 14 i starszymi wersjami, niezależnie od reguł dotyczących ścieżek zdefiniowanych w assetlinks.json na urządzeniach z Androidem 15 i nowszymi wersjami.

Strategia rezerwowa dla starszych wersji Androida, która nie wymaga precyzyjnych linków

Aby zapobiec obsłudze przez aplikację wszystkich linków do domeny na Androidzie 14 i starszych wersjach, gdy zamierzasz używać dynamicznych linków aplikacji w przypadku bardziej szczegółowych ścieżek na Androidzie 15 i nowszych wersjach, uwzględnij w filtrze intencji w pliku manifestu ścieżkę, która nie pasuje do żadnego linku. Dodaj element <data> z atrybutem android:path, który prawdopodobnie nigdy nie będzie prawidłową ścieżką dla Twoich linków. Dzięki temu filtr intencji nie będzie pasować do wszystkich ścieżek w starszych wersjach.

Przykład:

<activity
    android:name=".MainActivity"
    android:exported="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" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

Dodając <data android:path="/no_match_for_older_android_versions" />, masz pewność, że na Androidzie 14 i starszych ten filtr intencji nie będzie pasować do żadnych linków przychodzących, a jednocześnie umożliwi weryfikację domeny pod kątem użycia z dynamicznymi linkami aplikacji na Androidzie 15 i nowszym na podstawie zaawansowanych reguł dopasowywania w regułach assetlinks.json.

Migracja istniejących linków do aplikacji

Jeśli masz już linki do aplikacji z określonymi regułami ścieżki (np. android:pathPrefix) w pliku manifestu i chcesz zacząć używać dynamicznych linków do aplikacji na Androidzie 15 lub nowszym, możesz bezpiecznie dodać element <uri-relative-filter-group> do istniejących filtrów intencji.

Ponieważ Android 14 i starsze wersje ignorują element <uri-relative-filter-group>, dotychczasowe linki do aplikacji będą nadal działać dokładnie tak samo na urządzeniach z nowszymi wersjami Androida.

Musisz jednak dokładnie rozważyć, jak Android 15 i nowsze wersje oceniają konfigurację „mieszaną”:

Filtrowanie dwuwarstwowe: na Androidzie 15 i nowszych system ocenia filtry intencji jako sumę. Adres URL przechodzi weryfikację pliku manifestu, jeśli spełnia wymagania dotyczące starszych statycznych tagów <data> lub ogólnych reguł w <uri-relative-filter-group>. Gdy adres URL przejdzie wstępną weryfikację pliku manifestu, system zastosuje reguły dynamiczne zdefiniowane w pliku assetlinks.json jako drugą warstwę szczegółowego filtrowania. Oznacza to, że reguły JSON po stronie serwera ostatecznie decydują, które z tych pasujących adresów URL otworzą aplikację.

Przykład konfiguracji hybrydowej:

<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="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>