Thêm bộ lọc ý định cho đường liên kết đến ứng dụng

Đường liên kết trong ứng dụng là các đường liên kết sâu sử dụng giao thức HTTP hoặc HTTPS và được Android xác minh là có liên kết với trang web của bạn. Để đăng ký xử lý Đường liên kết trong ứng dụng, hãy làm theo các bước sau:

  1. Thêm một hoặc nhiều bộ lọc ý định vào tệp kê khai ứng dụng để chỉ định miền hoặc URL của trang web.
  2. Thêm autoVerify="true"attribute vào các phần tử Bộ lọc ý định. Thao tác này báo hiệu cho hệ thống biết rằng hệ thống nên cố gắng xác minh lược đồ và(các) miền lưu trữ dựa trên cấu hình assetlinks.json của trang web.
  3. Khai báo mối liên kết với trang web.

Sau đây là ví dụ về nội dung khai báo Đường liên kết trong ứng dụng có lược đồ và máy chủ lưu trữ cũng như 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>

Các điểm chính về mã

  • AutoVerify: Thuộc tính android:autoVerify="true" là bắt buộc đối với Đường liên kết trong ứng dụng. Thuộc tính này báo hiệu cho hệ thống biết rằng hệ thống nên cố gắng xác minh mối liên kết giữa ứng dụng của bạn với các lược đồ và(các) miền được chỉ định trong thẻ <data>. Bạn nên thêm autoVerify="true" vào mọi Bộ lọc ý định mà bạn muốn xác minh.
  • Phần tử dữ liệu: Mỗi bộ lọc ý định của Đường liên kết trong ứng dụng phải bao gồm một hoặc nhiều phần tử <data> chỉ định lược đồ và định dạng máy chủ lưu trữ khớp với miền trang web có thể xác minh của bạn.
  • Lược đồ: Bộ lọc ý định phải bao gồm các phần tử <data> cho cả lược đồ http và https.
  • Máy chủ lưu trữ: Bạn có thể tuỳ ý thêm các phần tử <data> để so khớp một hoặc nhiều máy chủ lưu trữ. Sử dụng ký tự đại diện (*) để so khớp nhiều miền con (chẳng hạn như *.example.com). Hệ thống sẽ cố gắng xác minh từng máy chủ lưu trữ dựa trên tệp assetlinks.json trên trang web của bạn. Xin lưu ý rằng mọi hoạt động định tuyến ở cấp đường dẫn đều phải do tệp assetlinks.json xử lý (xem phần các phương pháp hay nhất bên dưới).

  • Nhiều tên miền được lưu trữ: Nếu bạn khai báo nhiều tên miền được lưu trữ, thì hệ thống (trên Android 12 trở lên) sẽ cố gắng xác minh từng tên miền. Nếu có bất kỳ máy chủ lưu trữ nào được xác minh, thì ứng dụng sẽ trở thành trình xử lý mặc định cho các đường liên kết từ máy chủ lưu trữ đã xác minh đó. Trên Android 11 trở xuống, quá trình xác minh sẽ không thành công nếu có dù chỉ một máy chủ không xác minh được.

  • Nhiều bộ lọc ý định: Bạn cần tạo các bộ lọc riêng biệt khi muốn khai báo các URL riêng biệt (chẳng hạn như một tổ hợp cụ thể của lược đồ và máy chủ lưu trữ), vì nhiều phần tử <data> trong cùng một bộ lọc ý định sẽ được hợp nhất với nhau để tính đến tất cả các biến thể của thuộc tính kết hợp.

Những điều cần cân nhắc đối với quy tắc lọc tệp kê khai

Nếu bạn đang thiết lập bộ lọc để sử dụng với Đường liên kết động trong ứng dụng trên Android 15 trở lên, thì bạn cần nhớ rằng các quy tắc động được khai báo trong tệp assetlinks.json phía máy chủ không thể mở rộng phạm vi của các quy tắc URL mà bạn khai báo tĩnh trong tệp kê khai ứng dụng.

