detour-onboarding

開発者が Detour を最初から理解し、セットアップできるようサポートする、親しみやすいオンボーディングガイドです。

Detour は Software Mansion によるオープンソースのディファードディープリンク SDKです。アプリがまだインストールされていない場合でも、ユーザーをアプリ内の特定のコンテンツに誘導できます。リンクのコンテキストは App Store／Play Store からのインストール後も保持され、アプリの初回起動時に取得されます。

Detour の機能

次の流れを説明します。

1. ユーザーが Detour リンクをクリックします（例：https://yourorg.godetour.link/APP_HASH/articles/2）
2. Detour がデバイスのフィンガープリントデータとともにクリックを記録し、アプリストアにリダイレクトします
3. インストール後、アプリを初めて起動すると SDK がマッチ API を呼び出します
4. Detour がインストールとクリックを照合し、元の遷移先 URL を返します
5. 初回起動時でも、アプリが適切な画面に遷移します

ディファードリンクに加えて、Detour はユニバーサルリンク（iOS）とアプリリンク（Android）にも対応しています。アプリがすでにインストールされている場合に、リンクから直接アプリを開く機能です。

デフォルトのリンク形式

標準的な Detour リンクの形式は次のとおりです。

https://YOUR_ORG.godetour.link/APP_HASH/your/path?param=value

例：https://matitest.godetour.link/VnAqasAabE/articles/2

APP_HASH は、ダッシュボードでアプリに対して生成される一意の識別子です。その後に続くパスとクエリ文字列が、アプリ内の遷移先になります。

ショートリンクは別の機能で、任意です。［Link Settings］タブで作成するキャンペーン固有のエイリアスです。デフォルトのリンク形式と混同しないでください。デフォルトのリンクは、追加の手順なしでアプリ作成直後から利用できます。

---

ステップ 0 — 最初に確認する

プラットフォームごとの手順に入る前に、次の2つの質問をまとめてユーザーに確認します。

1. どのプラットフォーム向けに開発していますか？

   • React Native（Expo または bare）
   • iOS（ネイティブ Swift）
   • Android（ネイティブ Kotlin/Java）
   • Flutter

2. Detour アカウントをすでにお持ちで、ダッシュボードでアプリを設定済みですか？

アカウントがある場合は、フェーズ 2 に進みます。それ以外の場合は、フェーズ 1 から始めます。

---

フェーズ 1 — ダッシュボードのセットアップ

プラットフォームに関係なく、一度だけ行います。

1. アカウントを作成する

• app.godetour.dev で登録し、メールアドレスを確認します

2. 組織を作成する

• 組織にはアプリ、リンク、チームメンバーをまとめます
• 一意のサブドメインを選択します。これがすべてのディファードリンクのベース URL になります。 https://YOURORG.godetour.link

3. アプリを作成する

ダッシュボードによって、次の情報が自動生成されます。

• App ID — SDK の初期化に使用します
• Publishable API Key — SDK の呼び出しの認証に使用します
• App Hash — デフォルトのディファードリンク URL の一部です（https://YOURORG.godetour.link/APP_HASH/...）

4. アプリを設定する（3つのタブ）

［Link Settings］タブ：

• Web Fallback Redirect URL を設定します。デスクトップや非対応のブラウザーのリダイレクト先です
• まずはパラメーター転送をデフォルトのままにします
• ショートリンクは任意です。特に必要でない限り、今はスキップします

［App Configuration］タブ：

• iOS： Bundle ID、Apple Team ID、App Store ID
• Android： Package name（アプリで設定した値と完全に一致する必要があります）、SHA-256 署名証明書のフィンガープリント
• これらを設定すると、Detour が apple-app-site-association と assetlinks.json ファイルを自動でホストできるようになります
• このタブでは、Android 用のすぐに使える intent-filter のスニペットも生成されます。必ずここからコピーし、手作業で記述しないでください

［API Configuration］タブ：

• Publishable API Key と App ID をコピーします。環境変数に保存し、コードに直接記述しないでください

フェーズ 1 の完了後、ユーザーはサブドメイン、App ID、Publishable API Key、App Hash を用意できている状態になります。

---

フェーズ 2 — ユニバーサルリンクとアプリリンク

ユニバーサルリンク（iOS）とアプリリンク（Android）を使うと、Detour のリンクから、アプリがインストール済みの場合にブラウザーを経由せず直接アプリを開けます。Detour は必要な検証ファイルを自動的にホストします。

必要な変更は、アプリ内で Detour のドメインを登録することだけです。該当するリファレンスファイルを読み込んでください。

• React Native → references/react-native.md — 「Universal / App Links」セクション
• iOS → references/ios.md — 「Universal Links」セクション
• Android → references/android.md — 「App Links」セクション
• Flutter → references/flutter.md — 「Universal / App Links」セクション

---

フェーズ 3 — SDK の統合

ユーザーのプラットフォームに対応するリファレンスファイルを読み込んでください。

• React Native → references/react-native.md
• iOS → references/ios.md
• Android → references/android.md
• Flutter → references/flutter.md

生成したコードを、インストール済みの SDK に照らして検証してください。 これらのリファレンスファイルは厳選されていますが、公開済み SDK の内容に追いついていない場合があります。インストール済みのパッケージを正としてください。生成したコードを確定する前に、使用するシンボル（エクスポート、メソッドシグネチャ、列挙型の値、設定フィールド）を、ユーザーのプロジェクトに実際にインストールされているものと照合してください。React Native の場合は node_modules/@swmansion/react-native-detour の型、Flutter の場合はプラグインの lib/、iOS と Android の場合は SDK の公開ヘッダー／ソースを確認してください。インストールする現行 SDK バージョンは、固定された番号を前提とせず、レジストリまたは README で確認してください。インストール済み SDK とこのリファレンスの内容が異なる場合は、インストール済み SDK に従い、相違点をユーザーに伝えてください。

すべてのプラットフォームに共通する概念

linkProcessingMode は、SDK が処理するリンクのソースを制御します。

モード	ディファード	ユニバーサルリンク／アプリリンク	カスタムスキーム
all（デフォルト）	はい	はい	はい
web-only	はい	はい	いいえ
deferred-only	はい	いいえ	いいえ

特別な理由がない限り、all から始めてください。

リンク結果オブジェクト — すべてのプラットフォームで次の値が返されます。

• route — ナビゲーションにそのまま使える完全なパスとクエリ文字列（例：/articles/2?ref=campaign）
• pathname — クエリ文字列を含まないパス
• params — キーと値のマップとして解析されたクエリパラメーター
• url — 元の完全な URL
• type — deferred、verified（ユニバーサルリンク／アプリリンク）、または scheme

アプリの再開時に再度ナビゲーションが発生しないよう、ナビゲーション後は必ず clearLink() を呼び出すか、インテントを消費してください。

---

フェーズ 4 — アナリティクス

Detour は次の項目を自動的に追跡します（コードは不要です）。

• クリック数 — Detour リンクへのアクセスごと
• リンク経由のインストール数 — クリックに紐づけられたインストール数
• フォールバック — Web のフォールバック先にリダイレクトされたユーザー
• オーガニック／非オーガニック — アトリビューションの有無によるインストール数

ダッシュボードの表示：概要（トレンドと継続率）、リンク（キャンペーンごとの日別データ）、イベント（カスタム SDK イベント）。

手動でのイベント追跡

DetourEventNames／DetourEventName 列挙型の値を使って DetourAnalytics.logEvent を呼び出してください。標準イベントには列挙型の値のみが受け付けられるため、カスタムのイベント名文字列を独自に作成しないでください。

// Correct — enum value
DetourAnalytics.logEvent(DetourEventNames.Purchase, { revenue: 29.99 })

// Wrong — "article_opened" does not exist in the enum
DetourAnalytics.logEvent("article_opened", {})

列挙型に対応する値がないイベントには、内容を説明する文字列を指定して logRetention を使ってください。

DetourAnalytics.logRetention("article_opened")

プラットフォームごとの構文はリファレンスファイルに記載されています。継続率は、最初の logRetention 呼び出しから最大 30 日間追跡されます。

