# WhatsAppの広告クリックアトリビューション

MetaやGoogleの広告を自社サイトのページに誘導し、そのページにWhatsAppボタンを設置している場合、<span data-t="appName">DM Champ</span>を使用すると、各WhatsAppの会話がどの広告クリックから発生したものかを把握できます。ウェブサイトに小さなスクリプトを1つ貼り付けるだけで設定は完了です。訪問者がWhatsAppボタンをタップすると、そのクリックが記録され、送信された最初のメッセージと照合されます。その後、連絡先情報にその連絡先がどのキャンペーンから来たものかが表示され、クリックデータはWebhookやAPIを通じて、必要に応じてMetaに送り返すことも可能です。

これは、ランディングページ、予約ページ、価格ページ、あるいは「回答をWhatsAppで送信」で終わるクイズなど、WhatsAppボタンがあるあらゆるページで機能します。

> このページは、まず**あなたのウェブサイト**にユーザーを誘導する広告に関するものです。広告から直接WhatsAppを開く場合（Metaの「Click to WhatsApp」広告）、スクリプトなしで自動的に[Click-to-WhatsApp広告アトリビューション](click-to-whatsapp-attribution.md)でカバーされます。

---

## 設定方法

1. **設定 → 広告クリック追跡**（統合グループ）に移動します。
2. **有効にしてスクリプトを取得**をクリックします。アカウント固有のサイトキーと1行のスクリプトが発行されます。
3. スクリプトをコピーし、WhatsAppボタンがあるすべてのページの終了`</body>`タグの直前に貼り付けます。

{% code overflow="wrap" %}
```html
<script src="https://api.dmchamp.com/v1/ad-visit/YOUR_SITE_KEY.js" async></script>
```
{% endcode %}

4. オプション：**WhatsApp番号**の下に、ボタンのリンク先となる番号を入力します。入力した場合、その番号へのリンクのみが追跡されます。空欄にすると、サイト上のすべてのWhatsAppリンクが追跡されます。
5. お問い合わせ番号の文言を選択し（下記参照）、**保存**をクリックします。設定を変更した後、ウェブサイト上のスクリプトを修正する必要はありません。
6. テスト：キャンペーンタグが付いたリンク（例：`https://yoursite.com/?utm_source=test&utm_campaign=setup-check`）からページを開き、自分のWhatsAppボタンをタップしてメッセージを送信します。チャットでその連絡先を開くと、連絡先パネルにキャンペーン情報とともに**広告クリックから発生**と表示されます。

サイトキーはスクリプト内に含まれています。これはパスワードではないため、公開ページに配置しても問題ありません。

::: master-only
**代理店の方へ：** クライアントのアカウントごとに独自のサイトキーとスクリプトがあるため、各クライアントのウェブサイトはそれぞれのアカウントにレポートされます。他の設定セクションと同様に、メニューの表示設定を使用してクライアント用のセクションを非表示にすることができます。
:::

---

## スクリプトの動作

- **ページ読み込み時**：ページアドレスに含まれる広告クリックIDとキャンペーンタグ（`utm_`パラメータ）をブラウザタブのセッションストレージに保持します。これにより、訪問者が最初に別のページを見た場合でもデータが維持されます。Cookieの設定や他の読み込み、データの送信は行われません。
- **訪問者がWhatsAppリンクをタップした時**（`wa.me`、`api.whatsapp.com/send`、または`whatsapp://send`）、メッセージにお問い合わせ番号を追加し、訪問を記録した上で、通常通りWhatsAppへのタップ処理を続行します。

タップするまで<span data-t="appName">DM Champ</span>には何も送信されません。

---

## お問い合わせ番号

店舗やクリニックが発行する参照番号のような短い番号が、訪問者のWhatsAppメッセージに追加されます。これにより、<span data-t="appName">DM Champ</span>はどの広告クリックがどの会話に対応しているかを正確に把握します。メッセージは以下のように表示されます：

```
Hi, I would like to know more.
Enquiry no. 4827
```

- **文言：** デフォルトは「Enquiry no.」です。「Booking ref」や「Ref」など、ビジネスに合わせて自然な1行のテキストを使用できます。数字は含められません。
- **位置：** 「独自の最終行」（デフォルト）または「テキストの末尾」から選択できます。設定ページでライブプレビューを確認できます。
- **長さ：** 4桁。サイトのアクセス数が多い場合は5桁になります。
- **AIエージェントには表示されず**、繰り返されることもありません。受信トレイには、番号を含めたメッセージ全体が表示されます。

問い合わせ番号をオフにすることができます。その場合、マッチングはメッセージのテキストのみに基づいて行われるため、まったく同じテキスト（例：同じクイズの回答）を送信した2人の訪問者を区別できなくなり、一部のクリックがマッチングされなくなります。

---

