Xác minh Đường liên kết trong ứng dụng

Khi android:autoVerify="true" xuất hiện trong ít nhất một bộ lọc ý định của ứng dụng, việc cài đặt ứng dụng trên một thiết bị chạy Android 6.0 (cấp độ API 23) trở lên sẽ khiến hệ thống tự động xác minh các máy chủ liên kết với URL trong bộ lọc ý định của ứng dụng. Trên Android 12 trở lên, bạn cũng có thể gọi quy trình xác minh theo cách thủ công để kiểm thử logic xác minh.

Tự động xác minh

Quy trình tự động xác minh của hệ thống bao gồm những việc sau:

  1. Hệ thống kiểm tra tất cả bộ lọc ý định có chứa bất kỳ nội dung nào sau đây:
    • Hành động: android.intent.action.VIEW
    • Danh mục: android.intent.category.BROWSABLE và android.intent.category.DEFAULT
    • Lược đồ dữ liệu: http hoặc https
  2. Đối với mỗi tên máy chủ riêng biệt được tìm thấy trong bộ lọc ý định, Android sẽ truy vấn các trang web tương ứng để tìm tệp Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số) tại https://hostname/.well-known/assetlinks.json.

Sau khi bạn xác nhận danh sách trang web cần liên kết với ứng dụng và xác nhận rằng tệp JSON được lưu trữ là hợp lệ, hãy cài đặt ứng dụng trên thiết bị của bạn. Chờ ít nhất 20 giây để quy trình xác minh không đồng bộ hoàn tất. Sử dụng lệnh sau để kiểm tra xem hệ thống đã xác minh ứng dụng của bạn và đặt các chính sách xử lý đường liên kết chính xác hay chưa:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Xác minh thủ công

Kể từ Android 12, bạn có thể gọi quy trình xác minh miền theo cách thủ công cho một ứng dụng được cài đặt trên thiết bị. Bạn có thể thực hiện quy trình này bất kể ứng dụng của bạn có nhắm đến Android 12 hay không.

Thiết lập kết nối Internet

Để thực hiện quy trình xác minh miền, thiết bị thử nghiệm của bạn phải được kết nối với Internet.

Hỗ trợ quy trình xác minh miền đã cập nhật

Nếu ứng dụng của bạn nhắm đến Android 12 trở lên, hệ thống sẽ tự động sử dụng quy trình xác minh miền đã cập nhật.

Nếu không, bạn có thể bật quy trình xác minh đã cập nhật theo cách thủ công. Để thực hiện điều này, hãy chạy lệnh sau trong cửa sổ dòng lệnh:

adb shell am compat enable 175408749 PACKAGE_NAME

Đặt lại trạng thái của Đường liên kết trong ứng dụng Android trên thiết bị

Trước khi gọi quy trình xác minh miền theo cách thủ công trên một thiết bị, bạn phải đặt lại trạng thái của Đường liên kết trong ứng dụng Android trên thiết bị thử nghiệm. Để thực hiện điều này, hãy chạy lệnh sau trong cửa sổ dòng lệnh:

adb shell pm set-app-links --package PACKAGE_NAME 0 all

Lệnh này sẽ đặt thiết bị ở cùng trạng thái như trước khi người dùng chọn ứng dụng mặc định cho bất kỳ miền nào.

Gọi quy trình xác minh miền

Sau khi đặt lại trạng thái của Đường liên kết trong ứng dụng Android trên một thiết bị, bạn có thể thực hiện quy trình xác minh. Để thực hiện điều này, hãy chạy lệnh sau trong cửa sổ dòng lệnh:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Xem xét kết quả xác minh

Sau khi cho phép tác nhân xác minh có thời gian hoàn tất các yêu cầu, hãy xem xét kết quả xác minh. Để thực hiện việc này, hãy chạy lệnh sau:

adb shell pm get-app-links PACKAGE_NAME

Kết quả của lệnh này tương tự như sau:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

Các miền xác minh thành công có trạng thái xác minh miền là verified. Bất kỳ trạng thái nào khác đều cho biết rằng không thể thực hiện quy trình xác minh miền. Cụ thể, trạng thái none cho biết rằng tác nhân xác minh có thể chưa hoàn tất quy trình xác minh.

