KappSナレッジベース · ブログ

Androidアプリリンク2026:ステップバイステップの検証チュートリアル

ブログ チュートリアル

Android App Linkは、Googleが所有権の証明として認める唯一のディープリンク機構です。アプリが処理を許可するHTTPSホストを宣言し、そのホストにDigital Asset Linksステートメントを公開すると、Androidはブラウザではなくアプリを開く前に両者が一致することを検証します。結果を左右するのは2つの要素、すなわち自分で管理する/.well-known/assetlinks.jsonファイルと、その中のSHA-256署名フィンガープリントであり、失敗のほとんどは珍しい原因ではなく、どちらかがわずかに誤っていることに起因します。

このチュートリアルは、実際の作業手順に沿って進めます。autoVerifyインテントフィルターを宣言し、assetlinks.jsonのステートメントリストを公開し、Play App Signingがビルドに再署名する際に正しいフィンガープリントを選び、インストールして検証状態を読み取り、本番環境でよくある失敗を診断し、ユーザーに嘘をつかないフォールバックを設計し、キーローテーションやドメイン移行をまたいでアプリリンク検証を維持します。その根底にあるルールは1つです。検証とは、ドメインとアプリが同じ所有者であるという約束であり、それを正当に通過する唯一の方法は、実際に両方を所有することです。


1. 検証済みリンクが証明すること、しないこと

3つの考えが混同されがちですが、これらを切り分けることで多くの不適切な設計判断を防げます。

  • ディープリンクとは、アプリ内の画面を開くあらゆるインテントのことです。myapp://product/42のようなカスタムスキームから来ることもありますが、このスキームは端末上のどのアプリでも登録できるため、悪意のあるアプリが同じスキームを名乗り、あなたの代わりにURLを受け取る可能性があります。
  • An App Link is an HTTPS URL — https://shop.example.com/product/42 — that Android has verified you are entitled to handle, because that host publishes a statement naming your package and your signing certificate. The user sees a normal web URL, the browser can always open it, and only one app can win the verification.
  • Webフォールバックとは、アプリが未インストールのときにブラウザで開かれる同一URLのことです。適切に設計されたリンク戦略ならこの3つの要素が一致し、アプリの有無にかかわらずURLは目的のコンテンツに解決されます。

検証が行わないこと:アプリがインストールされていることの証明にはならず、ドメインのコンテンツに対するいかなる権利も付与せず、認証の代替にもなりません。画面にアカウントデータを表示する場合、それを守るのは依然としてサーバー側のトークン検証です。検証が答えるのは「このアプリがこのホストのリンクを開いてよいか」だけであり、それ以上ではありません。

実務上の帰結として、カスタムスキームは内部の受け渡し用途にとどめ、パスワードリセットや支払いリダイレクトには決して依存しないでください。スキームの所有権は強制できないためです。

2. ステップ1 — マニフェストでautoVerifyインテントフィルターを宣言する

まずはAndroidManifest.xmlから始めます。フィルタはandroid:autoVerify="true"を指定したhttpsフィルタである必要があり、VIEWアクションに加えてDEFAULTとBROWSABLEの両方のカテゴリが必要です:

<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" android:host="shop.example.com" /> </intent-filter>

これが実務で機能するかどうかを決める詳細:

  • ホストごとに1つのフィルター。検証はホスト単位で評価され、Googleのガイダンスではドメインごとに個別の<intent-filter>を設けるよう求めています。5つのホストを1つのフィルターにまとめると、1つの不正なホストが残りすべてを台無しにします。
  • ホスト名は完全一致です。 android:hostはワイルドカードを受け付けません。サブドメインには個別のフィルターで対応し、android:path、android:pathPrefix、android:pathPatternで範囲を絞り込み、表示できないURLをアプリが捕捉しないようにしてください。
  • httpは検証できません。 自動検証の対象になるのはhttpsのみです。httpフィルターを残しておくと、選択ダイアログが重複して表示されるだけです。
  • ルーティングする範囲だけを宣言。アプリが3つのパスしか扱わないのにホスト全体にマッチするフィルターを設定すると、それ以外のURLはすべて空白画面に飛びます。その挙動はクラッシュダッシュボードよりずっと早くストアレビューに現れます。

