SHA-256 trong assetlinks.json sau Play App Signing: sửa thanh trình duyệt của TWA

Hướng dẫn này chỉ xử lý một việc: liên kết giữa website của bạn và bản build mà Google Play phân phối. Bài không đề cập đến việc tự xây dựng TWA hay quá trình Google Play xem xét ứng dụng, vì hai chủ đề đó có hướng dẫn riêng được liên kết bên dưới. Mọi trang của Google được trích dẫn ở đây đều đã được kiểm tra vào Ngày 16 tháng 10 năm 2026, và danh sách nguồn nằm ở cuối bài.

Vì sao thanh trình duyệt chỉ xuất hiện trên bản cài từ Play

Chrome xác minh một TWA bằng cách so sánh chứng chỉ đã ký ứng dụng được cài với các dấu vân tay mà website của bạn công bố. Khi bước kiểm tra này thất bại, hướng dẫn bắt đầu nhanh về TWA của Chrome cho biết trình duyệt sẽ chuyển sang hiển thị trang web của bạn dưới dạng Custom Tab. Phương án dự phòng đó chính là thanh địa chỉ bạn nhìn thấy.

Với Play App Signing thường có hai chứng chỉ. Bạn ký gói tải lên bằng khóa tải lên (upload key), còn Google ký các APK mà Google phân phối bằng khóa ký ứng dụng (app signing key). Trang Khái niệm Android cho nhà phát triển web của Chrome cho biết dấu vân tay của khóa ký ứng dụng là dấu vân tay tương ứng với ứng dụng của bạn khi được tải xuống từ Play Store. Vì vậy, một tệp chỉ liệt kê chứng chỉ trên máy của bạn sẽ chạy đúng trên bàn làm việc của bạn nhưng thất bại trên mọi điện thoại cài từ Play.

Hai khóa này không phải lúc nào cũng khác nhau. Tài liệu về ký ứng dụng của Android mô tả những cấu hình trong đó cùng một khóa đóng vai trò vừa là khóa ký ứng dụng vừa là khóa tải lên. Vì thế, cách sửa là so sánh các chứng chỉ thật, chứ không phải đoán xem bạn đang có loại nào.

Tìm SHA-256 ký ứng dụng trong Play Console

Tài liệu của chính Google hiện đưa ra hai nhãn cho cùng một vị trí. Cả hai đều bắt đầu từ Protected with Play trong menu bên trái của ứng dụng.

Các hướng dẫn cũ hơn, kể cả một số trang của Google, vẫn ghi Release > Setup > App signing hoặc Setup > App integrity. Nếu bạn chỉ thấy những nhãn đó, thì đó vẫn là cùng một trang dưới tên cũ.

Đọc dấu vân tay của khóa do chính bạn giữ

Với khóa tải lên hoặc khóa debug, công cụ keytool của Java in ra cùng định dạng. Thay tệp keystore và alias bằng của bạn, rồi sao chép dòng có nhãn SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Nếu bạn quản lý nhiều ứng dụng, Google Play Developer API cũng có thể trả về mã băm chứng chỉ của các APK do Play tạo ra (trường certificateSha256Hash trong danh sách APK được tạo). Để sửa một lần, sao chép từ Play Console sẽ đơn giản hơn.

Viết và phân phát assetlinks.json đúng cách

Tệp này là một mảng JSON gồm các câu lệnh (statement). Với TWA, quan hệ (relation) là delegate_permission/common.handle_all_urls, và đích (target) là ứng dụng Android của bạn: namespace android_app, đúng application ID của bạn và một mảng dấu vân tay SHA-256. Một tệp tối thiểu trông như sau:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Thay com.example.twa bằng application ID của bạn và thay mỗi giá trị giữ chỗ bằng một SHA-256 đầy đủ, ngăn cách bằng dấu hai chấm. Xóa mục thứ hai nếu bạn chỉ cần các bản cài từ Play được xác minh. Chỉ dùng JSON chuẩn nghiêm ngặt: không chú thích, không dấu phẩy thừa ở cuối, không giá trị SHA-1.