## 独自のクイズまたはボタンコード

ページ上でWhatsAppメッセージ自体を構築する場合（回答をテキストに含めるクイズや、独自のボタンコードなど）、scriptタグに `data-manual` を追加してください：

{% code overflow="wrap" %}
```html
<script src="https://api.dmchamp.com/v1/ad-visit/YOUR_SITE_KEY.js" data-manual async></script>
```
{% endcode %}

`data-manual` を使用すると、スクリプトはWhatsAppリンクを自動的に変更しなくなります。独自のコードがWhatsAppを開く直前にスクリプトを呼び出すため、各訪問が1回ずつ記録されます：

- `window.ChatAttribution.text(finalText, number)` は、問い合わせ番号を追加したテキストを返し、訪問を記録します。返されたテキストをWhatsAppリンクで使用してください。
- `window.ChatAttribution.link(finalText, number)` も同様の処理を行い、そのテキストを含む準備済みの `wa.me` リンクを返します。番号を省略すると、設定の **WhatsApp番号** にある番号が使用されます。

{% code overflow="wrap" %}
```html
<script>
  function sendAnswers(answers) {
    var text = "Hi, my answers: " + answers.join(", ");
    if (window.ChatAttribution) {
      window.location.href = window.ChatAttribution.link(text, "+15551234567");
    } else {
      window.location.href = "https://wa.me/15551234567?text=" + encodeURIComponent(text);
    }
  }
</script>
```
{% endcode %}

`else` ブランチは、ブラウザの拡張機能によってスクリプトがブロックされた場合など、スクリプトが読み込まれていない状態でもボタンが機能するようにします。スクリプトが発行した番号がすでに含まれているテキストは、二度と変更されることはありません。

---

## 記録される内容

タップ時に、訪問記録には以下が保持されます：

- ページアドレス内の広告クリックID（`fbclid`（Meta）や `gclid`（Google）など）
- 独自のMetaピクセルがサイト上で設定している場合、`_fbc` および `_fbp` クッキー（スクリプトはこれらを読み取るだけで、設定は行いません）
- キャンペーンタグ（`utm_source`、`utm_medium`、`utm_campaign`、`utm_content`、`utm_term`）
- ランニングページ、訪問者の参照元ページ、ブラウザ、およびメッセージテキスト
- 訪問が到着した際に <span data-t="appName">DM Champ</span> によって追加されるIPアドレスと時刻

訪問記録は **90日間** 保持されます。訪問がマッチングされると、そのクリックデータのコピーが連絡先に保存され、削除するまで連絡先に残り続けます。

**プライバシー通知について：** スクリプトはあなたのウェブサイト上で実行されるため、サイトのプライバシー通知にその旨を記載する必要があります。具体的には、何を記録するのか（上記のリスト）、および訪問者がWhatsAppボタンをタップした際に記録が行われることを明記してください。

---

## マッチングの仕組み

連絡先から最初のメッセージが届くと、<span data-t="appName">DM Champ</span> はその **15分前** までの訪問記録を探します：

1. **まず問い合わせ番号で検索。** スクリプトが発行した番号が含まれるメッセージは、その訪問とマッチングされます。
2. **次に同一テキストで検索。** 訪問記録とまったく同じテキストを持つメッセージは、その訪問とマッチングされます。同じ時間枠内に2人の異なる訪問者が同じテキストを送信した場合、誤った広告に連絡先が紐付けられることを防ぐため、意図的にどちらもマッチングされません。

問い合わせ番号が含まれる後続のメッセージも、その連絡先にまだマッチングが存在しない限り、マッチングされます。

制限事項：

- **最初に一致したものが優先されます。** 一度コンタクトが一致すると、上書きされることはありません。
- **WhatsAppのみ：** WhatsApp Business APIおよびWhatsApp Webチャネルが対象です。
- **15分以内：** ボタンをタップしてからメッセージ送信までの時間が15分を超えると、一致とはみなされません。
- **今後のみ有効：** スクリプトをインストールする前のコンタクトは一致しません。

---

## 表示場所

