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à đường liên kết sâu sử dụng giao thức HTTP hoặc HTTPS và được Android xác minh là 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:

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.
Thêm autoVerify="true"attribute vào các phần tử bộ lọc ý định. Điều này báo hiệu cho hệ thống rằng hệ thống nên cố gắng xác minh giao thức và(các) miền lưu trữ dựa trên cấu hình assetlinks.json của trang web.
Khai báo mối liên kết với trang web.

Sau đây là ví dụ về một khai báo App Link với các giao thức và máy chủ, 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 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à các giao thức cũng như(các) miền được chỉ định trong các thẻ <data>. Bạn nên thêm autoVerify="true" vào mọi bộ lọc ý định mà bạn muốn có thể 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 <data> chỉ định các giao thức và định dạng máy chủ khớp với miền trang web có thể xác minh của bạn.
Giao thức: Bộ lọc ý định phải bao gồm các phần tử <data> cho cả http và https giao thức.
Máy chủ: Bạn có thể tuỳ ý thêm các phần tử <data> để khớp với một hoặc nhiều máy chủ. Sử dụng ký tự đại diện (*) để khớp với 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ủ 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 được xử lý bằng tệp assetlinks.json (xem phần các phương pháp hay nhất bên dưới).
Nhiều máy chủ: Nếu bạn khai báo nhiều miền lưu trữ, hệ thống (trên Android 12 trở lên) sẽ cố gắng xác minh từng miền. Nếu xác minh được bất kỳ máy chủ nào, ứ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ủ đã 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 không xác minh được dù chỉ một máy chủ.
Nhiều bộ lọc ý định: Điều quan trọng là phải tạo các bộ lọc riêng biệt khi bạn 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 giao thức và máy chủ), vì nhiều phần tử <data> trong cùng một bộ lọc ý định được hợp nhất với nhau để tính đến mọi biến thể của các thuộc tính kết hợp.

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

Nếu bạn đang thiết lập các 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ì điều quan trọng là phải 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 giao thứ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 sẽ có thể thêm động các đường dẫn mới của Đường liên kết trong ứng dụng trong tệp assetlinks.json khi cần, biết rằng các đường dẫn đó sẽ nằm trong phạm vi rộng mà bạn đã đặt trong tệp kê khai ứng dụng.

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

Hệ thống phải có khả năng xác minh máy chủ đượ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, hệ thống sẽ mặc định sử dụng hành vi tiêu chuẩn để phân giải ý định, như mô tả trong bài viết Tạo đường liên kết sâu đến nội dung ứ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ẽ vượt qua quá trình xác minh chỉ 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 nhưng không tìm thấy tệp 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 coi các miền con trong bộ lọc ý định là các máy chủ 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ủ có các miền con khác nhau, thì bạn phải phát hành một 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ủ URL ý định được chấp nhận. Vì vậy, bạn phải phát hành một assetlinks.json 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 bạn 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 phát hành 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 quá trình xác minh cho bất kỳ tên phụ nào của example.com (chẳng hạn như foo.example.com) miễn là tệp assetlinks.json được phát hành 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 được liên kết với cùng một miền hay không

Nếu bạn phát hành nhiều ứng dụng, mỗi ứng dụng được 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 đường dẫn và máy chủ miền, như trường hợp có thể xảy ra với các phiên bản đầy đủ và phiên bản rút gọn 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 trên web cho miền đó.

Trong trường hợp như vậy, hãy kiểm tra xem có ứng dụng nào có thể xung đột trên thiết bị của người dùng hay không, miễn là bạn có quyền hiển thị gói cần thiết. Sau đó, trong ứng dụng, hãy hiển thị một 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 mà họ muốn trong danh sách các ứng dụng phù hợp xuất hiện trong hộp thoại.

Khả năng tương thích ngược của Đường liên kết động trong ứng dụng cho Android 14 trở xuống

Các tính năng của Đường liên kết động trong ứng dụng, bao gồm cá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 App Link. Các quy tắc, lựa chọn loại trừ và bản cập nhật động dành riêng cho đường dẫn từ assetlinks.json 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ể vô tình nắm bắt tất cả cá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 dành riêng cho đường dẫn được xác định trong assetlinks.json cho Android 15 trở lên.

Chiến lược dự phòng cho các phiên bản Android thấp hơn được định cấu hình mà không có đường liên kết sâu

Để ngăn ứng dụng của bạn xử lý tất cả cá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 một phần tử <data> có thuộc tính android:path mà có khả năng không bao giờ là một đườ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ả cá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 nào, đồng thời vẫn cho phép xác minh miền để sử dụng với Đường liên kết động trong ứ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 các quy tắc assetlinks.json.

Di chuyển Đường liên kết trong ứng dụng hiện có

Nếu bạn đã 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, thì bạn có thể thêm phần tử <uri-relative-filter-group> một cách an toàn trực tiếp vào các bộ lọc ý định hiện có.

Vì Android 14 trở xuống bỏ qua phần tử <uri-relative-filter-group>, nên Đường liên kết trong ứng dụng hiện có của bạn sẽ tiếp tục hoạt động chính xác 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 "hỗn hợp":

Lọc hai lớp: Trên Android 15 trở lên, hệ thống đá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 bước kiểm tra tệp kê khai nếu đáp ứng một trong hai điều kiện: thẻ <data> tĩnh cũ hoặc các quy tắc rộng 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 động được xác định trong tệp assetlinks.json 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 được so 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>