Sửa lỗi Android App Links: Khắc phục lỗi 'Intent filter verification failed'

Tại sao liên kết của bạn lại mở trong trình duyệtBạn đã cấu hình Android App Links, nhưng thay vì chuyển đổi mượt mà vào ứng dụng, hệ thống lại bỏ qua nó. Người dùng nhấp vào một liên kết và trình duyệt di động sẽ mở ra—đúng là điều bạn muốn tránh. Nếu bạn kiểm tra Logcat, có thể bạn sẽ thấy một lỗi cụ thể: Intent filter verification failed for domain: example.com.

Android 12 đã thay đổi quy tắc. Trước đây, việc xác thực không thành công đồng nghĩa với việc người dùng sẽ thấy một hộp thoại lựa chọn. Giờ đây, nếu xác thực thất bại, hệ thống sẽ mặc định mở trình duyệt trong mọi trường hợp. Quá trình xác thực là một bước bắt tay (handshake) nghiêm ngặt, trong đó Android lấy một tệp từ máy chủ của bạn để chứng minh bạn sở hữu tên miền đó.

Các nguyên nhân phổ biến khiến xác thực thất bạiDịch vụ Xác thực Intent Filter của hệ thống Android rất nhạy cảm. Quá trình bắt tay sẽ thất bại nếu bất kỳ điều kiện nào sau đây không được đáp ứng:

• Không có HTTPS: Tệp assetlinks.json của bạn phải có thể truy cập được qua kết nối an toàn.- Mã trạng thái không hợp lệ: Máy chủ phải trả về mã 200 OK. Các chuyển hướng (301 hoặc 302) đều bị coi là thất bại.- Sai MIME Type: Header Content-Type phải là application/json.- Sai lệch Fingerprint: Mã vân tay SHA-256 trong tệp JSON không khớp với khóa được sử dụng để ký APK.- Vấn đề tên miền phụ (Subdomain): example.com và www.example.com được coi là các tên miền khác nhau và cả hai đều cần được xác thực.## Cách sửa nhanh: Xác thực thủ công qua ADBĐừng đợi hệ thống thử lại. Bạn có thể kiểm tra trạng thái hiện tại và buộc xác thực lại bằng Android Debug Bridge (ADB) để xem chính xác hệ điều hành đang ghi nhận điều gì. Kiểm tra trạng thái tên miền của bạn:

adb shell pm get-app-links com.your.package.name

Nếu kết quả hiển thị legacy_failure, undefined, hoặc ask, nghĩa là xác thực đã thất bại. Để buộc hệ thống thực hiện lại bước bắt tay trên các thiết bị Android 12+, hãy chạy:

adb shell pm verify-app-links --re-verify com.your.package.name

Các bước sửa lỗi triệt để### 1. Kiểm tra tệp AndroidManifest.xmlXác nhận rằng intent filter của bạn có bao gồm android:autoVerify="true". Thuộc tính này là trình kích hoạt thông báo cho Android đi tìm tệp xác thực của bạn. Nếu không có nó, hệ thống thậm chí sẽ không cố gắng lấy tệp JSON của bạn.

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="example.com" />
</intent-filter>

2. Kiểm tra tệp assetlinks.jsonTệp assetlinks.json của bạn phải nằm tại https://yourdomain.com/.well-known/assetlinks.json. Một sai lầm phổ biến là sử dụng sai mã vân tay SHA-256. Nếu bạn sử dụng Google Play App Signing, mã vân tay cho bản build debug cục bộ sẽ khác với bản build production do Google quản lý.

Trích xuất mã vân tay SHA-256 cục bộ của bạn bằng keytool:

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

Tệp của bạn sẽ trông như thế này (đảm bảo không có dấu phẩy thừa ở cuối):

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.your.package.name",
      "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"
      ]
    }
  }
]

3. Yêu cầu phía Máy chủ (Server-Side)Kiểm tra cấu hình máy chủ của bạn. Nhiều trình lưu trữ tệp tĩnh như S3 hoặc GitHub Pages mặc định để text/plain cho các tệp không có phần mở rộng. Bạn phải thiết lập Content-Type thành application/json một cách rõ ràng. Ngoài ra, hãy đảm bảo tệp robots.txt của bạn không vô tình chặn đường dẫn /.well-known/ đối với các trình thu thập dữ liệu (crawlers).

Cách xác nhận lỗi đã được khắc phụcSau khi triển khai các thay đổi và cài đặt lại ứng dụng, hãy chạy lệnh này để xem trạng thái cuối cùng:

adb shell dumpsys package domain-preferred-apps

Tìm tên gói (package name) của bạn. Bạn cần thấy trạng thái status: always. Điều này có nghĩa là hệ thống đã xác thực thành công tên miền và ứng dụng của bạn hiện là trình xử lý mặc định. Để kiểm tra từ bên ngoài, hãy sử dụng Google Digital Asset Links API:

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls

Nếu API trả về chính xác tên gói của bạn nhưng ứng dụng vẫn thất bại, hãy kiểm tra kỹ xem AndroidManifest.xml của bạn có thiếu tên miền phụ hoặc tên miền thứ hai nào được sử dụng trong các liên kết của bạn hay không.