アプリがマーケティング用ドメインとアプリ用ドメインの両方を扱う場合は、共有用にどちらを正規とするかを意図的に決めてください。追加するホストはそれぞれ、公開すべきファイルであり、同期を保つべき証明書です。

3. ステップ2 — /.well-known/assetlinks.jsonを公開する

明細リストはHTTPS上の厳密に1つのパスに置かれ、その手前にリダイレクトはありません:

https://shop.example.com/.well-known/assetlinks.json

本文はステートメントのJSON配列です。ホスト上のすべてのURLを処理する通常のアプリでは、ステートメント1つで十分です:

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

複数のパッケージ、または複数の証明書を持つ1つのパッケージは、同じ配列に記述を追加するだけです。配信の詳細は内容と同じくらい重要です:

  • コンテンツタイプ。application/jsonとして配信してください。一部のAndroidバージョンや一部のCDNエッジ設定はこれに厳格です。
  • リダイレクト禁止。ファイルの手前に301や302があると取得に失敗し、しかも端末側では静かに失敗します。最もよくあるホスティングのミスで、サイト全体の「HTTPS強制」や「末尾スラッシュ削除」ルールが気づかないうちに壊してしまいます。
  • 認証なし、ボット対策なし。Googleの検証ツールはファイルを匿名で取得します。WAFのチャレンジや地域ブロックがあると、JSONが期待される場所にHTMLのエラーページが返されます。
  • 有効なJSON、コメントなし。 末尾のカンマや紛れ込んだ//コメントは、ファイル全体とその中のすべてのステートメントを無効にします。

Before you debug anything on the device, fetch the file the way the verifier would: curl -sI https://shop.example.com/.well-known/assetlinks.json should show 200 and no Location header, and the body should parse. Google publishes a statement list generator and tester that will validate the structure and the fingerprint format for you — use it before shipping.

4. ステップ3 — デバイスが実際に認識するフィンガープリントを使う

ここで多くの検証が失敗します。その理由はPlay App Signingにあります。登録すると、Googleがアプリ署名キーを保持し、配信するすべての成果物に再署名します。したがって、ユーザーの端末にインストールされる証明書はアプリ署名証明書であり、ビルドマシンにあるアップロードキーではありません。

  • Play インストールにはアプリ署名キーのSHA-256証明書が必要で、Play Consoleのアプリの整合性 → アプリの署名(「アプリ署名キーの証明書」ブロック)で確認できます。
  • ローカルビルドやサイドロードしたビルドはアップロードキーまたはデバッグキーで署名されており、そのフィンガープリントが必要です。keytool -list -v -keystore <keystore>で読み取り、SHA-256の行をコピーしてください。
  • 両方とも登録しましょう。アプリ署名証明書とアップロード証明書を同じsha256_cert_fingerprints配列に並べるのは一般的で推奨される方法です。これによりPlayからのインストールを検証しつつ、QAビルドも動かし続けられます。

同じ領域にもう2つの落とし穴があります。デバッグ用キーストアを使用する場合、そのフィンガープリントは生成したマシン固有のもので、自分のテストには使えても公開ファイルでは役に立ちません。また、Playのキーアップグレードを使用すると証明書が変わります。アップグレードを展開する前にステートメントリストを更新しないと、新規インストールではリンクが壊れ、既存のインストールは動作し続けます。

フィンガープリントは再入力せず、コンソールからコピーしてください。16進数の1組を打ち間違えるだけで、有効なJSONであり、200で配信され、しかもどこにもエラーメッセージが出ないまま検証に失敗するファイルができあがります。