- **コンタクトパネル：** キャンペーンやソース、日付とともに **広告クリックから流入** と表示されます。詳細を確認するにはホバーしてください。
- **Webhook：** [エージェントタグWebhook](webhooks.md#contact-tags-updated-webhook) 内の `contact.ad_attribution`、およびコンタクト情報を含むすべてのWebhookサブスクリプションイベントに表示されます。
- **API：** APIリファレンスの「コンタクト」セクションにある、コンタクトリストの `ad_attribution` および単一コンタクトの `adAttribution` に表示されます。
- **MCPツール：** 返されるすべてのコンタクトオブジェクトに含まれます。

コンタクトが一致しない場合、値は `null` になります。

| フィールド | 内容 |
|---|---|
| `visit_at` | 訪問者がWhatsAppボタンをタップした日時。 |
| `matched_at` | 訪問がコンタクトと一致した日時。 |
| `match_method` | `reference`（問い合わせ番号で一致）または `text`（同一のメッセージテキストで一致）。 |
| `reference` | 問い合わせ番号。オフの場合は `null`。 |
| `fbc` / `fbp` | Metaピクセルが存在する場合のMetaクリックおよびブラウザクッキー。 |
| `fbclid` | ページアドレスに含まれるMeta広告クリックID。 |
| `gclid` / `gbraid` / `wbraid` | ページアドレスに含まれるGoogle広告クリックID。 |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | ページアドレスに含まれるキャンペーンタグ。 |
| `landing_url` | 訪問者が最初にアクセスしたページ。 |
| `referrer` | 訪問者が遷移元としたページ。 |
| `client_ip` | 訪問者のIPアドレス。 |
| `user_agent` | 訪問者のブラウザ。 |
| `site_key` | 訪問を記録したスクリプトのサイトキー。 |
| `visit_id` | 訪問記録のID。 |

---

## Metaへの結果送信（オプション）

<span data-t="appName">DM Champ</span> を使用して、成果をMeta広告アカウントにレポートできます。これにより、Metaはどの広告が実際のリードや売上につながっているかを学習し、最適化を図ることができます。これには、お客様自身のMetaコンバージョンAPIの詳細情報を使用します。

1. Metaイベントマネージャで、「データソース」からピクセル（データセット）IDを確認し、「設定」>「コンバージョンAPI」>「**アクセストークンの生成**」からアクセストークンを作成します。
2. **設定** > **広告クリック追跡** の **Metaへの結果送信（オプション）** に、**ピクセル / データセットID** と **アクセストークン** を入力します。テスト時にはMetaの「テストイベント」タブから取得した **テストイベントコード** を追加できます（完了後は削除してください）。「**Metaの詳細を保存**」をクリックします。
3. エージェントエディタを開き、「**タグ**」タブからタグを選択します。「**Metaへ送信**」でイベント（**リード**、**コンタクト**、**スケジュール**、**購入**、またはカスタム名）を選択します。必要に応じて値と通貨を追加します。

以降、そのタグがコンタクトに適用されるたびに（AI、手動、API、または自動化経由）、<span data-t="appName">DM Champ</span> はコンタクトの保存されたクリックデータ（`fbc`、`fbp`、IPアドレス、ブラウザ、ランディングページ）に加え、ハッシュ化された電話番号、メールアドレス、名前をMetaに送信し、広告との紐付けを可能にします。一致しないコンタクトの場合でも、ハッシュ化された電話番号、メールアドレス、名前のみがイベントとして送信されます。

- **重複カウントの防止：** 各イベントには、コンタクトIDとタグ名から生成された固定IDが付与されます。CRMが同じイベントを同じIDでMetaに送信した場合、Metaは1つだけを保持します。
- **Metaの属性期間：** Metaは、デフォルトでクリック後7日間の属性期間内にあるイベントのみを広告の成果としてカウントします。数週間後に成立した取引はそれ単体ではカウントされないため、予約や支払い完了時など、より早い段階のイベントも送信してください。

---

## よくある質問

**広告から直接WhatsAppを開く場合でも機能しますか？**
そのような広告はウェブサイトを経由しないため、スクリプトは実行されません。代わりに、Metaが最初のメッセージとともに広告の詳細を送信します。[Click-to-WhatsApp広告の属性](click-to-whatsapp-attribution.md) を参照してください。

**スクリプトによってウェブサイトの速度が低下したり、クッキーが設定されたりしますか？**
スクリプトはバックグラウンドで読み込まれ（`async`）、クッキーの設定や他の読み込みは行いません。訪問者がWhatsAppボタンをタップしたときのみ情報を送信します。

**Meta広告だけでなくGoogle広告も追跡できますか？**
はい。GoogleクリックID（`gclid`、`gbraid`、`wbraid`）およびキャンペーンタグは記録され、コンタクト情報に表示されます。結果の送信機能はMetaのみ利用可能です。

**コンタクトが一致しなかったのはなぜですか？**
主な理由は、タップからメッセージ送信まで15分以上経過した、メッセージから問い合わせ番号が削除された、問い合わせ番号機能がオフの状態で別の訪問者が同じテキストを送信した、またはページにスクリプトが設置されていないなどが考えられます。

**ウェブサイトに2つのWhatsApp番号へのリンクがあります。片方だけ追跡できますか？**
はい。設定の **WhatsApp番号** にその番号を入力してください。空欄にすると、すべてのWhatsAppリンクが追跡されます。

**後から文言を変更できますか？**
はい。変更内容はすぐにウェブサイトに反映されます。スクリプトを再度貼り付ける必要はありません。