Đị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 Đườ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 này ở một vị trí quen thuộc trên trang web của bạn. 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 đến ứ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 (API cấp 35) trở lên đã cài đặt các dịch vụ của Google sẽ định kỳ truy xuất tệp 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 một tệp assetlinks.json bằng 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 bài viết Công cụ cho nhà phát triển Đườ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 tệp JSON Đườ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 tệp build.gradle của ứng dụng.
  • sha256_cert_fingerprints: Vân tay SHA256 của chứng chỉ ký ứng dụng. Bạn có thể dùng lệnh sau đây để tạo vân tay bằng keytool của Java:

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

  • Trường này hỗ trợ nhiều dấu vân tay. Bạn có thể dùng dấu vân tay để hỗ trợ các phiên bản khác nhau của ứng dụng, chẳng hạn như bản gỡ lỗi và bản phát hành công khai. Nếu bạn đang sử 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ỉ được tạo ra khi chạy keytool cục bộ thường sẽ 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 bạn có đang dùng tính năng Ký ứng dụng Play cho ứng dụng của mình trong tài khoản nhà phát triển trên Play Console ở phần Release > Setup > App signing hay không. Nếu có, thì bạn cũng sẽ 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 sau đây cấp quyền mở đường liên kết cho một ứ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ủ lưu trữ 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ỉ khác nhau ở vị trí lưu trữ các tệp này (.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 linh động

Đường liên kết động đến ứ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 ứng dụng. Tệp assetlinks.json là nơi bạn xác định các quy tắc linh động. Bạn không bắt buộc phải thêm thông tin này.

Các thiết bị Android chạy Android 15 (API cấp 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 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 linh hoạt:

[
  {
    "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 sẽ thêm một tiện ích mối quan hệ Digital Asset Links 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 các đối tượng 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 mọi đối tượng so khớp mẫu là bị loại trừ, để các URL khớp không mở ứng dụng của bạn.
  • Ví dụ này cho thấy các ví dụ về bộ so khớp cho đường dẫn ("/"), mảnh ("#") và tham số truy vấn ("?"), cũng như bộ 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, 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 những 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. Hãy xem bên dưới.

Khai báo các quy tắc linh động

Đường liên kết đến ứng dụng động hỗ trợ một tiện ích 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 các mẫu so khớp cho đường dẫn, mảnh và tham số truy vấn sẽ mở ứng dụng của bạn. Bạn cũng có thể loại trừ từng mẫu so khớp để chúng không mở ứng dụng của bạn. Tất cả những điều 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 mảnh
    • Khoá: "#"
    • Giá trị: Chuỗi đơn, biểu thức so khớp cho phân đoạn 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ẽ khớp với 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 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ả khớp cho mỗi mục từ điển.
    • Ví dụ: từ điển cũng sẽ khớp với chuỗi truy vấn "?lang=en&in_app=true&tz=pst&dl=abc", nhưng không khớp với 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 bộ so khớp mẫu:

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

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

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

Thứ tự khai báo các quy tắc có ý nghĩa quan trọng. Android đánh giá từng quy tắc theo thứ tự cho đến khi tìm thấy một quy tắc trùng 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 khớp với tất cả các đường dẫn ("*") nhưng loại trừ các kết quả trùng 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, nên quy tắc này sẽ được đánh giá trước và sẽ mở ứng dụng cho một URL khớp với "/path1". Quy tắc thứ hai (loại trừ tất 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 khớp.

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

Xác định phạm vi quy tắc linh động một cách phù hợp

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 đến ứng dụng trong Android 15 trở lên, bạn cần phải đặt phạm vi cho 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ác quy tắc linh độ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ủ lưu trữ mà bạn khai báo trong tệp AndroidManifest.xml của ứng dụng. Các quy tắc linh độ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 cho 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ể linh hoạt thêm các đường dẫn Đường liên kết đến ứng dụng mới 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.

Để xử lý đúng các quy tắc, bạn chỉ nên khai báo một đối tượng dynamic_app_link_components trong 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 duy nhất

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

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 đến ứ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ợ cho Đường liên kết động đến ứng dụng ngay trong tệp assetlinks.json hiện có. Các trường mối quan hệ để xác minh Đường liên kết đến ứng dụng vẫn giữ nguyên và bạn có thể thêm các trườ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 (API cấp 34 trở xuống) sẽ bỏ qua các trường tiện ích mới về mối quan hệ đối với 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.
  • Bạn phải truy cập được vào tệp assetlinks.json qua kết nối HTTPS, bất kể bộ lọc ý định của ứng dụng có khai báo HTTPS dưới dạng lược đồ dữ liệu hay không.
  • Bạn phải truy cập được vào tệp assetlinks.json mà không cần lệnh chuyển hướng (không có lệnh chuyển hướng 301 hoặc 302).
  • Nếu đường liên kết đến ứng dụng của bạn hỗ trợ nhiều miền lưu trữ, thì bạn phải xuất bản tệp assetlinks.json trên từng miền. Xem phần Hỗ trợ tính năng liên kết ứng dụng cho nhiều máy chủ lưu trữ.
  • Không xuất bản ứng dụng 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ư mọi URL chỉ có thể truy cập bằng VPN). Trong những trường hợp như vậy, giải pháp 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.

Hãy xem các hướng dẫn có liên quan sau đây: