クラウド Mac で Universal Links の関連ファイルを検証する

リリースブランチの商品リンクはブラウザーで正常に開くのに、テスト端末に App をインストールすると、いつも Web ページが開いてしまう。このとき、すぐに App のリンク処理コードを修正すると、実際の問題箇所を見落としがちです。端末はまず、ドメインが提供する関連ファイルを取得し、そのドメインが対象のパスを指定の App に処理させることを許可しているか確認する必要があります。クラウド Mac でファイルの配信経路を先に調べてから、端末で再検証しましょう。サーバー側と端末側の証拠を分けて記録するほうが、リンクを何度もクリックするより有効です。

失敗したケースを一つ確定する

リンク全体、開くはずの App、実際に開いた方法、端末の OS バージョン、App のビルドバージョンを記録します。リンクは少なくとも二つ用意してください。一つは App で開くべきもの、もう一つは Web ページで開くべきものです。「すべてのリンクが動かない」とだけ書かないでください。ドメイン、パス、クエリパラメーターが違えば、まったく別のルールに該当する可能性があります。

テスト方法も確認します。クリック可能なリンクから開くことと、ブラウザーのアドレスバーに URL を手入力することは、同じ検証にはなりません。チームで再検証するときは、同じ方法でリンクを開いてください。本番環境とプレリリース環境でドメインが異なる場合は、記録も別々に作成します。一方のドメインのファイルで、もう一方のドメインでの挙動を説明することはできません。

「サーバーが現在何を返しているか」と「この端末が現在リンクをどう開くか」を別々の列に記録してください。前者はすぐに再確認できますが、後者はインストール状態やキャッシュの影響を受けることがあります。

ファイルがリダイレクトなしで配信されるか確認する

クラウド Mac のターミナルで、チームが実際に管理しているドメインを設定します。App のバンドル ID をドメインとして指定しないでください。関連ファイルは /.well-known/apple-app-site-association から直接取得できる必要があります。確認時にコマンドがリダイレクトを自動でたどるようにはしないでください。リダイレクト先の成功応答を、ファイルが直接配信された結果と取り違えやすくなります。

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

HTTP ステータスが 200 であること、ログインページや別のパスを指す Location がないこと、本文が HTML のエラーページではないこと、Content-Type が application/json であることを確認します。plutil に通っても、構文を解析できると分かるだけで、ルールの正しさは証明できません。ネットワークエラーでコマンドが終了した場合は、まずドメインの名前解決と TLS 接続を確認してください。ディスクに残っている古い aasa-body.json を今回の結果として扱ってはいけません。確認時には古いファイルを削除してから再実行し、応答ヘッダーと本文を一緒に保存しておくとよいでしょう。

ネットワーク経路を一つだけで判断しない

ファイルがキャッシュやリバースプロキシを経由する場合は、チームが普段使うネットワークとクラウド Mac のそれぞれから同じ URL をリクエストし、本文と応答ヘッダーのキャッシュ情報を比較します。経路によって結果が異なるなら、まず公開先、キャッシュキー、更新手順を確認してください。問題を隠すためにキャッシュルールを一律に緩めてはいけません。目標は、同じドメインの関連ファイルが期待どおりの内容を安定して返すことです。

識別子とパスのルールを照合する

JSON の applinks.details から該当する項目を探し、チーム ID と App のバンドル ID で構成される appID を一字ずつ照合します。次に、失敗したリンクの URL パスをルールに一つずつ当てはめます。パスの大文字と小文字を区別するか、末尾にスラッシュがあるか、除外ルールが広範なルールより先に影響するかは、ファイルで実際に使われているルール形式に沿って個別に検証してください。Web のルートにアクセスできるからといって、App が必ずリンクを処理できるとは限りません。

クエリパラメーターは App が開いた後にコンテンツを特定する助けになりますが、URL パスがルールに一致するかの確認に代わるものではありません。チームが従来の paths から components に移行している場合は、対象端末の OS が採用した記述形式をサポートしているか先に確認し、実際のテストリンクで検証します。比較用のテストケースがないまま、識別子、ルール、App のコードを同時に変更しないでください。

ビルド成果物と端末を確認する

サーバーのファイルが正しければ、App のビルドで使用した関連ドメインの設定を確認します。ドメインの指定は、実際にそのファイルを配信するホスト名を指している必要があります。サブドメイン同士を、何も確認せず同等とみなしてはいけません。端末にインストールされているのが、いま確認したビルドバージョンであり、別のリリースブランチのパッケージではないことも確かめます。設定を変更したら、必ずビルドし直してインストールしてください。サーバーのファイルを更新するだけでは、インストール済みの App の設定は変わりません。

テスト端末で「変更前」の結果を記録してから新しいビルドをインストールし、以前と同じ場所から同じリンクをクリックします。サーバーは新しいルールを返しているのに端末の挙動が以前のままなら、App を再インストールして再テストし、両方の結果を記録します。関連ファイルの取得と検証が即座に完了するとは限りません。一度クリックした結果だけで、サーバーの変更は無効だったと断定しないでください。

まとめて再試行せず、境界ごとに切り分ける

ファイルを取得できない、またはリダイレクトが返るなら、配信経路を調べます。ファイルは取得できても識別子やパスが一致しないなら、ルールまたはビルド設定を調べます。両方とも一致していて一台の端末だけで失敗するなら、インストール履歴、端末のバージョン、リンクをクリックした場所を比較します。一度に変更するのは一つの層だけにし、変更前後の応答ヘッダー、ファイル本文、ビルド識別子、端末で観察した結果を残してください。そうして初めて、どの変更が効いたか確認できます。

リリース手順に確認を組み込む

リリース作業に簡単なチェックを追加できます。本番ドメインの関連ファイルをリクエストし、リダイレクトがないこと、ステータスが正しいこと、JSON を解析できることを確認します。さらに、App で開くべきパスと開くべきでないパスを一つずつ使ってルールを照合します。自動チェックで確認できるのは、サーバーと静的な設定までです。端末で「クリック後に何が開くか」は、ビルドをインストールした状態で検証する必要があります。

最後に、失敗したケース、実際の応答、一致するルール、端末での再検証結果を一つの記録にまとめます。次に「Web ページは開くのに App は開かない」という問題が起きても、担当者はリンク処理コードとキャッシュのどちらが原因か推測するところから始めず、直近で確認済みの境界から調査を続けられます。

よくある質問