Google yêu cầu phân phát tệp như thế nào

• Đúng vị trí. https://your-domain/.well-known/assetlinks.json, có dấu chấm trong .well-known. example.com và www.example.com là hai origin khác nhau; hãy đăng tệp trên từng origin mà ứng dụng của bạn mở. Một bản sao trong thư mục con như /app/.well-known/ không được tính.
• Mã HTTP 200 trực tiếp. Tài liệu Digital Asset Links của Google viết: “Mọi phản hồi từ máy chủ ngoài HTTP 200 đều bị coi là lỗi và sẽ dẫn đến danh sách câu lệnh trống.”
• Không chuyển hướng. Các phản hồi 301 và 302 không được theo. Điều này bao gồm cả bước chuyển từ http sang https và từ tên miền trần sang www.
• HTTPS với chuỗi chứng chỉ hợp lệ, và header Content-Type: application/json. Một trang đăng nhập hoặc trang lỗi HTML trả về 200 không phải là tệp hợp lệ.

Kiểm tra phản hồi thực tế từ bất kỳ terminal nào. Dòng trạng thái đầu tiên phải là 200 và kiểu nội dung phải là JSON, không có mã 3xx nào trước đó:

curl -sI https://example.com/.well-known/assetlinks.json

Nhiều dấu vân tay, nhiều ứng dụng

Hướng dẫn liên kết website của Android viết về mảng dấu vân tay: “Trường này hỗ trợ nhiều dấu vân tay, có thể dùng để hỗ trợ các phiên bản khác nhau của ứng dụng, chẳng hạn như bản build debug và bản build chính thức.” Chỉ thêm dấu vân tay của khóa tải lên hoặc khóa debug cho những bản build mà bạn thực sự muốn website đó tin cậy. Một bản build có application ID khác, chẳng hạn một gói debug riêng, cần câu lệnh riêng trong mảng.

Nếu bạn tạo TWA bằng Bubblewrap hoặc PWABuilder

Trong một dự án Bubblewrap có sẵn, hãy thêm dấu vân tay của Play và tạo lại tệp:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Tạo tệp chưa phải là triển khai tệp: hãy tải assetlinks.json mới lên website và kiểm tra bằng curl. bubblewrap validate kiểm tra PWA của bạn theo các tiêu chí chất lượng; lệnh này không kiểm tra liên kết ký, nên việc vượt qua bước đó không chứng minh được gì về dấu vân tay. Hướng dẫn hiện tại của PWABuilder cũng nêu cùng ý về việc ký, “Sau khi bạn tải tệp .aab lên, Google Play sẽ ký lại ứng dụng của bạn”, và yêu cầu bạn thêm dấu vân tay của Play vào tệp được tạo. Sửa dấu vân tay là thay đổi trên website, không phải trên tệp nhị phân của ứng dụng.

Xác minh liên kết, rồi thử bản cài từ Play

Có bốn lớp liên quan: tệp trên website, Digital Asset Links API của Google, cơ chế xác minh liên kết của chính Android và trình duyệt khởi chạy TWA. Vượt qua một lớp không chứng minh lớp tiếp theo cũng ổn, vì vậy hãy kiểm tra theo thứ tự và kết thúc trên thiết bị.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

App Links Assistant của Android Studio (Tools > App Links Assistant) kiểm tra liên kết Android App Links và manifest của bạn. Công cụ này hữu ích cho những việc đó, nhưng không cho bạn biết TWA có mở toàn màn hình hay không; chỉ việc thử trên thiết bị mới cho biết điều đó.

Nâng cao: trạng thái xác minh của chính Android

Trên Android 12 trở lên, hướng dẫn xác minh của Android ghi nhận các lệnh sau cho App Links. Thay tên gói, chạy hai lệnh đầu, chờ vài phút, rồi đọc trạng thái:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified mô tả việc xác minh tên miền của Android, không cho biết TWA có mở mà không có giao diện trình duyệt hay không. Các mã từ 1024 trở lên là lỗi riêng của trình xác minh, không phải chẩn đoán SHA-256 bị sai. Với chính TWA, hãy dùng nhật ký Chrome ở trên.

