Định cấu hình mối liên kết trang web và quy tắc linh hoạt

Để hỗ trợ Đường liên kết trong ứng dụng, bạn phải tạo một tệp JSON chứa Đường liên kết đến tài sản kỹ thuật số có tên là assetlinks.json và xuất bản tệp đó ở một vị trí quen thuộc trên trang web của mình. Tệp này công khai khai báo những ứng dụng được phép xử lý đường liên kết cho miền của bạn và các thiết bị Android sẽ truy xuất tệp này từ máy chủ của bạn để xác minh đường liên kết sâu.

Đối với Đường liên kết động trong ứng dụng trong Android 15 trở lên, tệp assetlinks.json cũng là nơi bạn xác định cấu hình quy tắc động, chẳng hạn như trình so khớp mẫu cho đường dẫn, đoạn và tham số truy vấn. Các thiết bị Android chạy Android 15 (cấp độ API 35) trở lên đã cài đặt các dịch vụ của Google sẽ định kỳ truy xuất tệp này và hợp nhất cấu hình động của bạn với cấu hình tĩnh trong tệp kê khai của ứng dụng.

Hướng dẫn này mô tả cách chuẩn bị tệp assetlinks.json và xuất bản tệp đó trên trang web của bạn. Nếu muốn, bạn có thể tạo tệp assetlinks.json từ công cụ Đường liên kết sâu của Play hoặc Trợ lý App Links của Android Studio. Để biết thêm thông tin, hãy xem Công cụ cho nhà phát triển về Đường liên kết trong ứng dụng.

Khai báo mối liên kết với trang web

Bạn phải xuất bản một tệp JSON chứa Đường liên kết đến tài sản kỹ thuật số trên trang web của mình để cho biết những ứng dụng Android được liên kết với trang web và xác minh ý định URL của ứng dụng. Tệp JSON sử dụng các trường sau để xác định các ứng dụng được liên kết:

package_name: Mã ứng dụng được khai báo trong build.gradle tệp của ứng dụng.
sha256_cert_fingerprints: Các vân tay số SHA256 trong chứng chỉ ký của ứng dụng. Bạn có thể sử dụng lệnh sau để tạo vân tay số bằng Java keytool:

keytool -list -v -keystore my-release-key.keystore

Trường này hỗ trợ nhiều vân tay số. Bạn có thể dùng các vân tay số này để hỗ trợ nhiều phiên bản của ứng dụng, chẳng hạn như bản dựng gỡ lỗi và bản dựng phát hành. Nếu bạn đang dùng Tính năng ký ứng dụng của Play cho ứng dụng, thì dấu vân tay chứng chỉ do việc chạy keytool cục bộ tạo ra thường không khớp với dấu vân tay trên thiết bị của người dùng. Bạn có thể xác minh xem mình có đang dùng Tính năng ký ứng dụng của Play cho ứng dụng hay không trong tài khoản nhà phát triển trên Play Console, ở phần Release > Setup > App signing. Nếu có, thì bạn cũng sẽ tìm thấy đoạn mã JSON chính xác của Đường liên kết đến tài sản kỹ thuật số cho ứng dụng của mình trên cùng một trang.

Tệp assetlinks.json ví dụ sau đây cấp quyền mở đường liên kết cho ứng dụng Android com.example:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Liên kết một trang web với nhiều ứng dụng

Một trang web có thể khai báo mối liên kết với nhiều ứng dụng trong cùng một tệp assetlinks.json. Danh sách tệp sau đây cho thấy ví dụ về một tệp câu lệnh khai báo mối liên kết với 2 ứng dụng riêng biệt và nằm tại https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Các ứng dụng khác nhau có thể xử lý đường liên kết cho các tài nguyên khác nhau trong cùng một máy chủ web. Ví dụ: app1 có thể khai báo một bộ lọc ý định cho https://example.com/articles và app2 có thể khai báo một bộ lọc ý định cho https://example.com/videos.

Liên kết nhiều trang web với một ứng dụng

