TN3155：ユニバーサルリンクのデバッグ

概要ページ内リンク

ユニバーサルリンクでは、applinks（関連ドメインサービスの1つ）を使用して、SafariまたはWebサイトを経由することなく、アプリ内のコンテンツに直接リンクすることができます。アプリがインストールされている場合は、アプリでユニバーサルリンクが開きます。インストールされていない場合は、デフォルトのWebブラウザでリンクが開き、サイトで残りの処理を行うことができます。ユニバーサルリンクおよびコードでユニバーサルリンクをサポートする方法について十分に把握していない場合は、「関連ドメインをサポートする」および「コンテンツへのリンクをアプリとWebサイトに許可する」を参照してください。

本ドキュメントでは、以下の方法について概要を説明します。

• ユニバーサルリンクをテストする

• 正しいapplinksドメインを選択する

• サイトでユニバーサルリンクを使用する

• apple-app-site-association（AASA）ファイルを検証する

• sysdiagnoseを使用してデバッグする

• Appleのコンテンツ配信ネットワーク（CDN）を理解する

ユニバーサルリンクの動作をテストするページ内リンク

ユニバーサルリンクの動作をテストするには、リンクをメモアプリに貼り付けて、リンクを長押しするか（iOSの場合）、Controlキーを押しながらクリックして（macOSの場合）、リンク先への移動方法に関するオプションを確認します。ユニバーサルリンクが正しく設定されていれば、アプリで開くオプションとSafariで開くオプションの両方が表示されます。ここで選択したオプションが、今後このドメインからユニバーサルリンクのリンク先に移動する際のデフォルトのデバイス動作となります。このデフォルトの選択を変更するには、同じ手順を繰り返して別のオプションを選択します。

iOSの場合、次の手順に従って、「デベロッパ」の設定にある関連ドメイン診断テストを使用して、ユニバーサルリンクをさらにテストすることができます。

1. 「設定」で「デベロッパモード」をオンにします。ヘルプが必要な場合は、「デバイスでデベロッパモードを有効にする」を参照してください。

2. 「設定」>「デベロッパ」と選択し、「ユニバーサルリンク」セクションまでスクロールし、「関連ドメインの開発」をオンにします。

3. 「診断」を開き、完全なURLを入力します。インストールされているアプリに対してこのリンクが有効であるかどうかのフィードバックが表示されます。

ユニバーサルリンクが無効である場合、applinksが正しく設定されていない可能性があります。

applinksの設定とルールを理解するページ内リンク

Xcodeの「Signing and Capabilities（署名と機能）」タブを使用して、アプリにapplinksを含む「Associated Domains（関連ドメイン）」機能があることを確認できます。次の形式を使用します。

applinks:<fully qualified domain>

よくある問題の原因として、AASAファイルが適切な場所にホストされていないドメインがapplinksで使用されている場合があります。

ドメインとAASAファイルのパスが一致していることを確認してください。ルートドメインと、ワイルドカードを使用するすべてのサブドメインを一致させるには、AASAファイルを次の場所にホストする必要があります。

https://example.com/.well-known/apple-app-site-association

これは、ルートドメインapplinks:example.comと、ワイルドカードを使用したapplinks:*.example.comに一致するサブドメインにのみ有効です。一方、applinks:www.example.comまたはapplinks:foo.example.comなどの特定のサブドメインは有効ではありません。

特定のサブドメインを一致させるには、AASAファイルを次の場所にホストする必要があります。

https://www.example.com/.well-known/apple-app-site-association

これは、applinks:www.example.comにのみ有効です。applinks内の各サブドメインには、それぞれ一致する固有のAASAファイルパスが必要です。

サイトでユニバーサルリンクを使用するページ内リンク

