ディープリンク

概要

ディープリンクは、ユーザーがリンクをタップしたときに、メール、SMS、ウェブサイト、プッシュ通知、アプリ内メッセージなどのソースを問わず、アプリ内の特定の画面に誘導します。アプリがインストールされていない場合、オペレーティングシステムはユーザーをアプリストアまたはフォールバックウェブページにリダイレクトできます。このガイドでは以下を説明します：

ディープリンクの種類とそれぞれの使用タイミング
Android と iOS のプラットフォーム設定
OneSignal SDK を使用したアプリでのディープリンクの処理
プッシュ、メール、アプリ内メッセージのチャネル別の動作

一般的な URL およびリンク設定（起動 URL、UTM パラメーター、動的 URL、リンクトラッキング）については、URL、リンク、ディープリンクを参照してください。

前提条件

ディープリンクを設定する前に、以下が必要です：

アプリが設定された OneSignal アカウント
モバイルアプリにインストールされた OneSignal SDK
Universal Links または App Links 用に HTTPS でホストされた管理ドメイン
アプリのソースコードおよびビルド設定へのアクセス（iOS は Xcode、Android は Android Studio）

ディープリンクの種類

ディープリンクには 3 つの一般的なメカニズムがあります。各メカニズムの動作はアプリがインストールされているかどうかによって異なります。

種類	プラットフォーム	形式	アプリ未インストール時
Universal Links	iOS 9+	`https://yourdomain.com/path`	Safari で URL を開く
App Links	Android 6.0+	`https://yourdomain.com/path`	ブラウザで URL を開く
カスタム URI スキーム	iOS と Android	`myapp://path`	エラーなしで失敗またはエラーを表示

推奨： 最も信頼性の高いエクスペリエンスのために、Universal Links（iOS）と App Links（Android）を使用してください。これらは標準の https:// URL を使用し、チャネル（プッシュ、メール、SMS）をまたいで機能し、アプリがインストールされていない場合のフォールバック動作を提供します。カスタム URI スキーム（myapp://）は設定が簡単ですが、フォールバック動作を提供せず、すべてのコンテキスト（メールクライアントなど）で機能しない場合があります。

Universal Links と App Links では、ドメインに検証ファイルをホストする必要があります。このファイルがないと、OS はリンクを通常のウェブ URL として扱います。

Android 設定（App Links）

Android Studio の App Links Assistant を使用して、必要な設定を生成します。

インテントフィルターの設定

ディープリンクを処理する Activity にインテントフィルターを追加します：

<activity android:name=".DeepLinkActivity" android:exported="true">
  <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="yourdomain.com" />
  </intent-filter>
</activity>

受信インテントの処理

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

Digital Asset Links ファイルのホスティング

Android Studio の App Links Assistant を使用して assetlinks.json ファイルを生成し、以下の場所にホストします：

https://yourdomain.com/.well-known/assetlinks.json

完全なファイル形式と確認手順については、Google の Verify App Links ドキュメントを参照してください。

iOS 設定（Universal Links）

Apple の Universal Links は、ユーザーが一致する https:// URL をタップしたときにアプリを開きます。アプリのインストールが保証されているシンプルなユースケースでは、代わりに URL スキームを使用できます。

Associated Domains の有効化

Xcode でターゲットを選択 → Signing & Capabilities → Associated Domains を追加
ドメインを追加：applinks:yourdomain.com

アプリでの Universal Link の処理

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // URL パスに基づいて正しい画面にルーティング
  return true
}

- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
    restorationHandler:(void (^)(NSArray *))restorationHandler {
  if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
    NSURL *url = userActivity.webpageURL;
    // URL パスに基づいて正しい画面にルーティング
    return YES;
  }
  return NO;
}

Apple App Site Association ファイルのホスティング

apple-app-site-association（AASA）ファイルを作成し、以下の場所にホストします：

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

TEAMID を Apple Team ID に、com.example.app をバンドル識別子に置き換えてください：

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.app",
      "paths": ["/path/*", "/another-path"]
    }]
  }
}

完全な仕様については、Apple の Supporting Associated Domains ドキュメントを参照してください。

iOS 起動 URL の動作

OneSignal の iOS SDK は起動 URL（url プロパティ）を処理するために openURL を使用します。これにより、リンクが最初にブラウザで開き、その後アプリにリダイレクトされます——ユーザーエクスペリエンスが低下する可能性があります。これを回避するには、以下のいずれかのアプローチを使用してください：

API ペイロードで url の代わりに data を使用し、プッシュ通知クリックリスナーでディープリンクを処理する
Info.plist に Boolean 値 YES の OneSignal_suppress_launch_urls を追加して起動 URL を抑制し、クリックリスナーですべてのナビゲーションを処理する