Nhiều trang web có thể khai báo mối liên kết với cùng một ứng dụng trong các tệp assetlinks.json tương ứng. Danh sách tệp sau đây cho thấy ví dụ về cách khai báo mối liên kết của example.com và example.net với app1. Danh sách đầu tiên cho thấy mối liên kết của example.com với app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Danh sách tiếp theo cho thấy mối liên kết của example.net với app1. Chỉ vị trí lưu trữ các tệp này là khác nhau (.com và .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Định cấu hình quy tắc động

Đường liên kết động trong ứng dụng trong Android 15 trở lên cho phép bạn sử dụng các quy tắc so khớp đường liên kết sâu phía máy chủ hoạt động cùng với các quy tắc mà bạn đã xác định tĩnh trong tệp kê khai của ứng dụng. Tệp assetlinks.json là nơi bạn xác định các quy tắc động. Bạn có thể chọn đưa tệp này vào.

Các thiết bị Android chạy Android 15 (cấp độ API 35) trở lên đã cài đặt các dịch vụ của Google sẽ định kỳ truy xuất tệp này từ máy chủ của bạn và hợp nhất cấu hình quy tắc động của bạn với cấu hình tĩnh trong tệp kê khai của ứng dụng. Sau đây là ví dụ về tệp assetlinks.json có các quy tắc động:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

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

Đường liên kết động trong ứng dụng thêm một tiện ích mở rộng mối quan hệ Đường liên kết đến tài sản kỹ thuật số mới có tên là dynamic_app_link_components. Đây là nơi bạn định cấu hình các quy tắc động.
Các quy tắc động có thể bao gồm trình so khớp mẫu cho đường dẫn, đoạn và tham số truy vấn.
Bạn cũng có thể đánh dấu bất kỳ trình so khớp mẫu nào là bị loại trừ để các URL phù hợp không mở ứng dụng của bạn.
Ví dụ này cho thấy các ví dụ về trình so khớp cho đường dẫn ("/"), đoạn ("#"), tham số truy vấn ("?") và cả trình so khớp bị loại trừ ("exclude")
Nếu bất kỳ trường nào trong tệp bị lỗi hoặc trống, thì Android sẽ loại bỏ các quy tắc động và thiết bị sẽ quay lại các quy tắc được xác định tĩnh trong tệp kê khai của ứng dụng.

Các quy tắc động chỉ có thể chỉ định các quy tắc áp dụng trong phạm vi của các miền mà bạn khai báo trong tệp kê khai của ứng dụng. Xem bên dưới.

Khai báo quy tắc động

Đường liên kết động trong ứng dụng hỗ trợ một tiện ích mở rộng mối quan hệ dynamic_app_link_components mới, chứa một mảng các đối tượng quy tắc. Mỗi quy tắc được xác định bằng cách sử dụng trình so khớp mẫu cho đường dẫn, đoạn và tham số truy vấn sẽ mở ứng dụng của bạn. Bạn cũng có thể loại trừ riêng từng trình so khớp để chúng không mở ứng dụng của bạn. Tất cả các trình so khớp này đều không bắt buộc.

So khớp đường dẫn
- Khoá: "/"
- Giá trị: Chuỗi đơn, biểu thức so khớp cho đường dẫn URL
So khớp đoạn
- Khoá: "#"
- Giá trị: Chuỗi đơn, biểu thức so khớp cho phân mảnh của URL
So khớp tham số truy vấn
- Khoá: "?"
- Giá trị: Từ điển để so khớp các cặp khoá/giá trị trong tham số truy vấn URL.
- Ví dụ: từ điển {"?", {"dl": "*", "in_app":"true"} sẽ so khớp chuỗi truy vấn "?in_app=true&dl=abc".
- Thứ tự của các cặp khoá/giá trị trong từ điển không cần phải khớp với thứ tự của các cặp trong chuỗi truy vấn. Ngoài ra, từ điển không cần phải so khớp tất cả các cặp khoá/giá trị trong chuỗi truy vấn, nhưng phải tìm thấy một kết quả so khớp cho mỗi mục trong từ điển.
- Ví dụ: từ điển cũng sẽ so khớp chuỗi truy vấn "?lang=en&in_app=true&tz=pst&dl=abc", nhưng không so khớp chuỗi truy vấn "?lang=en&tz=pst&dl=abc"
Bị loại trừ
- Khoá: "exclude"
- Giá trị: Giá trị true/false không bắt buộc cho mỗi quy tắc được xác định trong dynamic_app_link_components (xem ví dụ).

Bạn có thể sử dụng các ký tự đặc biệt sau trong trình so khớp mẫu:

"*" so khớp 0 hoặc nhiều ký tự cho đến khi tìm thấy ký tự sau ký tự đại diện trong mẫu trong chuỗi so khớp
"?" so khớp bất kỳ ký tự đơn nào
"?*" so khớp 1 hoặc nhiều ký tự

Không có hạn chế nào khác về ký tự đối với giá trị.

Sắp xếp quy tắc động

Thứ tự khai báo các quy tắc là quan trọng. Android đánh giá từng quy tắc theo thứ tự cho đến khi tìm thấy một kết quả so khớp.

Ví dụ sau đây cho thấy cách sắp xếp có thể ảnh hưởng đến việc xử lý. Quy tắc đầu tiên so khớp tất cả các đường dẫn ("*") nhưng loại trừ các kết quả so khớp (exclude: true), nghĩa là quy tắc này loại trừ tất cả các URL khỏi việc mở ứng dụng. Trong trường hợp này, quy tắc thứ hai cho phép "/path1" sẽ không bao giờ được đánh giá.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

Tuy nhiên, trong ví dụ tiếp theo, quy tắc "/path1" được khai báo trước, vì vậy, quy tắc này sẽ được đánh giá trước và sẽ mở ứng dụng cho một URL so khớp "/path1". Quy tắc thứ hai loại trừ tất cả các URL khỏi việc mở ứng dụng sẽ được đánh giá thứ hai, nhưng chỉ khi quy tắc đầu tiên không phải là kết quả so khớp.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Nếu không tìm thấy kết quả so khớp nào trong danh sách các thành phần được khai báo, thì URL sẽ không mở ứng dụng. Trong ví dụ sau đây, không có đường dẫn nào so khớp "/path3", vì vậy, thiết bị sẽ coi đường dẫn này là bị loại trừ.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Hành vi này rất quan trọng nếu bạn muốn dynamic_app_link_components chỉ loại trừ một số phần URL nhưng cho phép tất cả các phần khác. Trong ví dụ sau đây, việc bỏ qua quy tắc cuối cùng để cho phép tất cả các đường dẫn còn lại có nghĩa là tất cả các URL đều bị loại trừ khỏi ứng dụng.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Phạm vi quy tắc động đúng cách

Khi xác định các quy tắc phía máy chủ để sử dụng với Đường liên kết động trong ứng dụng trong Android 15 trở lên, bạn cần phải xác định phạm vi các quy tắc đó một cách thích hợp để chúng hoạt động và bổ sung cho các bộ lọc ý định tĩnh được khai báo trong tệp kê khai ứng dụng của bạn.

Các quy tắc động được khai báo trong tệp assetlinks.json chỉ có thể chỉ định các quy tắc cho những máy chủ mà bạn khai báo trong tệp AndroidManifest.xml của ứng dụng. Các quy tắc động 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 này trên các quy tắc động và tĩnh:

Trong tệp kê khai ứng dụng, hãy đặt các quy tắc có 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 động 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 App Link mới trong tệp assetlinks.json khi cần, biết rằng chúng sẽ nằm trong phạm vi rộng mà bạn đã đặt trong tệp kê khai ứng dụng.

Chỉ khai báo dynamic_app_link_components một lần

Để xử lý đúng các quy tắc, hãy chỉ khai báo một đối tượng dynamic_app_link_components trên các câu lệnh cho một trang web, mối quan hệ và ứng dụng nhất định.

Tìm nhiều câu lệnh cho cùng một trang web, mối quan hệ và ứng dụng, khai báo một đối tượng dynamic_app_link_components.
Tìm nhiều đối tượng dynamic_app_link_components được khai báo trong một câu lệnh

Trong những trường hợp như thế này, Android không đảm bảo cấu hình quy tắc động nào sẽ được sử dụng.

Khả năng tương thích của quy tắc động với các cấu hình Đường liên kết trong ứng dụng trước đó

Nếu đã hỗ trợ Đường liên kết trong ứng dụng, bạn có thể thêm tính năng hỗ trợ Đường liên kết động trong ứng dụng trực tiếp trong tệp assetlinks.json hiện có. Các trường mối quan hệ để xác minh Đường liên kết trong ứng dụng vẫn giữ nguyên và bạn có thể thêm các trường tiện ích mở rộng mối quan hệ mới cho các quy tắc động mà không cần thay đổi gì khác.

Các thiết bị Android chạy Android 14 (cấp độ API 34 trở xuống) bỏ qua các trường tiện ích mở rộng mối quan hệ mới cho các quy tắc động, trong khi các thiết bị chạy Android 15 trở lên sẽ hợp nhất các quy tắc đó với các quy tắc do tệp kê khai xác định.

Xuất bản tệp xác minh JSON

Bạn phải xuất bản tệp xác minh JSON tại vị trí sau:

https://domain.name/.well-known/assetlinks.json

Hãy đảm bảo những điều sau:

Tệp assetlinks.json được phân phát bằng loại nội dung application/json.
Tệp assetlinks.json phải có thể truy cập được qua kết nối HTTPS, bất kể bộ lọc ý định của ứng dụng có khai báo HTTPS là lược đồ dữ liệu hay không.
Tệp assetlinks.json phải có thể truy cập được mà không cần chuyển hướng (không có lệnh chuyển hướng 301 hoặc 302).
Nếu đường liên kết trong ứng dụng hỗ trợ nhiều miền máy chủ, thì bạn phải xuất bản tệp assetlinks.json trên mỗi miền. Xem bài viết Hỗ trợ liên kết ứng dụng cho nhiều máy chủ.
Không xuất bản ứng dụng của bạn bằng các URL kiểm thử trong tệp kê khai mà công chúng có thể không truy cập được (chẳng hạn như bất kỳ URL nào chỉ có thể truy cập được bằng VPN). Một giải pháp thay thế trong những trường hợp như vậy là định cấu hình các biến thể bản dựng để tạo một tệp kê khai khác cho các bản dựng dành cho nhà phát triển.

Xem các hướng dẫn liên quan sau đây: