Dodawanie filtrów intencji do linków do aplikacji

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

  1. Dodaj do pliku manifestu aplikacji co najmniej 1 filtr intencji, który określa domenę lub adresy URL Twojej witryny.
  2. Dodaj autoVerify="true"attribute do elementów filtra intencji. Informuje to system, że powinien spróbować zweryfikować schemat i domeny hosta na podstawie konfiguracji assetlinks.json Twojej witryny.
  3. Zadeklaruj powiązania z witryną.

Oto przykład deklaracji linku aplikacji ze schematami i hostami, a także 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 aplikacji. Informuje on system, że powinien spróbować zweryfikować powiązanie między Twoją aplikacją a schematami i domenami określonymi w <data> tagach. Zalecamy dodanie autoVerify="true" do każdego filtra intencji , który ma być weryfikowalny.
  • Elementy danych: każdy filtr intencji linków aplikacji musi zawierać co najmniej 1 <data> element, który określa schematy i formaty hosta pasujące do Twojej weryfikowalnej domeny.
  • Schematy: filtr intencji musi zawierać elementy <data> dla schematów http i https.

  • Hosty: opcjonalnie możesz dodać elementy <data>, aby dopasować co najmniej 1 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 routing na poziomie ścieżki powinien być obsługiwany przez plik assetlinks.json (patrz sekcja Najlepsze praktyki poniżej).

  • Wiele hostów: jeśli zadeklarujesz wiele domen hosta, system (w Androidzie 12 lub nowszym) spróbuje zweryfikować każdą z nich. Jeśli którykolwiek host zostanie zweryfikowany, aplikacja stanie się domyślnym programem obsługującym linki z tego zweryfikowanego hosta. W Androidzie 11 i starszych wersjach 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), musisz utworzyć osobne filtry, ponieważ wiele elementów <data> w tym samym filtrze intencji jest łączonych w celu uwzględnienia wszystkich odmian ich połączonych atrybutów.

Wskazówki dotyczące reguł filtrowania w manifeście

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

Z tego powodu zalecamy stosowanie tego podejścia:

  • W manifeście aplikacji ustaw jak najszerszy zakres, np. deklarując tylko schemat i domenę.
  • W celu dalszego doprecyzowania, np. routingu na poziomie ścieżki, polegaj na regułach assetlinks.json po stronie serwera.

Dzięki tej idealnej konfiguracji możesz w razie potrzeby dynamicznie dodawać nowe ścieżki linków 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 aplikacji w przypadku wielu hostów

System musi być w stanie zweryfikować hosta określonego w elementach danych filtrów intencji 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 przechodzi do standardowego działania w celu rozwiązania intencji, zgodnie z opisem w artykule Tworzenie precyzyjnych linków do treści aplikacji. Aplikacja może jednak nadal być weryfikowana jako domyślny program obsługujący dowolne wzorce URL zdefiniowane 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>

Obsługa linków 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 listę wielu 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 URL intencji. Dlatego prawidłowy plik assetlinks.json musi być opublikowany zarówno w lokalizacji 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ę w przypadku każdej subdomeny example.com (np. foo.example.com), o ile plik assetlinks.json jest opublikowany w lokalizacji 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ć pomyślnie zweryfikowana. Jeśli jednak aplikacje mogą rozwiązywać dokładnie ten sam host i ścieżkę domeny (jak w przypadku wersji lite i pełnej aplikacji), tylko aplikacja zainstalowana jako ostatnia może rozwiązywać 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, które zawiera wyniki wywołania queryIntentActivities. Użytkownik może wybrać preferowaną aplikację z listy pasujących aplikacji, która pojawi się w oknie.

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

W Androidzie 14 (poziom interfejsu API 34) i starszych wersjach system na potrzeby weryfikacji linków aplikacji bierze pod uwagę tylko scheme i host zadeklarowane w elementach <data> w manifeście. Reguły, wykluczenia i aktualizacje dynamiczne z pliku assetlinks.json dotyczące ścieżki nie są stosowane.

Oznacza to, że jeśli w manifeście określono tylko scheme i host, aplikacja może nieoczekiwanie przechwytywać wszystkie ścieżki zweryfikowanej domeny w Androidzie 14 i starszych wersjach, niezależnie od reguł dotyczących ścieżki zdefiniowanych w pliku assetlinks.json dla Androida 15 i nowszych wersji.

Aby uniemożliwić aplikacji obsługę wszystkich linków do domeny w Androidzie 14 i starszych wersjach, gdy chcesz używać dynamicznych linków aplikacji w przypadku bardziej szczegółowych ścieżek w Androidzie 15 i nowszych wersjach, dodaj do filtra intencji w manifeście ś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 w Androidzie 14 i starszych wersjach ten filtr intencji nie będzie pasować do żadnych przychodzących linków, a jednocześnie umożliwi weryfikację domeny do użycia z dynamicznymi linkami aplikacji w Androidzie 15 i nowszych wersjach na podstawie zaawansowanych reguł dopasowywania w pliku assetlinks.json rules.

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

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

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

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