すでにSafariで閲覧している場合にユニバーサルリンクを使用してアプリを開くには、別のサブドメインを使用します。これが必要になる理由として、アンケートに回答する場合やサインインを実行する場合などがあります。ユニバーサルリンクのドメインが前のナビゲーションと同じである場合、Safariでは、ユーザーがブラウザでのナビゲーションを継続する意向であると推測します。詳しくは、「コンテンツへのリンクをアプリとWebサイトに許可する」を確認してください。

サブドメインを使用する場合の例として、applinks:example.comをルートドメインに持つアプリと次を含むAASAについて考えます。

 "components" : [
 {
 "/" : "/login/*",
 "comment" : "/login/で始まるパスを持つすべてのURLが一致します。"
 }]

Safariでユーザーがサイトを閲覧中に、https://example.com/loginへのリンクが貼られたログインボタンを選択した場合、リンクはアプリで開きません。パスが上記のコンポーネントと一致していても、ドメインが変更されていないため、Safariはブラウザでのナビゲーションを続行します。

これを回避するには、次の手順を実行します。

• Xcodeの「Signing and Capabilities（署名と機能）」タブで、applinks:foo.example.comなどのサブドメインを関連ドメインに追加します。

• 次の場所にAASAをホストします。

https://foo.example.com/.well-known/apple-app-site-association

• ログインボタンに次のリンクを設定します。

https://foo.example.com/login

別のサブドメインを使用することで、リンクがSafariでナビゲーションとして処理されず、アプリで開くようにすることができます。

AASAをホストして検証するページ内リンク

それでもユニバーサルリンクがアプリで開かない場合は、HTTPレスポンスヘッダとAASAコンテンツを詳しく確認します。これを行うには、ターミナルで以下を使用して、HTTPレスポンスヘッダとAASA JSONコンテンツを出力します。

% curl -v https://{domain}/.well-known/apple-app-site-association

301または302 HTTPレスポンスステータスコードが表示されたら、サイトはHTTPリダイレクトを実行しているということですが、AASAファイルをホストしている場合、HTTPリダイレクトはサポートされません。リダイレクトせずにファイルに直接到達できる必要があります。

ルートドメインにAASAをホストし、サブドメインへのリダイレクトを行う代わりに、applinksに含まれる各ドメインとサブドメインにAASAをホストします。例えば、applinks:www.example.comというサブドメインとapplinks:*.example.comというワイルドカードがある場合、次の場所にサブドメイン用のAASAファイルを1つホストし、

https://www.example.com/.well-known/apple-app-site-association

次の場所にワイルドカード用のAASAファイルを1つホストします。

https://example.com/.well-known/apple-app-site-association

403または404 HTTPエラーが表示された場合、サイトがアクセスを拒否しています。一般的に、この事象は、AASAファイルのパスがすべてのIPアドレスからアクセスできるかたちでは公開されていないか、その他の何らかの理由でサイトがブロックされている場合に発生します。Webサイトの設定で、地理的位置やIPアドレスを問わず、.well-knownディレクトリにあるAASAファイルへの直接アクセスが許可されていることを確認してください。特定のIPアドレスと範囲は、保証できないために公開されません。

AASAファイルの形式を確認します。「関連ドメインをサポートする」に示されているようなappIDs配列とcomponents配列、または文字列型のappIDフィールドと配列型のpathsフィールド（古い形式と一致）が含まれている必要があります。これらの形式は一致させる必要があります。混在していると、ユニバーサルリンクは機能しません。推奨される形式は次の通りです。

 "appIDs": [ "ABCDE12345.com.example.app", "ABCDE12345.com.example.app2" ], 
 "components": [ { 
    "/": "/test/*", 
    "comment": "/test/で始まるすべてのURLが一致します。" 
    },
    { 
    "/": "/path/1/*", 
    "exclude": true,
    "comment": "/path/1/で始まるすべてのURLが一致し、そのURLをユニバーサルリンクとして開かないようにシステムに命令します。" 
    }]

古い形式は次の通りです。

"appID": "ABCDE12345.com.example.app",
 "paths": [ "/test/*", NOT "/path/1/*"]