Dấu vân tay khớp nhưng thanh vẫn còn

Thanh hiển thị không chứng minh SHA-256 bị sai. Khi bước kiểm tra ở trên trả về linked: true mà thanh vẫn còn, hãy lần lượt xem xét các nguyên nhân sau.

Bao lâu thì tệp đã sửa có hiệu lực

Google không công bố một thời gian chờ duy nhất cho TWA, vì có nhiều bộ nhớ đệm liên quan và mỗi bộ có quy tắc riêng:

• Máy chủ hoặc CDN của bạn có thể vẫn phân phát tệp cũ. Hãy xóa bộ nhớ đệm và xác nhận phản hồi thực tế bằng curl.
• Digital Asset Links API cho biết mỗi phản hồi còn hiệu lực trong bao lâu qua trường maxAge.
• Android App Links có thời gian riêng. Hướng dẫn xác minh của Android cho biết trên Android 15 trở lên, thay đổi có thể mất đến bảy ngày để đến được mọi thiết bị, còn trên Android 14 trở xuống, tệp thường được đọc lại khi ứng dụng được cài đặt hoặc cập nhật.
• Trình duyệt có thể giữ trạng thái riêng. Một nhà phát triển báo cáo đã thành công sau khi xóa dữ liệu của Chrome.

Vì vậy, hãy xóa bộ nhớ đệm, xác nhận tệp đang chạy thực tế và cài lại từ Google Play. Trên thiết bị thử nghiệm, cài mới hoặc xóa dữ liệu trình duyệt có thể loại trừ trạng thái lưu trong bộ nhớ đệm; đó là một bước chẩn đoán, không phải điều nên yêu cầu mọi người dùng làm. Đừng lên kế hoạch dựa trên một số giờ cố định.

Bị từ chối, xem xét và thử nghiệm khép kín

Tài liệu không ghi nhận việc thiếu hoặc sai assetlinks.json tự nó là nguyên nhân khiến ứng dụng bị từ chối. Điều tài liệu mô tả là việc chuyển sang Custom Tab có giao diện trình duyệt. Quá trình xem xét là một câu hỏi riêng: chính sách về chức năng của Google Play viết “Chúng tôi không cho phép những ứng dụng gặp sự cố, buộc đóng, bị treo hoặc hoạt động bất thường theo cách khác,” và điều đó áp dụng bất kể trạng thái liên kết của bạn ra sao. Dấu vân tay đúng sửa được thanh trình duyệt; nó không quyết định kết quả xem xét. Nếu bạn đã bị từ chối, hãy bắt đầu từ chính sách được nêu trong email.

Một số bài viết cũ nói rằng Chrome sẽ làm TWA gặp sự cố nếu không đạt các bước kiểm tra chất lượng. Chromium đã gỡ bỏ mã QualityEnforcer đó vào ngày 4 tháng 5 năm 2023, vì vậy hãy xem lời khuyên đó là thông tin lịch sử, không phải mô tả về các trình duyệt hiện nay.

Nếu bạn đã bị từ chối, hãy xử lý dựa trên lý do trong thông báo: bài về lỗi bị từ chối do Broken Functionality hướng dẫn chi tiết thông báo về chức năng phổ biến nhất. Đừng xây dựng lại TWA thành WebView chỉ vì một thanh trình duyệt. Nếu ứng dụng của bạn được tạo bằng công cụ AI, bài đăng ứng dụng vibe coding lên Google Play trình bày toàn bộ lộ trình từ dự án đến Play.

Câu hỏi thường gặp

Tóm lại

Nhãn menu của Play Console là thông tin thay đổi nhanh nhất trên trang này. Nếu các đường dẫn ở trên không còn khớp với Console của bạn, hãy tìm Play app signing trong mục Protected with Play, hoặc tìm kiếm "app signing" trong Console.