Play App Signing後のassetlinks.json SHA-256：TWAのブラウザバーを直す

このガイドで扱う修正は1つだけです。ウェブサイトと、Google Playが配信するビルドとの関連付けです。TWA自体の作り方や、Playによるアプリの審査は扱いません。それぞれ下にリンクした専用のガイドがあります。ここで引用しているGoogleのページはすべて2026年10月16日に確認したもので、出典は末尾にまとめています。

Play版のインストールだけにブラウザバーが出る理由

Chromeは、インストールされたアプリに署名した証明書と、ウェブサイトが公開しているフィンガープリントを比較してTWAを検証します。ChromeのTWAクイックスタートによると、この検証に失敗した場合、ブラウザはサイトをCustom Tab（カスタムタブ）として表示する動作に切り替わります。この切り替えこそが、目に見えるアドレスバーの正体です。

Play App Signingを使う場合、証明書は通常2つあります。アップロードするバンドルには自分のアップロード鍵で署名し、Googleは配信するAPKにアプリ署名鍵で署名します。Chromeのウェブ開発者向けAndroidの概念のページには、Playストアからダウンロードされたときのアプリに対応するのはアプリ署名鍵のフィンガープリントだと書かれています。そのため、ローカルの証明書しか記載していないファイルは、手元では検証に通っても、Playからインストールしたすべてのスマートフォンで失敗します。

2つの鍵が常に異なるわけではありません。Androidのアプリ署名のドキュメントには、同じ鍵をアプリ署名鍵とアップロード鍵の両方として使う構成も説明されています。したがって、どちらの鍵かを思い込まず、実際の証明書を比較することが修正の基本です。

Play Consoleでアプリ署名のSHA-256を見つける

現在、Google自身のドキュメントでは、同じ場所に対して2通りのラベルが記載されています。どちらも、アプリの左側メニューにある Protected with Play から始まります。

古いガイド（Googleのページの一部を含む）では、今も Release > Setup > App signing や Setup > App integrity と書かれています。これらのラベルしか見つからない場合でも、探しているのは古い名前の同じページです。

自分で保有している鍵のフィンガープリントを読む

アップロード鍵やデバッグ鍵の場合は、Javaのkeytoolで同じ形式の値を表示できます。キーストアファイルとエイリアスを自分のものに置き換え、SHA256と書かれた行をコピーしてください。

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

多数のアプリを管理している場合は、Google Play Developer APIでも、Playが生成したAPKの証明書ハッシュ（生成済みAPKリストの certificateSha256Hash フィールド）を取得できます。1件だけ修正するなら、Play Consoleからコピーするほうが簡単です。

正しいassetlinks.jsonを作成して配信する

このファイルは、ステートメントのJSON配列です。TWAの場合、relationは delegate_permission/common.handle_all_urls で、targetはAndroidアプリです。つまり、namespaceの android_app、正確なアプリケーションID、そしてSHA-256フィンガープリントの配列を指定します。最小構成のファイルは次のとおりです。

[
  {
    "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"
      ]
    }
  }
]

com.example.twa を自分のアプリケーションIDに、各プレースホルダーをコロン区切りの完全なSHA-256に置き換えます。Play版のインストールだけ検証できればよい場合は、2つ目のエントリを削除してください。厳密なJSONのみ有効です。コメント、末尾のカンマ、SHA-1の値は使えません。

Googleが求めるファイルの配信方法

• 場所は完全一致。https://your-domain/.well-known/assetlinks.json で、.well-known の先頭のドットも必要です。example.com と www.example.com は別のオリジンなので、アプリが開くオリジンそれぞれにファイルを公開してください。/app/.well-known/ のようなサブディレクトリに置いたコピーは対象になりません。
• 直接のHTTP 200。GoogleのDigital Asset Linksのドキュメントには、「HTTP 200以外のサーバーからの応答はすべてエラーとして扱われ、空のステートメントリストになります」と書かれています。
• リダイレクトなし。301や302の応答はたどられません。httpからhttpsへの転送や、ドメイン名のみのアドレスからwwwへの転送も含みます。
• 有効な証明書チェーンを持つHTTPSと、Content-Type: application/json ヘッダー。200で応答するログインページやHTMLのエラーページは、有効なファイルではありません。

任意のターミナルから実際の応答を確認します。最初のステータス行が200で、コンテンツタイプがJSONであり、その前に3xxがないことが条件です。

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

複数のフィンガープリント、複数のアプリ

Androidのウェブサイトの関連付けガイドには、フィンガープリントの配列について「このフィールドは複数のフィンガープリントに対応しており、デバッグビルドと製品版ビルドなど、アプリの異なるバージョンをサポートするために使用できます」と書かれています。アップロード用やデバッグ用のフィンガープリントは、そのウェブサイトに本当に信頼させたいビルドについてだけ追加してください。別のデバッグパッケージなど、アプリケーションIDが異なるビルドには、配列内にそれ専用のステートメントが必要です。

