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 thiết bị chạy Android 6.0 (API cấp 23) trở lên sẽ khiến hệ thống tự động xác minh các máy chủ lưu trữ được 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.

Xác minh tự động

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

  1. Hệ thống sẽ kiểm tra tất cả cá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ủ lưu trữ riêng biệt có trong các bộ lọc ý định nêu trên, 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:///.well-known/assetlinks.json.

Sau khi bạn xác nhận danh sách các 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. Đợi í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 có xác minh ứng dụng của bạn và đặt chính sách xử lý đường liên kết chính xác hay không:

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à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

Để xác minh miền, thiết bị thử nghiệm của bạn phải kết nối với Internet.

Hỗ trợ quy trình xác minh miền mới

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 mới.

Nếu không, bạn có thể bật quy trình xác minh mới theo cách thủ công. Để thực hiện việc 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ị kiểm thử. Để 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 đặt thiết bị ở trạng thái giống như trước khi người dùng chọn ứng dụng mặc định cho bất kỳ miền nào.

Triệu hồ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ể tự 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 kết quả xác minh

Sau khi cho phép tác nhân xác minh 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 sẽ 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

Những miền xác minh thành công sẽ có trạng thái xác minh miền là verified. Mọi trạng thái 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 nhân viên xác minh có thể chưa hoàn tất quy trình xác minh.

Danh sách sau đây cho biết 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
Chưa ghi lại phản hồi nào cho miền nà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 việc xác minh miền, sau đó gọi lại quy trình xác minh miền.
verified
Miền đã được xác minh thành công cho ứng dụng khai báo.
approved
Miền này được phê duyệt bắt buộc, thường là bằng cách thực thi một lệnh shell.
denied
Miền bị từ chối bắt buộc, thường là do thực thi một lệnh shell.
migrated
Hệ thống đã giữ lại kết quả của một quy trình trước đó sử dụng phương thức xác minh miền cũ.
restored
Miền được phê duyệt sau khi người dùng thực hiện thao tác khôi phục dữ liệu. Giả sử miền này đã được xác minh trước đó.
legacy_failure
Miền đã bị trình xác minh cũ từ chối. Chưa xác định được lý do cụ thể gây ra lỗi.
system_configured
Cấu hình thiết bị đã tự động phê duyệt miền này.
Mã lỗi từ 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ị.

Kiểm tra kỹ để đảm bảo bạn đã thiết lập kết nối mạng và 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 này hay chưa

Trước khi bạn 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 các 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 ví dụ về đầu ra sau đây, mặc dù ứng dụng không xác minh được 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ể dùng các lệnh shell để mô phỏng quy trình 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 phần giải thích đầy đủ về các lệnh này trong đầu ra của adb shell pm.

Cung cấp bối 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ố thông tin cho người dùng. Ví dụ: bạn có thể cho họ thấy một màn hình khởi động, hộp thoại hoặc một phần tử tương tự trên giao diện người dùng để 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 được những gì ứng dụng yêu cầu họ làm, hãy đưa ra yêu cầu. Để làm vậ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 đích, như minh hoạ trong đoạn mã sau:

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ột màn hình cài đặt có tên là Mở theo mặc định. Màn hình này có 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 chế độ Mở đường liên kết được hỗ trợ, một nhóm hộp đánh dấu sẽ xuất hiện trong phần Đường liên kết để mở trong ứng dụng này. Tại đây, người dùng có thể chọn những 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 đó, 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 cho phép người dùng chọn các miền bổ sung để 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 với tư cách là 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 tại thời điểm đó, khi chọn một đường liên kết trên web, họ không thể chọn giữa ứng dụng của 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 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 đàn hồi cho phép người dùng mở đường liên kết trong ứng dụng của bên thứ nhất nếu người dùng muốn làm như vậy, đóng vai trò là một proxy. Trước khi thiết lập một hộp thoại hoặc hoạt động trung gian 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 đối với các ứng dụng bên thứ nhất khớp với bộ lọc ý định trên web của ứng dụng.