---

フェーズ 5 — アーキテクチャとマッチングの仕組み

ユーザーから「誰がインストールしたかをどうやって判別するのか」と質問された場合や、信頼性について知りたい場合に説明します。

決定論的マッチング（Android）

Play Store が正確な click_id を含むインストールリファラーを渡すと、Detour はその値を直接検索します。完全一致するため、非常に信頼性が高い方法です。

確率的マッチング（iOS および Android のフォールバック）

click_id がない場合、Detour は最近の未照合クリックとインストールを照合し、スコアを算出します。

シグナル	ポイント
IP アドレスの完全一致	500
デバイスモデル＋OS バージョン	450
ユーザーエージェントのデバイスシグネチャ	350
iOS のペーストボードトークン	350
タイムゾーン	200
画面サイズ	200
言語	100

デフォルトのしきい値：850 ポイント（700～1200 に設定可能）。時間枠：15 分（5～180 分に設定可能）。

既知の制限 — 事前に伝える

• iCloud Private Relay／VPN — IP を難読化するため、最も大きなシグナルが弱まります
• iOS のペーストボードへのアクセス拒否 — ユーザーがクリップボードへのアクセスを拒否すると、350 ポイントを失います
• 広告ネットワークのリダイレクトチェーン — click_id が取り除かれ、Android で確率的な方法が強制される場合があります
• Play Store のリファラー情報の欠落 — サイドロードやプリインストールではリファラーデータがありません
• 共有デバイス — 類似したフィンガープリントを持つ複数のユーザーによって、誤検出のリスクが生じます
• 機密データのルーティングや財務上の判断には適していません

---

フェーズ 6 — テスト

ディファードリンクのテスト手順

1. 先にアプリをアンインストールします。アンインストール後にのみリンクをクリックしてください
2. 実機のブラウザーでデフォルトの Detour リンクをクリックします：https://YOUR_ORG.godetour.link/APP_HASH/your/path
3. アプリをインストールします（ストアへのリダイレクトから）
4. アプリを開きます。SDK が数秒以内にマッチング API を呼び出します
5. link オブジェクトに想定したルートが設定されていることを確認します

重要： ディファードリンクをテストするには、毎回アプリを先にアンインストールする必要があります。アプリがインストールされた状態でリンクをクリックすると、ディファードリンクではなく Universal Link／App Link として解決されます。また、ディファードリンクのテストには毎回新しいリンクが必要です。同じデバイスでは、同じリンクによるディファードリンクの解決は 2 回目以降に実行されません。

**初回テストでは短縮リンクを使用しないでください。**まず、デフォルトの https://ORG.godetour.link/APP_HASH/path 形式でテストします。

Universal Link／App Link のテスト

アプリがインストールされた状態でリンクをクリックします。ブラウザーを経由せず、アプリが直接開くはずです。

Android 12 以降については、references/android.md のテストのセクションを参照してください。デバッグ APK では adb による手動の有効化が必要です。

アプリを実行する前に

正しい実行コマンドについて、必ずプロジェクトの README または package.json のスクリプトを確認してください。npx react-native run-android と決めつけないでください。多くのプロジェクトでは npm run android またはカスタムスクリプトを使用しています。

---

一般的なルール

• フェーズを飛ばさないでください。必ずすべてのフェーズを順番に完了し、次に進む前にユーザーに確認してください
• すべてのコードでプレースホルダーを使用してください：YOUR_API_KEY、YOUR_APP_ID、YOUR_ORG。実際の認証情報を尋ねないでください
• Android App Links では、必ず Detour Dashboard から intent-filter のスニペットをコピーしてください。手動で記述しないでください
• アナリティクスでは、logEvent に DetourEventNames／DetourEventName 列挙型の値のみを使用してください。イベント名の文字列を独自に作成しないでください
• 短縮リンクは任意であり、デフォルトのリンクとは別のものです。標準的なセットアップの一環として作成を提案しないでください
• 詳細なリファレンスについては、detour.swmansion.com/docs を案内してください