為應用程式連結新增意圖篩選器

應用程式連結是使用 HTTP 或 HTTPS 配置的深層連結，且經 Android 驗證與您的網站相關聯。如要註冊處理應用程式連結，請按照下列步驟操作：

  1. 在應用程式資訊清單中新增一或多個意圖篩選器，指定網站網域或網址。
  2. 將 autoVerify="true"attribute 新增至意圖篩選器元素。這會向系統發出信號，表示系統應嘗試根據網站的 assetlinks.json 設定驗證配置和主機網域。
  3. 宣告網站關聯。

以下是包含配置、主機和 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>

程式碼重點

  • AutoVerify：應用程式連結必須具備 android:autoVerify="true" 屬性。這會向系統發出信號，表示系統應嘗試驗證應用程式與 <data> 標記中指定的配置和網域之間的關聯。建議您在每個要驗證的意圖篩選器中加入 autoVerify="true"。
  • 資料元素：每個應用程式連結意圖篩選器都必須包含一或多個 <data> 元素，用於指定與可驗證網站網域相符的配置和主機格式。
  • 配置：意圖篩選器必須包含 http 和 https 配置的 <data> 元素。

  • 主機：您可以視需要新增 <data> 元素，比對一或多個主機。使用萬用字元 (*) 比對多個子網域 (例如 *.example.com)。系統會嘗試根據網站上的 assetlinks.json 檔案驗證每個主機。請注意，任何路徑層級的轉送都應由 assetlinks.json 檔案處理 (請參閱下方的最佳做法一節)。

  • 多個代管網域：如果您宣告多個代管網域，系統 (Android 12 以上版本) 會嘗試驗證每個網域。只要有任何主機通過驗證，應用程式就會成為該主機連結的預設處理常式。在 Android 11 以下版本中，只要有一個主機無法驗證，驗證就會失敗。

  • 多個意圖篩選器：如果您想宣告不重複的網址 (例如配置和主機的特定組合)，請務必建立個別篩選器，因為同一意圖篩選器中的多個 <data> 元素會合併在一起，以反映其組合屬性的所有變化版本。

資訊清單篩選規則注意事項

如果您要設定篩選器，以便在 Android 15 以上版本中使用動態應用程式連結，請務必記住，在伺服器端 assetlinks.json 檔案中宣告的動態規則，無法擴充您在應用程式資訊清單中靜態宣告的網址規則範圍。

因此，建議您採用以下方法：

  • 在應用程式資訊清單中，盡可能設定最廣泛的範圍，例如僅宣告配置和網域
  • 依賴伺服器端 assetlinks.json 規則進一步調整，例如路徑層級轉送。

採用這種理想設定後，您就能視需要動態新增 assetlinks.json 檔案中的應用程式連結路徑，並確保這些路徑符合應用程式資訊清單中設定的廣泛範圍。

支援多個主機的應用程式連結

系統必須能夠根據意圖篩選器中各個網域代管的 Digital Asset Links 檔案，驗證應用程式網址意圖篩選器資料元素中指定的主機。如果驗證失敗，系統會預設為標準行為來解析意圖，如「建立應用程式內容的深層連結」一文所述。不過，系統仍可將應用程式驗證為預設處理常式，處理應用程式其他意圖篩選器中定義的任何網址模式。

舉例來說，如果應用程式具有下列意圖篩選器，且在 https://www.example.com/.well-known/assetlinks.json 找到 assetlinks.json 檔案，但在 https://www.example.net/.well-known/assetlinks.json 找不到，則只有 https://www.example.com 會通過驗證：

<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>

支援多個子網域的應用程式連結

Digital Asset Links 通訊協定會將意圖篩選器中的子網域視為獨立的主機。因此，如果意圖篩選器列出多個具有不同子網域的主機，您必須在每個網域上發布有效的 assetlinks.json。舉例來說，下列意圖篩選器包含 www.example.com 和 mobile.example.com 做為接受的意圖網址主機。因此，有效的 assetlinks.json 必須同時發布在 https://www.example.com/.well-known/assetlinks.json 和 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>

或者，如果您使用萬用字元 (例如 *.example.com) 宣告主機名稱，則必須在根主機名稱 (example.com) 發布 assetlinks.json 檔案。舉例來說，如果應用程式具有下列意圖篩選器，只要 assetlinks.json 檔案發布在 https://example.com/.well-known/assetlinks.json，就會通過 example.com 任何子名稱 (例如 foo.example.com) 的驗證：

<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>

檢查是否有與同一個網域相關聯的多個應用程式

如果您發布的多個應用程式都與同一個網域相關聯，則每個應用程式都能成功通過驗證。不過，如果應用程式可以解析完全相同的網域主機和路徑 (例如應用程式的精簡版和完整版)，則只有最近安裝的應用程式可以解析該網域的網頁意圖。

在這種情況下，請檢查使用者裝置上是否有衝突的應用程式，前提是您必須具備必要的套件瀏覽權限。接著，在應用程式中顯示自訂選擇器對話方塊，其中包含呼叫 queryIntentActivities 的結果。使用者可以從對話方塊中顯示的相符應用程式清單中，選取偏好的應用程式。

動態應用程式連結功能 (包括 assetlinks.json 中的進階比對規則和 <uri-relative-filter-group> 的使用) 僅在 Android 15 (API 級別 35) 以上版本中受到完整支援。

在 Android 14 (API 級別 34) 以下版本中，系統只會考量資訊清單 <data> 元素中宣告的 scheme 和 host，用於驗證應用程式連結。系統不會套用 assetlinks.json 中的路徑專屬規則、排除項目和動態更新。

也就是說，如果資訊清單僅指定 scheme 和 host，應用程式可能會在 Android 14 以下版本中，意外擷取已驗證網域的所有路徑，無論 assetlinks.json 中為 Android 15 以上版本定義的路徑特定規則為何。

如果您打算在 Android 15 以上版本，針對更具體的路徑使用動態應用程式連結，請在資訊清單的意圖篩選器中加入不相符的路徑，以免應用程式在 Android 14 以下版本處理網域的所有連結。新增 <data> 元素，並加入不太可能成為連結有效路徑的 android:path 屬性。這可確保意圖篩選器不會比對較低版本的所有路徑。

範例：

<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>

新增 <data android:path="/no_match_for_older_android_versions" /> 可確保在 Android 14 以下版本中，這個意圖篩選器不會與任何傳入連結相符，同時仍可根據 assetlinks.json 規則中的進階比對規則，驗證網域是否可在 Android 15 以上版本中與動態應用程式連結搭配使用。

如果資訊清單中已有特定路徑規則 (例如 android:pathPrefix) 的應用程式連結，且想在 Android 15 以上版本開始使用動態應用程式連結，可以直接將 <uri-relative-filter-group> 元素新增至現有意圖篩選器。

由於 Android 14 以下版本會忽略 <uri-relative-filter-group> 元素，因此在搭載較低 Android 版本的裝置上，現有的應用程式連結仍會照常運作。

不過，您必須仔細考量 Android 15 以上版本如何評估「混合」設定：

  • 雙層篩選：在 Android 15 以上版本中，系統會將意圖篩選器視為聯集進行評估。如果網址符合舊版靜態 <data> 標記或 <uri-relative-filter-group> 中的廣泛規則，就會通過資訊清單檢查。網址通過這項初始資訊清單檢查後，系統會套用 assetlinks.json 檔案中定義的動態規則，做為第二層精細篩選。這表示伺服器端 JSON 規則最終會決定哪些相符的網址會實際開啟應用程式。

混合型設定範例：

<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>