AASAが有効な形式であり、パターンが正しく一致することを確認するには、Macに組み込まれているswcutilツールを使用します。ターミナルでsudo swcutilを実行すると、swcutil dlやswcutil verifyなどの使用可能なコマンドが表示されます。

ターミナルでこれらのコマンドを使用するには、次の手順を実行します。

• sudo swcutil dl -d <domain>を実行して、AASA JSONを正常にダウンロードできることを確認します。

• sudo swcutil verify -d <domain> -j <path-to-JSON> [-u <URL>]を実行して、ダウンロードした.json AASAファイルの内容を確認します。-dを使用してドメインが一致していることを確認し、-uを使用してURLパスパターンがJSONと一致していることを確認します。両方が一致していれば、確認メッセージが表示されます。

例えば、applinks:example.comを含むアプリと上記のAASAにswcutil verifyを使用すると、次のようになります。ここで、「s」はサービス、「a」はアプリID、「d」はドメインを表しています。

% sudo swcutil verify -d example.com -j ./example.json -u https://example.com/test
{ s = applinks, a = ABCD123.com.example.app, d = example.com }:
Pattern "https://example.com/test" matched.

AASAにパターン/testが含まれているため、JSONのパターンは一致し、検証に成功します。パス/path/1については、AASAで除外するように設定されているため、除外を確認する次のメッセージが表示されます。

Pattern "https://example.com/path/1" blocked match.

除外されていないURLパスにこのメッセージが表示された場合は、AASAが一致していません。詳しくは、「sysdiagnoseを使用してデバッグする」のセクションを参照してください。

sysdiagnoseを使用してデバッグするページ内リンク

「AASAをホストして検証する」のセクションの手順でswcutilからの出力に無効なユニバーサルリンクが表示された場合は、「Profiles and Logs（プロファイルとログ）」で各プラットフォーム用にリンクされている手順に従い、アプリがインストールされたデバイスでsysdiagnoseを取得します。sysdiagnoseを開いてから、swcutil_show.txtファイルを開きます。App IDを検索して、applinksの情報（次の例を参照）を確認します。

Service:              applinks
App ID:               1234abcd.com.example
Domain:               example.com
User Approval:        unspecified
Site/Fmwk Approval:   approved
Last Checked:         2023-08-24 10:09:00 +0000
Next Check:           2023-08-18 21:00:19 +0000

User Approval：ユーザーがリンクをアプリまたはSafariのどちらで開くことにしたかを示しています。詳しくは、「ユニバーサルリンクの動作をテストする」を参照してください。

Site/Fmwk Approval：Appleが管理するコンテンツ配信ネットワーク（CDN）でユニバーサルリンクが承認され、パターンが一致したかどうかを示しています。「approved」である場合、ユニバーサルリンクは正常に機能しています。

「unspecified」または「denied」である場合、すべてのIPアドレスへのフルアクセスが許可されていること、またドメインが関連ドメインに含まれていることを確認してください。詳しくは、「AppleのCDNを理解する」を確認してください。

Last Check/Next Check：AppleのCDNがサイトにAASAを要求した最後の日時と次にAASAを確認する日時を示しています。

AppleのCDNを理解するページ内リンク

アプリがデバイスにインストールされると、AppleのCDNはAASAファイルを要求します。CDNがファイルをキャッシュできるように、ファイルをホストするドメインは、すべてのIPアドレスと範囲で利用でき、リダイレクトされず、かつアクセスポリシーによってブロックされていない必要があります。

テストの際に、Xcodeでパブリックなインターネットから到達できないサーバを使用してアプリを実行する場合、またはAppleのCDNがキャッシュできる速度よりも速い速度で変更をテストする場合は、「関連するドメインエンタイトルメント」に説明されている別のデベロッパモードを使用してください。こうすることで、AppleのCDNをバイパスし、AASAをドメインから直接取得できます。

改訂履歴ページ内リンク

• 2023-09-05 初版発行。