Danh sách sau đây cho thấy các giá trị trả về có thể có mà quy trình xác minh miền có thể trả về cho một miền nhất định:

none
Không có thông tin nào được ghi lại cho miền này. Hãy đợi thêm vài phút để tác nhân xác minh hoàn tất các yêu cầu liên quan đến quy trình xác minh miền, và sau đó gọi lại quy trình xác minh miền lần nữa.
verified
Miền được xác minh thành công cho ứng dụng khai báo.
approved
Miền được phê duyệt bắt buộc, thường là bằng cách thực thi lệnh shell.
denied
Miền bị từ chối bắt buộc, thường là bằng cách thực thi lệnh shell.
migrated
Hệ thống giữ nguyên kết quả của một quy trình trước đó sử dụng quy trình xác minh miền cũ.
restored
Miền được phê duyệt sau khi người dùng thực hiện quy trình khôi phục dữ liệu. Giả sử miền đã được xác minh trước đó.
legacy_failure
Miền bị trình xác minh cũ từ chối. Không xác định được lý do cụ thể khiến quy trình xác minh không thành công.
system_configured
Miền được phê duyệt tự động theo cấu hình thiết bị.
Mã lỗi 1024 trở lên

Mã lỗi tuỳ chỉnh dành riêng cho trình xác minh của thiết bị.

Hãy kiểm tra kỹ để đảm bảo bạn đã thiết lập kết nối mạng, rồi gọi lại quy trình xác minh miền.

Yêu cầu người dùng liên kết ứng dụng của bạn với một miền

Một cách khác để ứng dụng của bạn được phê duyệt cho một miền là yêu cầu người dùng liên kết ứng dụng của bạn với miền đó.

Kiểm tra xem ứng dụng của bạn đã được phê duyệt cho miền đó hay chưa

Trước khi nhắc người dùng, hãy kiểm tra xem ứng dụng của bạn có phải là trình xử lý mặc định cho các miền mà bạn xác định trong các phần tử <intent-filter> hay không. Bạn có thể truy vấn trạng thái phê duyệt bằng một trong những phương thức sau:

  • API DomainVerificationManager (trong thời gian chạy).
  • Một chương trình dòng lệnh (trong quá trình kiểm thử).

DomainVerificationManager

Đoạn mã sau đây minh hoạ cách sử dụng API DomainVerificationManager:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the
// user has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user
        // has associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Chương trình dòng lệnh

Khi kiểm thử ứng dụng trong quá trình phát triển, bạn có thể chạy lệnh sau để truy vấn trạng thái xác minh của các miền mà tổ chức của bạn sở hữu:

adb shell pm get-app-links --user cur PACKAGE_NAME

Trong kết quả mẫu sau đây, mặc dù ứng dụng không xác minh được cho miền "example.org", nhưng người dùng 0 đã phê duyệt ứng dụng theo cách thủ công trong phần cài đặt hệ thống và không có gói nào khác được xác minh cho miền đó.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Bạn cũng có thể sử dụng các lệnh shell để mô phỏng quy trình mà người dùng chọn ứng dụng được liên kết với một miền nhất định. Bạn có thể xem giải thích đầy đủ về các lệnh này trong kết quả của adb shell pm.

Cung cấp ngữ cảnh cho yêu cầu

Trước khi bạn đưa ra yêu cầu phê duyệt miền này, hãy cung cấp một số ngữ cảnh cho người dùng. Ví dụ: bạn có thể cho họ thấy màn hình chờ, hộp thoại hoặc phần tử trên giao diện người dùng tương tự để giải thích cho người dùng lý do ứng dụng của bạn nên là trình xử lý mặc định cho một miền cụ thể.

Đưa ra yêu cầu

Sau khi người dùng hiểu những gì ứng dụng của bạn yêu cầu họ làm, hãy đưa ra yêu cầu. Để thực hiện việc này, hãy gọi một ý định bao gồm thao tác theo ý định ACTION_APP_OPEN_BY_DEFAULT_SETTINGS và một chuỗi dữ liệu khớp với package:com.example.pkg cho ứng dụng mục tiêu, như minh hoạ trong đoạn mã sau đây:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Khi ý định được gọi, người dùng sẽ thấy màn hình cài đặt có tên là Mở theo mặc định. Màn hình này chứa một nút chọn có tên là Mở các đường liên kết được hỗ trợ, như minh hoạ trong hình 1.