BubblewrapまたはPWABuilderでTWAを作成した場合

既存のBubblewrapプロジェクトでは、Playのフィンガープリントを追加してファイルを再生成します。

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

ファイルを生成しただけでは配置したことになりません。新しいassetlinks.jsonをウェブサイトにアップロードし、curlで確認してください。bubblewrap validate はPWAを品質基準に照らしてチェックするもので、署名の関連付けはチェックしません。そこで合格しても、フィンガープリントについては何も証明されません。PWABuilderの現在の手順書も署名について同じ点を指摘しており、「.aabファイルをアップロードすると、Google Playがアプリに再署名します」としたうえで、生成されたファイルにPlayのフィンガープリントを追加するよう案内しています。フィンガープリントの修正はウェブサイトの変更であり、アプリのバイナリの変更ではありません。

関連付けを検証してから、Play版のインストールをテストする

関わる層は4つあります。ウェブサイト上のファイル、GoogleのDigital Asset Links API、Android自身のリンク検証、そしてTWAを起動するブラウザです。1つの層を通過しても次の層が通る保証にはならないため、順番に確認し、最後は端末で確かめてください。

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

Android StudioのApp Links Assistant（Tools > App Links Assistant）は、Android App Linksの関連付けとマニフェストをチェックします。それらの確認には便利ですが、TWAが全画面で開くかどうかは教えてくれません。それがわかるのは端末でのテストだけです。

上級：Android自身の検証状態

Android 12以降については、Androidの検証ガイドにApp Links用の次のコマンドが記載されています。パッケージを置き換えて最初の2つを実行し、数分待ってから状態を読み取ります。

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 はAndroidのドメイン検証を表すもので、TWAがブラウザUIなしで開くかどうかを示すものではありません。1024以上のコードは検証ツール固有のエラーであり、SHA-256が間違っているという診断ではありません。TWAそのものについては、上記のChromeのログを使ってください。

フィンガープリントは一致しているのにバーが消えない

バーが表示されていても、SHA-256が間違っているとは限りません。上記のチェックで linked: true が返るのにバーが残っている場合は、次の原因を順に確認してください。

修正したファイルが反映されるまでの時間

GoogleはTWAについて単一の待ち時間を公表していません。複数のキャッシュが関わり、それぞれに独自のルールがあるためです。

• サーバーやCDNが古いファイルを配信し続けている可能性があります。キャッシュを削除し、curlで実際の応答を確認してください。
• Digital Asset Links APIは、各応答の有効期間を maxAge フィールドで示します。
• Android App Linksは別のタイミングで動きます。Androidの検証ガイドによると、Android 15以降では変更がすべての端末に届くまで最大7日かかることがあり、Android 14以前では通常、アプリのインストール時または更新時にファイルが読み込まれます。
• ブラウザが独自の状態を保持している場合があります。Chromeのデータを消去したら解決したという開発者の報告があります。

したがって、キャッシュを削除し、公開中のファイルを確認してから、Google Playから再インストールしてください。テスト端末では、新規インストールやブラウザのデータ消去によって、キャッシュされた状態が原因かどうかを切り分けられます。これは診断の手順であり、すべてのユーザーに求めることではありません。決まった時間数を前提に計画しないでください。

審査落ち、審査、クローズドテスト

assetlinks.jsonがない、または間違っていること自体が審査落ちの原因になるとは、ドキュメントには記載されていません。ドキュメントで説明されているのは、ブラウザUI付きのCustom Tabへの切り替えです。審査は別の問題です。Google Playの機能に関するポリシーには「クラッシュする、強制終了する、フリーズする、その他の異常な動作をするアプリは許可されません」とあり、これは関連付けの状態に関係なく適用されます。正しいフィンガープリントでバーは直りますが、審査が決着するわけではありません。審査落ちの通知を受け取った場合は、メールに記載されたポリシーから確認を始めてください。

古い記事の中には、品質チェックに失敗したTWAをChromeがクラッシュさせると書いているものがあります。ChromiumはそのQualityEnforcerのコードを2023年5月4日に削除しているため、その助言は現在のブラウザの説明ではなく、過去の話として扱ってください。

審査落ちの通知を受け取った場合は、通知に書かれた理由から対処してください。Broken Functionality（機能の不具合）による審査落ちの記事で、最もよくある機能に関する通知を順を追って解説しています。ブラウザバーが出るという理由だけでTWAをWebViewで作り直さないでください。AIビルダーで作ったアプリなら、バイブコーディングしたアプリをGoogle Playで公開する方法で、プロジェクトからPlayまでの全工程を解説しています。

よくある質問

まとめ

Play Consoleのメニューラベルは、このページで最も変わりやすい情報です。上記のルートが現在のConsoleと一致しない場合は、Protected with Playの下にあるPlay app signingを探すか、Console内で「app signing」を検索してください。