アプローチ 1（data + クリックリスナーの使用）を推奨します。OS に URL 解決を依存せず、ナビゲーションを完全に制御できます。

OneSignal SDK によるディープリンクの処理

OneSignal メッセージからのディープリンクを処理する最も信頼性の高い方法は、OS レベルのリンク解決に依存するのではなく、SDK のクリックリスナーを使用することです。これにより、アプリ内のナビゲーションを完全に制御できます。

プッシュ通知クリックリスナー

addClickListener を使用して通知クリックをインターセプトし、ディープリンク URL または追加データに基づいてユーザーをルーティングします：

OneSignal.Notifications.addClickListener { event ->
  val url = event.notification.launchURL
  val data = event.notification.additionalData
  // url または data に基づいて正しい画面にルーティング
}

class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    OneSignal.Notifications.addClickListener(self)
    return true
  }

  func onClick(event: OSNotificationClickEvent) {
    let url = event.notification.launchURL
    let data = event.notification.additionalData
    // url または data に基づいて正しい画面にルーティング
  }
}

OneSignal.Notifications.addEventListener('click', (event) => {
  const url = event.notification.launchURL;
  const data = event.notification.additionalData;
  // url または data に基づいて正しい画面にルーティング
});

OneSignal.Notifications.addClickListener((event) {
  final url = event.notification.launchUrl;
  final data = event.notification.additionalData;
  // url または data に基づいて正しい画面にルーティング
});

OneSignal.Notifications.Clicked += (sender, e) => {
  var url = e.Notification.LaunchURL;
  var data = e.Notification.AdditionalData;
  // url または data に基づいて正しい画面にルーティング
};

Java、Objective-C、Cordova/Ionic を含む完全な API リファレンスについては、addClickListener() プッシュを参照してください。

アプリ内メッセージクリックリスナー

アプリ内メッセージのボタンとアクションからのディープリンクを処理するには、アプリ内メッセージクリックリスナーを使用します：

OneSignal.InAppMessages.addClickListener { event ->
  val actionId = event.result.actionId
  // アクション ID（ディープリンク URI）に基づいてルーティング
}

func onClick(event: OSInAppMessageClickEvent) {
  let actionId = event.result.actionId
  // アクション ID（ディープリンク URI）に基づいてルーティング
}

OneSignal.InAppMessages.addEventListener('click', (event) => {
  const actionId = event.result.actionId;
  // アクション ID（ディープリンク URI）に基づいてルーティング
});

OneSignal.InAppMessages.addClickListener((event) {
  final actionId = event.result.actionId;
  // アクション ID（ディープリンク URI）に基づいてルーティング
});

完全な API リファレンスについては、addClickListener() アプリ内を参照してください。

プッシュ通知

2 つの方法のいずれかでディープリンクを含めます：

方法	API プロパティ	動作
起動 URL	`url`（またはモバイル専用の `app_url`）	OS が URL を直接開く。iOS では、抑制しない限りブラウザが先に開く。
追加データ（推奨）	`data`	URL がクリックリスナーに渡される。ナビゲーションを完全に制御できる。

プラットフォームの動作

Android：App Links を通じて一致する Activity を直接開く
iOS：Safari を開き、その後アプリを開く（起動 URL を抑制してクリックリスナーでナビゲーションを処理しない場合）

url、web_url、app_url のターゲティングの詳細については、URL、リンク、ディープリンクを参照してください。

メール

デフォルトでは、OneSignal はクリックトラッキングのためにメールリンクを書き換えます。これにより URL が変更され、OS がドメインをアプリの Associated Domain と一致するものと認識しなくなるため、ディープリンクが機能しなくなります。

メールでのディープリンクの有効化

ディープリンクを維持するには、以下のいずれかの方法でクリックトラッキングを無効にします：

ダッシュボード：メールエディターでリンククリックのトラッキングのチェックを外す
API：disable_email_click_tracking: true を設定する
リンクごと：アンカータグに disable-tracking=true 属性（<a href="https://yourdomain.com/path" disable-tracking=true>…</a>）を追加して、他のリンクのトラッキングを維持しながら個別リンクのトラッキングを無効にする

OneSignal メールエディターで「リンククリックのトラッキング」チェックボックスがオフになっている — メールエディターでリンククリックのトラッキングが無効になっています。

クリックトラッキングを無効にすると、メールレポートのクリック指標が失われます。ディープリンク以外の URL の分析を維持するために、リンクごとのトラッキング除外の使用を検討してください。

メールディープリンクの動作

