Để 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 đó ở một vị trí phổ biến trên trang web của bạn. Tệp này khai báo công khai những ứng dụng được phép xử lý đường liên kết cho miền của bạn và 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 trên 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, mảnh 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 dịch vụ của Google sẽ định kỳ truy xuất tệp và hợp nhất cấu hình động 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 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 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 các ứ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 ứng dụng được liên kết:
package_name: Mã ứng dụng được khai báo trong tệpbuild.gradlecủa ứng dụng.sha256_cert_fingerprints: 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 công cụ khoá Java:
keytool -list -v -keystore my-release-key.keystore
- Trường này hỗ trợ nhiều vân tay số, có thể dùng để hỗ trợ nhiều phiên bản ứ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 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
keytoolcục bộ tạo ra 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 mình có đang sử dụng tính năng Ký ứng dụng của Play cho ứng dụng của mình trong tài khoản nhà phát triển trên Play Console, ở phầnRelease > Setup > App signinghay không; nếu có, 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 trang đó.
Tệp assetlinks.json trong ví dụ 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 khai báo mối liên kết với hai ứ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 nhiều tài nguyên trong cùng một máy chủ lưu trữ web.
Ví dụ: ứng dụng 1 có thể khai báo bộ lọc ý định cho https://example.com/articles và ứng dụng 2 có thể khai báo 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. Trang thông tin đầ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ỉ có 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 linh động
Đường liên kết động trong ứng dụng trên 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 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 (cấp độ API 35) trở lên đã cài đặt 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 độ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 quan hệ mới cho Đường liên kết đến tài sản kỹ thuật số 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. - Quy tắc động có thể bao gồm trình so khớp mẫu cho đường dẫn, mảnh và tham số truy vấn.
- Bạn cũng có thể đánh dấu mọi trình 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ề trình so khớp cho đường dẫn (
"/"), mảnh ("#") và tham số truy vấn ("?"), cũng như cá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, 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. Xem mục Khai báo quy tắc động.
Khai báo quy tắc động
Đường liên kết động đến ứng dụng hỗ trợ một tiện ích 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, 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ừ riêng lẻ các 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
- Phím: "/"
- Giá trị: Chuỗi đơn, biểu thức khớp cho đường dẫn URL
- Khớp mảnh
- Phím: "#"
- Giá trị: Chuỗi đơn, biểu thức khớp cho phân mảnh của URL
- So khớp tham số truy vấn
- Phím: "?"
- 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 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 khớp với tất cả các cặp khoá/giá trị trong chuỗi truy vấn, nhưng phải tìm thấy 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ị đúng/sai 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 đây trong trình so khớp mẫu:
- "*" khớp với không 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 khớp
- "?" khớp với bất kỳ ký tự đơn nào
- "?*" khớp với 1 ký tự trở lên
Không có quy định hạn chế nào khác về ký tự đối với các giá trị.
Quy tắc động về đơn đặt hàng
Thứ tự khai báo các quy tắc là rất quan trọng. Android đánh giá từng quy tắc theo thứ tự cho đến khi tìm thấy quy tắc phù hợp.
Ví dụ sau đây cho thấy thứ tự có thể ảnh hưởng đến việc xử lý như thế nào. 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ả 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 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}
]
Nếu không tìm thấy kết quả trùng khớp trong danh sách thành phần đã khai báo, thì URL sẽ không mở ứng dụng. Trong ví dụ sau, không có đường dẫn nào khớp với "/path3" nên 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 nhất định của URL nhưng cho phép tất cả các phần khác. Trong ví dụ sau, 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ả URL đều bị loại trừ khỏi ứng dụng.
dynamic_app_link_components: [
{"/": "/path1", "exclude": true},
{"/": "*"}
]
Xác định phạm vi phù hợp cho các quy tắc linh động
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 trên Android 15 trở lên, bạn cần phải xác định phạm vi phù hợp để các quy tắc đó 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 động được khai báo trong tệp assetlinks.json chỉ có thể chỉ định quy tắc cho
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 độ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ả quy tắc động và quy tắc tĩnh:
- Trong tệp kê khai ứng dụng, hãy đặt 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 có thể tự động thêm các đường dẫn Đường liên kết trong ứng dụng mới vào 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.
Chỉ khai báo dynamic_app_link_components một lần
Để xử lý đúng cách các quy tắc, 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 đố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ư vậ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ợ cho Đường liên kết động trong ứng dụng ngay trong tệp assetlinks.json hiện có. Các trường 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 mở rộng quan hệ mới cho quy tắc động mà không cần thay đổi gì khác.
Thiết bị Android chạy Android 14 (cấp độ API 34 trở xuống) sẽ bỏ qua các trường mở rộng mối quan hệ mới cho quy tắc động, còn thiết bị chạy Android 15 trở lên sẽ hợp nhất các quy tắc đó với 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 dungapplication/json. - Tệp
assetlinks.jsonphải 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. - Bạn phải truy cập được vào tệp
assetlinks.jsonmà không cần chuyển hướng (không có lệnh chuyển hướng 301 hoặc 302). - Nếu App Link của bạn hỗ trợ nhiều tên miền được lưu trữ, thì bạn phải xuất bản tệp
assetlinks.jsontrên mỗi tên miền. Xem phần Hỗ trợ liên kết ứng dụng cho nhiều máy chủ lưu trữ. - Đừ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ư bất kỳ URL nào chỉ có thể truy cập bằng VPN). Giải pháp trong những trường hợp như vậy là định cấu hình biến thể bản dựng để tạo một tệp kê khai khác cho bản dựng phát triển.
Hãy xem các hướng dẫn liên quan sau đây:
- Tạo danh sách câu lệnh
- Trợ lý App Links trong Android Studio
- Công cụ cho nhà phát triển về Đường liên kết trong ứng dụng