5. ステップ4 — インストールして実際の検証状態を確認する

検証はアプリのインストール時と、更新後のそれぞれで試行されます。そのため、テスト対象のチャネルからインストールしたアプリが必要です。Playの内部テスト経由のインストールは、アップロード署名済みビルドをadb installした場合とは挙動が異なります。

Android 12以降では、プラットフォームに直接問い合わせてください。

adb shell pm get-app-links com.example.shop

ドメインごとのレポートが届きます。内容はドメイン、ユーザーが承認済みかどうか、そして検証状態です。ステートメントリストが一致すればverified、一致しなければdeniedまたはlegacy_failureとなります。旧リリースでは、これに相当するものとしてドメイン検証レコードのダンプが表示されます。

adb shell dumpsys package d

ホストが拒否と表示され、ファイルを修正したばかりの場合は、盲目的に再インストールするのではなく、新たに試行してください:

adb shell pm set-app-links --package com.example.shop --domain shop.example.com all

次に、ユーザーが実際に行うフローをテストします。ブラウザに入力したリンク、メールクライアントでタップしたリンク、別アプリ内のリンクは、必ずしも同じように解決されるとは限らず、そのうち1つだけが選択画面を経由する場合があります。システム設定のアプリのデフォルトで開く画面も確認してください。ユーザーが検証済みリンクをオフにでき、コードはそれに耐えて壊れないようにする必要があります。

6. ステップ5 — 実際に直面する失敗を診断する

本番環境の障害はほぼすべて5つのカテゴリのいずれかに当てはまります。この順番で確認してください。それぞれ数秒で済みます。

  1. フィンガープリントの不一致。 ファイルは解析でき、ホストも正しいものの、ステートメント内の証明書がアップロードキーで、端末側はPlay署名済みのビルドというケースです。コンソールのフィンガープリントをファイルと1文字ずつ照合してください。
  2. リダイレクトまたは誤ったコンテンツタイプ。 curl -sIで3xx、text/html、またはCDNキャッシュされたエラーページが表示されます。ヘッダーを修正し、キャッシュをパージしてから再検証してください。
  3. パッケージ名またはホストの不一致。 ホワイトラベルビルド用にアプリケーションIDが変更された、あるいはフィルターにまだステージングホストが残っていて、そのホストがファイルを配信しなくなっているケースです。マニフェスト内のすべてのホストを検索し、それぞれに有効なステートメントがあることを確認してください。
  4. 検証が実行されていません。 インストールがオフラインで行われたか、インストール後にアプリを一度も起動していません。ネットワーク接続のある状態でアプリを一度開き、pm get-app-linksを再実行してください。
  5. ユーザーによる上書き。設定でドメインが無効化されていたケースです。数か月前だったり、OEMの移行ツールによるものだったりします。pm set-app-links … allでテスト用にリセットできますが、実ユーザーには強制ではなく周知が解決策です。

リリースチェックリストに1行のスモークテストを加えましょう。ファイルを取得し、パースし、フィンガープリントがコンソールに現在表示されているものと一致することを検証します。このチェックを省いたドメイン移行やキー更新は、まさに稼働中のリンク設定が静かに壊れる原因です。

7. ステップ6 — 真実を伝えるフォールバックを構築する

App Linksはアプリを優先ハンドラにしますが、唯一のハンドラにはしません。ウェブ側を先に設計してください。常に存在するのはそちらのケースだからです。

  • URLはアプリなしで表示できる必要があります。インストール時しか機能しない共有リンクはリンク切れであり、インデックスするクローラーも壊します。
  • 検知してから提案を — 乗っ取りはしない。 「アプリで開く」とストアリンクを備えた小さなバナーは、意図的にブラウザを使いたいユーザーを閉じ込めてしまう自動リダイレクトよりもコンバージョンが良くなります。
  • ディープリンクのパスはウェブのパスと同一に保ってください。 アプリが/product/42を表示するなら、同じパスのウェブページも同じ商品を表示すべきです。構築を避けたマッピングテーブルこそ、次の四半期に壊れるものです。
  • 保留中のインストールのケースに対応する。新規ユーザーがインストールして共有アイテムに着地する遅延ディープリンクには、サーバー側またはインストールリファラーの仕組みが必要です。多くのチームがこれに使っていたFirebase Dynamic Linksは廃止されたため、ホスト型サービスを前提とせず、Install Referrer APIまたは同等の自社実装を計画してください。

また、検証を不可視にしようという誘惑に抗ってください。アプリがURLをレンダリングできない場合、ブラウザに処理させる方がアプリ側の「見つかりません」画面より良い結果であり、ドメインのSEOも維持されます。

8. リリースやドメインをまたいで本人確認を維持する

検証は一度きりの設定ではありません。マニフェスト、公開ファイル、そしてストアが実際に署名に使う証明書という3つの可変要素の間の継続的な合意です。そのいずれかに触れるものはすべてリリースチェックリストの項目になります。

  • 鍵のアップグレードまたは再署名。 assetlinks.jsonを新しい証明書で更新し、段階的リリースの前に公開してください。その後も、旧バージョンが完全に廃止されるまで古い証明書を記載したままにします。
  • ドメイン変更。 新しいホストでステートメントを先に公開し、マニフェストの変更はその後に反映します。ファイルのないホストを指すフィルターは、リンクを即座にオフラインにしてしまいます。
  • ブランドドメインと地域ドメイン。 各ホストはそれぞれ独立した表明であり、独立したファイルです。新しい地域ドメインがファイルなしで公開されないよう、デプロイを自動化してください。
  • 所有権の確認。このファイルは、そのドメインを管理しているという公開の表明です。自組織が所有・運営するドメインにのみ公開し、他者の表明を代わりにホストしないでください——それはまさに不正検知が見ているパターンであり、ドメインとアプリアカウントの両方を危険にさらします。

マニフェストのフィルター、公開済みのJSONテンプレート、現在のフィンガープリントを1か所にまとめ、単一の情報源から生成してください。3つを別々に手作業で編集していると、2回のリリースサイクルのうちに食い違ってきます。

9. KappSの位置づけ

私たちはリリースの運用面を担います。アカウント、リリース、ストアの記録を、プラットフォーム審査に耐える状態に保つこと。すなわち準拠した素材を準備し提出することであり、審査を欺くことではありません。リンク検証では、通常次のことを意味します:

  • リリースの衛生管理。証明書とアプリケーションIDをコンソール、ビルド、公開済みのステートメントリスト間で一致させ、デバイスが認識するフィンガープリントが文書化したものと同じになるようにします。
  • アカウントの準備状況。デベロッパー本人確認、支払いプロフィール、税務情報をアカウントの法人と整合させておくことで、無関係な審査でローンチが滞るのを防げます。
  • ドメインとホスティングの確認。well-knownパスが、リダイレクトもWAFチャレンジもキャッシュされたエラーページも介さずに、実際にJSONを返しているかを確認します。

当社が行わないこと:クライアントが所有していないドメインのステートメントを公開すること、フィンガープリントを偽装すること、アプリに権利のないホストを主張させる手助けをすること。確認はまさにそうした事態からユーザーを守るために存在し、当社が提供するサービスではありません。

Sources (official documentation): Android Developers — Verify Android App Links; Add Android App Links; Digital Asset Links specification; Play Console Help — App signing key certificate and key upgrade; Android Developers — Adb shell pm commands for app links.

デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。

クリックしてファイルを選択 · 右クリック→貼り付け、またはCtrl/⌘+Vでスクリーンショットを貼り付け

このボックスにファイルをドラッグすることもできます。

ご提供いただいたメールに返信します。お客様の情報はKappS内に留まります。

✔ 送信済み

メッセージを受け付けました。24時間以内に返信します。


← 編集に戻る