シナリオ	結果
iOS + Safari + Universal Link + トラッキング無効	アプリを直接開く
iOS + Safari + Universal Link + トラッキング有効	Safari を開き、アプリを開くよう促す
iOS + Safari 以外のメールクライアント + Universal Link	アプリ未インストール時は App Store を開く
Android + App Link + トラッキング無効	アプリを直接開く
Android + App Link + トラッキング有効	先にブラウザを開き、その後アプリを開く

アプリ内メッセージ

アプリ内メッセージのディープリンクはクリックリスナーパターンを使用します。メッセージエディターでカスタムアクション識別子を設定し、アプリコードでそれを処理します。

ドラッグアンドドロップエディター

ボタンまたはクリック可能な要素を追加する
クリックアクションをカスタムアクション ID に設定する
アクション名としてディープリンク URI を入力する（例：https://yourdomain.com/promo または myapp://promo）

HTML エディター

カスタム HTML からディープリンクをトリガーするには、アプリ内 JS ライブラリの openUrl メソッドを使用します。

クリックの処理

アプリ内メッセージクリックリスナーを使用してアクションをインターセプトし、アプリ内でユーザーを誘導します。

ディープリンクのテスト

Android

通知を送信せずに App Links をテストするには、adb を使用します：

adb shell am start -a android.intent.action.VIEW \
  -d "https://yourdomain.com/path" \
  com.your.package

assetlinks.json にアクセスできることを確認します：

curl -I https://yourdomain.com/.well-known/assetlinks.json

iOS

Apple の Associated Domains 検証ツールを使用して AASA ファイルを確認します。以下の方法で Universal Links をテストすることもできます：

メモアプリにリンクを貼り付ける
リンクを長押しして「[App] で開く」オプションが表示されることを確認する
リンクをタップしてアプリが開くことを確認する

Universal Links は Safari のアドレスバーに直接入力しても機能しません——別のアプリ（メモ、メール、メッセージなど）からタップする必要があります。

OneSignal テストメッセージ

OneSignal ダッシュボードから、ディープリンク URL を起動 URL または追加データとして設定してテストプッシュを送信する
通知がアプリ内の正しい画面を開くことを確認する
クリックリスナーのログをチェックして、URL またはデータが受信されたことを確認する

トラブルシューティング

iOS ディープリンクがアプリの代わりに Safari を開く

これは最も一般的な問題です。考えられる原因：

AASA ファイルが正しくホストされていない — https://yourdomain.com/.well-known/apple-app-site-association にあり、Content-Type: application/json でリダイレクトがないことを確認する
Associated Domains が設定されていない — Xcode → Signing & Capabilities → Associated Domains に applinks:yourdomain.com が含まれていることを確認する
起動 URL の動作 — OneSignal の iOS SDK は url プロパティに openURL を使用し、ブラウザ優先の動作をトリガーします。代わりに data + クリックリスナーを使用するか、起動 URL を抑制してください
Safari でのテスト — Universal Links は Safari のアドレスバーからはアクティベートされません。メモ、メール、または別のアプリからテストしてください。

Android ディープリンクがブラウザを開く

autoVerify が欠落している — インテントフィルターに android:autoVerify="true" が含まれていることを確認する
assetlinks.json が見つからない — ファイルが https://yourdomain.com/.well-known/assetlinks.json にあり、HTTP 200 を返すことを確認する
SHA256 フィンガープリントの不一致 — assetlinks.json のフィンガープリントはアプリの署名証書と一致する必要があります。デバッグビルドとリリースビルドは異なる証明書を使用します。

ディープリンクがプッシュでは機能するがメールでは機能しない

メールのクリックトラッキングが URL を書き換え、ドメイン検証を破壊しています。ディープリンクを含むメールのクリックトラッキングを無効にしてください。

ディープリンクは受信されたがアプリが遷移しない

クリックリスナーがアプリのライフサイクル初期（例：Application.onCreate() または AppDelegate.didFinishLaunchingWithOptions）に登録されていることを確認する
URL またはアクション ID がルーティングロジックの期待と一致することを確認する
iOS では、起動 URL を抑制せずに url に依存していないことを確認する——リスナーが起動する前にブラウザがリンクを消費する場合があります

よくある質問

アプリがインストールされていない場合はどうなりますか？

Universal Links（iOS）では、URL は通常のウェブページとして Safari で開きます。App Links（Android）では、URL はデフォルトブラウザで開きます。どちらの場合も、ウェブページを適切なアプリストアにリダイレクトするよう設定できます。カスタム URI スキーム（myapp://）は、アプリがインストールされていない場合にエラーなしで失敗するかエラーを表示します。