Vì lý do này, bạn nên sử dụng phương pháp sau:

  • Trong tệp kê khai ứng dụng, hãy đặt phạm vi rộng nhất có thể, chẳng hạn như chỉ khai báo lược đồ và miền
  • Dựa vào các quy tắc assetlinks.json phía máy chủ để tinh chỉnh thêm, chẳng hạn như định tuyến ở cấp đường dẫn.

Với cấu hình lý tưởng này, bạn có thể tự động thêm các đường dẫn Đường liên kết ứng dụng mới trong tệp assetlinks.json khi cần, biết rằng các đường dẫn đó sẽ phù hợp với phạm vi rộng mà bạn đã đặt trong tệp kê khai ứng dụng.

Hỗ trợ Đường liên kết ứng dụng cho nhiều máy chủ lưu trữ

Hệ thống phải có thể xác minh máy chủ lưu trữ được chỉ định trong các phần tử dữ liệu của bộ lọc ý định URL của ứng dụng dựa trên các tệp Digital Asset Links được lưu trữ trên các miền web tương ứng trong bộ lọc ý định đó. Nếu quá trình xác minh không thành công, thì hệ thống sẽ mặc định sử dụng hành vi chuẩn để phân giải ý định, như mô tả trong phần Tạo đường liên kết sâu đến nội dung trong ứng dụng. Tuy nhiên, ứng dụng vẫn có thể được xác minh là trình xử lý mặc định cho bất kỳ mẫu URL nào được xác định trong các bộ lọc ý định khác của ứng dụng.

Ví dụ: một ứng dụng có các bộ lọc ý định sau đây sẽ chỉ vượt qua quy trình xác minh cho https://www.example.com nếu tìm thấy tệp assetlinks.json tại https://www.example.com/.well-known/assetlinks.json chứ không phải 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>

Hỗ trợ liên kết ứng dụng cho nhiều miền con

Giao thức Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số) coi các miền con trong bộ lọc ý định của bạn là các máy chủ lưu trữ riêng biệt. Vì vậy, nếu bộ lọc ý định của bạn liệt kê nhiều máy chủ lưu trữ có các miền con khác nhau, thì bạn phải xuất bản một tệp assetlinks.json hợp lệ trên mỗi miền. Ví dụ: bộ lọc ý định sau đây bao gồm www.example.com và mobile.example.com làm máy chủ lưu trữ URL ý định được chấp nhận. Vì vậy, bạn phải xuất bản một tệp assetlinks.json hợp lệ tại cả https://www.example.com/.well-known/assetlinks.json và 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>

Ngoài ra, nếu khai báo tên máy chủ bằng ký tự đại diện (chẳng hạn như *.example.com), thì bạn phải xuất bản tệp assetlinks.json tại tên máy chủ gốc (example.com). Ví dụ: một ứng dụng có bộ lọc ý định sau đây sẽ vượt qua quy trình xác minh cho mọi tên phụ của example.com (chẳng hạn như foo.example.com) miễn là tệp assetlinks.json được xuất bản tại 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>

Kiểm tra xem có nhiều ứng dụng liên kết với cùng một miền hay không

Nếu bạn xuất bản nhiều ứng dụng và mỗi ứng dụng đều liên kết với cùng một miền, thì mỗi ứng dụng đều có thể được xác minh thành công. Tuy nhiên, nếu các ứng dụng có thể phân giải cùng một máy chủ lưu trữ và đường dẫn miền, như trường hợp của phiên bản rút gọn và phiên bản đầy đủ của một ứng dụng, thì chỉ ứng dụng được cài đặt gần đây nhất mới có thể phân giải ý định web cho miền đó.

Trong trường hợp như vậy, hãy kiểm tra các ứng dụng có thể xung đột trên thiết bị của người dùng, với điều kiện là bạn có chế độ hiển thị gói cần thiết. Sau đó, trong ứng dụng của bạn, hãy hiển thị hộp thoại bộ chọn tuỳ chỉnh chứa kết quả từ việc gọi queryIntentActivities. Người dùng có thể chọn ứng dụng họ muốn trong danh sách các ứng dụng phù hợp xuất hiện trong hộp thoại.

