# WhatsApp 广告点击归因

如果您投放了 Meta 或 Google 广告并将其引导至您自己的网站页面，且该页面包含 WhatsApp 按钮，<span data-t="appName">DM Champ</span> 可以告诉您每条 WhatsApp 对话来自哪次广告点击。您只需在网站上粘贴一小段脚本。当访客点击您的 WhatsApp 按钮时，系统会记录该点击并将其与他们发送给您的第一条消息进行匹配。随后，联系人信息中会显示其来源的广告系列，且点击数据会随联系人同步到 Webhook、API 中，如果需要，还可以回传给 Meta。

这适用于任何带有 WhatsApp 按钮的页面：落地页、预订页面、价格页面或以“通过 WhatsApp 发送我的答案”结尾的问卷。

> 本页面介绍的是先将用户引导至**您的网站**的广告。如果您的广告直接打开 WhatsApp（Meta 的“点击跳转至 WhatsApp”广告），则无需脚本，系统会自动处理，详见 [点击跳转至 WhatsApp 广告归因](click-to-whatsapp-attribution.md)。

---

## 设置方法

1. 前往 **设置 → 广告点击追踪**（集成组）。
2. 点击 **开启并获取我的脚本**。您的账户将获得专属的站点密钥和一行脚本。
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”。不能包含数字。
- **位置：** **在最后一行单独显示**（默认）或 **在文本末尾**。设置页面会显示实时预览。
- **长度：** 4 位数字，当您的网站流量非常大时为 5 位。
- **您的 AI 代理永远不会看到它**，也不会重复它。收件箱会显示完整消息，包括编号。

您可以关闭查询编号。此时匹配仅基于消息文本，因此发送完全相同文本（例如相同的测验答案）的两名访客将无法被区分，且部分点击将无法被匹配。

---

## 您自己的测验或按钮代码

如果您的页面自行构建 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 之前调用它，因此每次访问都会被记录一次：

- `window.ChatAttribution.text(finalText, number)` 返回添加了查询编号的文本，并记录此次访问。请在您的 WhatsApp 链接中使用返回的文本。
- `window.ChatAttribution.link(finalText, number)` 执行相同操作并返回一个带有该文本的现成 `wa.me` 链接。省略编号以使用设置中 **WhatsApp number** 下的编号。

{% 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)
- `_fbc` 和 `_fbp` cookie（如果您的 Meta Pixel 已在您的网站上设置它们；脚本仅读取，从不设置它们）
- 广告系列标签 (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`)
- 着陆页、访客来源页面、浏览器和消息文本
- IP 地址和时间，由 <span data-t="appName">DM Champ</span> 在访问到达时添加

访问记录保留 **90 天**。当访问被匹配时，其点击数据的副本会存储在联系人信息中，并保留在该联系人名下，直到您将其删除。

**您的隐私声明：** 该脚本在您的网站上运行，因此您网站的隐私声明应提及它：它记录了什么（上述列表），以及在访客点击 WhatsApp 按钮时会进行记录。

---

## 匹配的工作原理

当联系人的第一条消息到达时，<span data-t="appName">DM Champ</span> 会查找 **15 分钟** 内的访问记录：

1. **首先按查询编号。** 携带脚本发放编号的消息会匹配到对应的访问记录。
2. **否则按相同文本。** 文本与某次访问完全相同的消息会匹配到该记录。当两名不同的访客在时间窗口内发送了相同的文本时，出于安全考虑，两者均不会被匹配，以确保联系人永远不会被错误地归因于错误的广告。

只要联系人尚未匹配，后续携带查询编号的消息也会被匹配。

限制：

- **首次匹配成功即锁定。** 一旦联系人匹配成功，就不会再被覆盖。
- **仅限 WhatsApp：** 适用于 WhatsApp Business API 和 WhatsApp Web 渠道。
- **15 分钟限制：** 如果访客点击了按钮，但过了很久才发送消息，则不会进行匹配。
- **仅限后续：** 在您安装脚本之前产生的联系人不会有匹配记录。

---

## 查看位置

- **联系人面板：** **来自广告点击**，包含广告系列或来源以及日期。将鼠标悬停可查看详情。
- **Webhooks：** `contact.ad_attribution` 位于 [座席标签 webhooks](webhooks.md#contact-tags-updated-webhook) 中，以及每个携带联系信息的 webhook 订阅事件中。
- **API：** `ad_attribution` 位于联系人列表，`adAttribution` 位于单个联系人页面，详见 API 参考文档的“联系人”部分。
- **MCP 工具：** 每个返回的联系人对象中均包含相同信息。

当联系人没有匹配项时，该值为 `null`。

| 字段 | 说明 |
|---|---|
| `visit_at` | 访客点击 WhatsApp 按钮的时间。 |
| `matched_at` | 访客与联系人匹配的时间。 |
| `match_method` | `reference`（通过咨询编号匹配）或 `text`（通过相同的消息文本匹配）。 |
| `reference` | 咨询编号，若已关闭则显示为 `null`。 |
| `fbc` / `fbp` | 若存在，则为来自您 Meta 像素的 Meta 点击和浏览器 Cookie。 |
| `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** 下，选择事件：**潜在客户 (Lead)**、**联系人 (Contact)**、**预约 (Schedule)**、**购买 (Purchase)** 或自定义名称。您可以选择添加价值和货币。

此后，每当该标签应用于联系人时（无论是通过 AI、手动、API 还是自动化），<span data-t="appName">DM Champ</span> 都会将该事件发送给 Meta，并附带联系人存储的点击数据（`fbc`、`fbp`、IP 地址、浏览器、着陆页）以及经过哈希处理的电话、电子邮件和姓名，以便 Meta 将其与广告关联。即使联系人没有匹配项，仍会发送事件，仅包含经过哈希处理的电话、电子邮件和姓名。

- **无重复计算：** 每个事件都有一个由联系人 ID 和标签名称组成的固定 ID。如果您的 CRM 向 Meta 发送了具有相同 ID 的同一事件，Meta 只会保留一个。
- **Meta 的归因窗口：** Meta 仅在归因窗口内将事件归因于广告，默认情况下为点击后 7 天。几周后成交的订单不会自动计入，因此请发送更早的事件，例如针对已预订或已支付咨询的标签。

---

## 常见问题

**如果我的广告直接打开 WhatsApp，这还能用吗？**
这些广告不会经过您的网站，因此脚本不会运行。Meta 会在第一条消息中发送广告详情，请参阅 [Click-to-WhatsApp 广告归因](click-to-whatsapp-attribution.md)。

**脚本会拖慢我的网站或设置 Cookie 吗？**
它在后台加载（`async`），不设置任何 Cookie，也不加载其他内容。只有当访客点击 WhatsApp 按钮时，它才会发送数据。

**我可以同时跟踪 Google 广告和 Meta 广告吗？**
可以。Google 点击 ID（`gclid`、`gbraid`、`wbraid`）和任何广告系列标签都会被记录并显示在联系人信息中。将结果回传功能目前仅支持 Meta。

**为什么联系人没有匹配成功？**
最常见的原因包括：消息在点击后超过 15 分钟才发送、消息中的咨询编号被删除、咨询编号功能已关闭且另一位访客发送了相同文本，或者页面未安装脚本。

**我的网站链接到两个 WhatsApp 号码。我可以只跟踪其中一个吗？**
可以。在设置中的**WhatsApp 号码**下输入该号码。留空则表示跟踪所有 WhatsApp 链接。

**我可以稍后更改措辞吗？**
可以。更改会立即应用到您的网站；您无需再次粘贴脚本。