ディープリンクには起動 URL と追加データのどちらを使用すべきですか？

追加データ（data）はモバイルディープリンクに推奨されます。クリックリスナーを通じてナビゲーションを完全に制御できます。起動 URL（url）はよりシンプルですが、iOS での制限（ブラウザリダイレクト）があり、カスタムルーティングロジックを許可しません。

ユーザーデータでディープリンクをパーソナライズできますか？

はい。Liquid 構文で動的 URL を使用して、ユーザープロパティ、タグ、またはカスタムデータをディープリンク URL に挿入します。例：https://yourdomain.com/profile/{{subscription.external_id}}

カスタム URI スキームでディープリンクを使用できますか？

はい。カスタムスキーム（例：myapp://screen）を起動 URL または追加データの値として設定します。カスタムスキームはプッシュおよびアプリ内メッセージではうまく機能しますが、メールクライアントでは機能しない場合があります。また、アプリがインストールされていない場合のフォールバックも提供されません。

OneSignal Journeys でディープリンクは機能しますか？

はい。Journey でメッセージステップを設定する際、起動 URL または追加データをディープリンクに設定します。動作はスタンドアローンのプッシュまたはアプリ内メッセージと同じです。

URL、リンク、ディープリンク

起動 URL、UTM パラメーター、動的 URL、リンクトラッキング設定。

モバイル SDK リファレンス

クリックリスナーと通知イベント処理の完全な API リファレンス。

アプリ内クリックアクション

アプリ内メッセージのボタンと要素のクリックアクションを設定します。

モバイルプッシュ設定

Android と iOS のプラットフォーム固有のプッシュ通知設定。

URL、リンク、ディープリンクメール配信停止リンクとヘッダー

⌘I

​概要

​前提条件

​ディープリンクの種類

​Android 設定（App Links）

​インテントフィルターの設定

​受信インテントの処理

​Digital Asset Links ファイルのホスティング

​iOS 設定（Universal Links）

​Associated Domains の有効化

​アプリでの Universal Link の処理

​Apple App Site Association ファイルのホスティング

​iOS 起動 URL の動作

​OneSignal SDK によるディープリンクの処理

​プッシュ通知クリックリスナー

​アプリ内メッセージクリックリスナー

​プッシュ通知

​プラットフォームの動作

​メール

​メールでのディープリンクの有効化

​メールディープリンクの動作

​アプリ内メッセージ

​ドラッグアンドドロップエディター

​HTML エディター

​クリックの処理

​ディープリンクのテスト

​Android

​iOS

​OneSignal テストメッセージ

​トラブルシューティング

​iOS ディープリンクがアプリの代わりに Safari を開く

​Android ディープリンクがブラウザを開く

​ディープリンクがプッシュでは機能するがメールでは機能しない

​ディープリンクは受信されたがアプリが遷移しない

​よくある質問

​アプリがインストールされていない場合はどうなりますか？

​ディープリンクには起動 URL と追加データのどちらを使用すべきですか？

​ユーザーデータでディープリンクをパーソナライズできますか？

​カスタム URI スキームでディープリンクを使用できますか？

​OneSignal Journeys でディープリンクは機能しますか？

URL、リンク、ディープリンク

モバイル SDK リファレンス

アプリ内クリックアクション

モバイルプッシュ設定

概要

前提条件

ディープリンクの種類

Android 設定（App Links）

インテントフィルターの設定

受信インテントの処理

Digital Asset Links ファイルのホスティング

iOS 設定（Universal Links）

Associated Domains の有効化

アプリでの Universal Link の処理

Apple App Site Association ファイルのホスティング

iOS 起動 URL の動作

OneSignal SDK によるディープリンクの処理

プッシュ通知クリックリスナー

アプリ内メッセージクリックリスナー

プッシュ通知

プラットフォームの動作

メール

メールでのディープリンクの有効化

メールディープリンクの動作

アプリ内メッセージ

ドラッグアンドドロップエディター

HTML エディター

クリックの処理

ディープリンクのテスト

Android

iOS

OneSignal テストメッセージ

トラブルシューティング

iOS ディープリンクがアプリの代わりに Safari を開く

Android ディープリンクがブラウザを開く

ディープリンクがプッシュでは機能するがメールでは機能しない

ディープリンクは受信されたがアプリが遷移しない

よくある質問

アプリがインストールされていない場合はどうなりますか？

ディープリンクには起動 URL と追加データのどちらを使用すべきですか？

ユーザーデータでディープリンクをパーソナライズできますか？

カスタム URI スキームでディープリンクを使用できますか？

OneSignal Journeys でディープリンクは機能しますか？