Khi người dùng bật Mở các đường liên kết được hỗ trợ, một tập hợp hộp đánh dấu sẽ xuất hiện trong phần có tên là Các đường liên kết cần mở trong ứng dụng này. Tại đây, người dùng có thể chọn các miền mà họ muốn liên kết với ứng dụng của bạn. Họ cũng có thể chọn Thêm đường liên kết để thêm miền, như minh hoạ trong hình 2. Sau này, khi người dùng chọn bất kỳ đường liên kết nào trong các miền mà họ thêm, đường liên kết đó sẽ tự động mở trong ứng dụng của bạn.

Khi nút chọn được bật, một phần gần cuối sẽ có các hộp đánh dấu cũng như một nút có tên là &quot;Thêm đường liên kết&quot;
Hình 1. Màn hình cài đặt hệ thống nơi người dùng có thể chọn đường liên kết nào sẽ mở trong ứng dụng của bạn theo mặc định.
Mỗi hộp đánh dấu đại diện cho một miền mà bạn có thể thêm. Các nút của hộp thoại là &quot;Huỷ&quot; và &quot;Thêm&quot;.
Hình 2. Hộp thoại nơi người dùng có thể chọn thêm miền để liên kết với ứng dụng của bạn.

Mở các miền trong ứng dụng mà ứng dụng của bạn không thể xác minh

Chức năng chính của ứng dụng có thể là mở các đường liên kết dưới dạng bên thứ ba mà không có khả năng xác minh các miền được xử lý. Nếu đúng như vậy, hãy giải thích cho người dùng rằng vào thời điểm họ chọn một đường liên kết trang web, họ không thể chọn giữa ứng dụng bên thứ nhất và ứng dụng của bạn (bên thứ ba). Người dùng cần liên kết các miền với ứng dụng bên thứ ba của bạn theo cách thủ công.

Ngoài ra, hãy cân nhắc việc giới thiệu một hộp thoại hoặc hoạt động trampoline cho phép người dùng mở đường liên kết trong ứng dụng bên thứ nhất nếu người dùng muốn làm như vậy, đóng vai trò là proxy. Trước khi thiết lập một hộp thoại hoặc hoạt động trampoline như vậy, hãy thiết lập ứng dụng của bạn để ứng dụng đó có khả năng hiển thị gói vào các ứng dụng bên thứ nhất khớp với bộ lọc ý định trang web của ứng dụng.

Độ trễ khi cập nhật Digital Asset Links (Đường liên kết đến tài sản kỹ thuật số)

Khi bạn cập nhật tệp assetlinks.json trên máy chủ web, thời gian để các thay đổi này được phản ánh trên thiết bị của người dùng cuối sẽ phụ thuộc vào phiên bản hệ điều hành:

  • Android 15 (cấp độ API 35) trở lên: Hệ thống định kỳ xác minh lại các miền ở chế độ nền. Các thay đổi có thể mất tối đa 7 ngày mới có hiệu lực đối với tất cả thiết bị của người dùng cuối do hệ thống lưu vào bộ nhớ đệm và lên lịch xác minh lại.
  • Android 14 (cấp độ API 34) trở xuống: Hệ thống không thực hiện quy trình xác minh lại định kỳ ở chế độ nền. Các bản cập nhật cho tệp thường chỉ được chọn khi ứng dụng được cài đặt hoặc cập nhật.

Kiểm thử bản cập nhật

Để buộc xác minh lại trên một thiết bị cụ thể trong quá trình kiểm thử, bạn có thể gỡ cài đặt rồi cài đặt lại ứng dụng. Tuy nhiên, hãy lưu ý rằng bộ nhớ đệm phía máy chủ vẫn có thể trì hoãn việc gửi tệp assetlinks.json đã cập nhật đến thiết bị, ngay cả sau khi cài đặt lại. Vì bộ nhớ đệm dựa trên thời gian, nên độ trễ thường tự động được giải quyết nếu bạn thử lại sau vài giờ.