Các tính năng của Đường liên kết động đến ứng dụng, bao gồm cả quy tắc so khớp nâng cao trong assetlinks.json và việc sử dụng <uri-relative-filter-group>, chỉ được hỗ trợ đầy đủ trên Android 15 (cấp độ API 35) trở lên.

Trên Android 14 (cấp độ API 34) trở xuống, hệ thống chỉ xem xét scheme và host được khai báo trong các phần tử <data> của tệp kê khai để xác minh Đường liên kết trong ứng dụng. Các quy tắc, tiêu chí loại trừ và nội dung cập nhật động theo đường dẫn cụ thể từ assetlinks.json sẽ không được áp dụng.

Điều này có nghĩa là nếu tệp kê khai của bạn chỉ chỉ định scheme và host, thì ứng dụng của bạn có thể bất ngờ thu thập tất cả đường dẫn cho miền đã xác minh trên Android 14 trở xuống, bất kể các quy tắc theo đường dẫn cụ thể được xác định trong assetlinks.json cho Android 15 trở lên.

Để ngăn ứng dụng của bạn xử lý tất cả đường liên kết cho một miền trên Android 14 trở xuống khi bạn dự định sử dụng Đường liên kết động trong ứng dụng cho các đường dẫn cụ thể hơn trên Android 15 trở lên, hãy thêm một đường dẫn không khớp vào bộ lọc ý định của tệp kê khai. Thêm phần tử <data> có thuộc tính android:path không có khả năng là đường dẫn hợp lệ cho các đường liên kết của bạn. Điều này đảm bảo rằng bộ lọc ý định không khớp với tất cả đường dẫn trên các phiên bản thấp hơn.

Ví dụ:

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

Bằng cách thêm <data android:path="/no_match_for_older_android_versions" />, bạn đảm bảo rằng trên Android 14 trở xuống, bộ lọc ý định này không khớp với bất kỳ đường liên kết nào đến, trong khi vẫn cho phép xác minh miền để sử dụng với Đường liên kết động đến ứng dụng trên Android 15 trở lên dựa trên các quy tắc so khớp nâng cao trong quy tắc assetlinks.json.

Nếu đã có Đường liên kết trong ứng dụng với các quy tắc đường dẫn cụ thể (chẳng hạn như android:pathPrefix) trong tệp kê khai và muốn bắt đầu sử dụng Đường liên kết động trong ứng dụng trên Android 15 trở lên, bạn có thể thêm phần tử <uri-relative-filter-group> trực tiếp vào bộ lọc ý định hiện có một cách an toàn.

Vì Android 14 trở xuống bỏ qua phần tử <uri-relative-filter-group>, nên các Đường liên kết trong ứng dụng hiện có của bạn sẽ tiếp tục hoạt động đúng như hiện tại trên các thiết bị chạy phiên bản Android thấp hơn.

Tuy nhiên, bạn phải cân nhắc kỹ cách Android 15 trở lên đánh giá cấu hình "kết hợp":

  • Lọc hai lớp: Trên Android 15 trở lên, hệ thống sẽ đánh giá các bộ lọc ý định dưới dạng một tập hợp. Một URL sẽ vượt qua quy trình kiểm tra tệp kê khai nếu URL đó đáp ứng các thẻ <data> tĩnh cũ hoặc các quy tắc chung trong <uri-relative-filter-group>. Sau khi URL vượt qua bước kiểm tra tệp kê khai ban đầu này, hệ thống sẽ áp dụng các quy tắc linh động được xác định trong tệp assetlinks.json của bạn dưới dạng lớp lọc chi tiết thứ hai. Điều này có nghĩa là các quy tắc JSON phía máy chủ sẽ quyết định URL nào trong số các URL khớp đó thực sự mở ứng dụng.

Ví dụ về cấu hình kết hợp:

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