# WhatsApp 广告点击归因

如果您投放了 Meta 或 Google 广告并将其引导至您自己的网站页面，且该页面包含 WhatsApp 按钮，<span data-t="appName">Your AI Connector</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.youraiconnector.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 按钮并发送消息。在“聊天”中打开该联系人：联系人面板会显示 **来自广告点击** 以及对应的广告系列。

站点密钥已包含在脚本中。它不是密码，因此放在公开页面上是安全的。


---

## 脚本的工作原理

- **页面加载时**，它会将页面地址中的广告点击 ID 和广告系列标签（`utm_` 参数）保留在浏览器标签页的会话存储中，以便访客先查看其他页面时这些信息依然存在。它不会设置 Cookie，不会加载其他内容，也不会发送任何数据。
- **当访客点击 WhatsApp 链接**（`wa.me`、`api.whatsapp.com/send` 或 `whatsapp://send`）时，它会将查询编号添加到消息中，记录访问情况，并让点击按正常流程跳转至 WhatsApp。

在点击之前，不会向 <span data-t="appName">Your AI Connector</span> 发送任何信息。

---

## 查询编号

一个短编号（类似于商店或诊所给您的参考号）会被添加到访客的 WhatsApp 消息中。这就是 <span data-t="appName">Your AI Connector</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.youraiconnector.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">Your AI Connector</span> 在访问到达时添加

当访问被匹配时，<span data-t="appName">Your AI Connector</span> 还会根据该数据大致推算出访客的位置（通过 IP 地址推算的城市和国家/地区）以及他们使用的设备（例如手机、平板电脑或计算机，操作系统和浏览器，例如 Instagram 应用内浏览器）。当无法推算出位置时，该字段将保持为空，这在移动网络上很常见。

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

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

---

## 匹配的工作原理

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

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

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

当一个已经有匹配记录的联系人通过另一个广告再次进入并发送了一条带有更新的查询编号的消息时，该点击会被保留为联系人的**最新点击**。首次匹配记录保持不变。

- **首次点击，用于您的报告：** 联系人将持续显示其最初的来源。这一点永远不会改变。
- **最新点击，用于 Meta：** 发送给 Meta 的事件使用最新的点击记录，因为 Meta 会将转化归因于将用户带回的广告，且仅在其归因窗口内有效。报告旧的点击记录会归因到错误的广告，或者根本无法归因。
- 最新点击仅通过查询编号获取，绝不会仅通过匹配文本获取，且旧的访问记录永远不会替换较新的记录。

限制：

- **首次匹配永远不会被覆盖。** 较新的点击会进入最新点击字段。
- **仅限 WhatsApp：** WhatsApp Business API 和 WhatsApp Web 渠道。
- **15 分钟：** 点击按钮但很久之后才发送消息的访问者将不会被匹配。
- **仅限未来：** 在您安装脚本之前产生的联系人没有匹配记录。

---

## 查看位置

- **联系人面板：** **来自广告点击**，包含广告系列或来源以及首次点击的日期。悬停以查看详细信息：广告系列、**广告** (`utm_content`) 和 **广告组** (`utm_term`)、大致的 **位置** 和 **设备**（仅在已知时显示），以及如果有最新点击，还会显示相同信息。从未填写的广告系列标签（广告预览点击会发送标签模板而不是名称）将被忽略。只有当页面是通过广告链接（Meta 或 Google 点击 ID，或广告系列标签）打开时，访问才会被计为广告点击。任何通过其他方式到达页面的人，例如通过 Google 搜索、输入您的地址或点击您的网站，都会显示 **来自您的网站** 以及他们的来源，例如 **Google 搜索**，或者当浏览器未提供信息时显示 **网站访问，未记录引荐来源**。
- **联系人页面：** 相同的行位于 **联系人** 中联系人姓名的下方，因此您可以直接看到它，在手机上也一样。悬停或点击它以查看详细信息。
- **活动：** 联系人的时间轴以点击时的 **在广告后点击了您的 WhatsApp 按钮**（或 **在您的网站上**）开头，位于他们的第一条消息之前。聊天联系人面板在 **活动** 下方显示相同的行。
- **Webhooks：** `contact.ad_attribution` 在 [代理标签 webhooks](webhooks.md#contact-tags-updated-webhook) 中以及每个携带联系人的 webhook 订阅事件中。
- **API：** `ad_attribution` 在联系人列表上，`adAttribution` 在单个联系人上，位于 API 参考的“联系人”部分。
- **MCP 工具：** 他们返回的每个联系人上的相同对象。

当联系人没有匹配记录时，该值为 `null`。以下字段描述了首次点击。当匹配到后续点击时，`latest` 会使用相同的字段存储该点击；在此之前该字段不存在。

| 字段 | 说明 |
|---|---|
| `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` | 访客的浏览器。 |
| `geo_country` / `geo_region` / `geo_city` / `geo_timezone` | 通过 IP 地址推算的大致位置：两个字母的国家/地区代码、区域代码、城市和时区。未知时为空。 |
| `device_type` / `device_os` / `device_browser` | 浏览器识别的设备：`mobile`、`tablet` 或 `desktop`，带有版本的操作系统（例如 `iOS 18.3`）和浏览器（例如 `Safari` 或 `Instagram in-app`）。未知时为空。 |
| `site_key` | 记录该访问的脚本的站点密钥。 |
| `visit_id` | 访问记录的 ID。 |
| `latest` | 首次点击后匹配的最新点击，包含相同的字段。用于发送给 Meta 的事件。如果没有，则为空。 |

---

## 将结果发送至 Meta（可选）

您可以让 <span data-t="appName">Your AI Connector</span> 将结果回传至您的 Meta 广告账户，以便 Meta 了解哪些广告带来了真正的潜在客户和销售，并据此进行优化。此功能使用您自己的 Meta 转化 API 详情。

1. 在 Meta 事件管理工具中，在“数据源”下找到您的像素（也称为数据集）ID，并在“设置”、“转化 API”、“**生成访问口令**”下创建访问口令。
2. 在 **设置 → 广告点击追踪** 中，在 **发送结果至 Meta（可选）** 下，输入 **像素 / 数据集 ID** 和 **访问口令**。点击 **保存 Meta 详情**。
3. 可选：检查连接。在 Meta 事件管理工具中，打开您的像素并转到 **测试事件** 选项卡，复制显示的测试代码，将其粘贴到 **发送测试事件** 下，然后点击 **发送测试事件**。按钮下方的行会显示“Meta 已收到 1 个测试事件”（请在 Meta 的“测试事件”下查看），或者在被拒绝时显示 Meta 的原因，例如口令错误。该代码仅用于该次测试，不会被保存。
4. 打开代理编辑器，转到 **标签** 选项卡并打开一个标签。在 **发送至 Meta** 下，选择事件：**潜在客户 (Lead)**、**联系 (Contact)**、**预约 (Schedule)**、**购买 (Purchase)** 或自定义名称。您可以选择添加金额和货币。

从那时起，每当该标签应用于联系人（通过 AI、手动、通过 API 或自动化）时，<span data-t="appName">Your AI Connector</span> 就会将该事件发送给 Meta，并附带联系人的最新点击数据（`fbc`、`fbp`、IP 地址、浏览器、着陆页，若存在最新点击则使用最新点击数据，否则使用首次点击数据）以及经过哈希处理的电话、电子邮件和姓名，以便 Meta 将其与广告关联。没有匹配记录的联系人仍会发送事件，但仅包含经过哈希处理的电话、电子邮件和姓名。

- **实时事件始终计数：** 测试事件代码永远不会与您的 Meta 详情一起存储，因此您的标签和自动化发送的事件始终会进入您在 Meta 中的真实数据，而不会进入“测试事件”选项卡。
- **不会重复计数：** 每个事件都有一个由联系人 ID 和标签名称组成的固定 ID。如果您的 CRM 向 Meta 发送了具有相同 ID 的相同事件，Meta 只会保留一个。
- **Meta 的归因窗口：** Meta 仅将广告归因窗口内的事件计入广告效果，默认情况下为点击后 7 天。几周后才完成的交易不会自动计入，因此也请发送较早的事件，例如针对已预订或已付费咨询的标签。

---

## 从自动化流程发送转化

标签在被应用时会发送其事件。当结果发生在其他地方时（例如 CRM 中的交易关闭或预约了咨询），请在自动化流程中使用 **发送转化到 Meta** 操作。它通过转化 API 将一个事件报告给您的 Meta 数据集，以便 Meta 不仅根据消息，还能根据实际结果来优化您的广告。

它使用与标签相同的 Meta 详细信息：**设置 → 广告点击跟踪**下的 **Pixel / 数据集 ID** 和 **访问令牌**。如果没有这些信息，该步骤将失败并显示“Meta 未连接”。

**字段**

| 字段 | 功能描述 |
|---|---|
| **事件名称** | 必填。**Purchase**（购买）、**Schedule**（预约）、**Lead**（潜在客户）或您自定义的名称。自定义名称使用字母、数字、空格和下划线，以字母开头，最多 40 个字符。 |
| **金额** 和 **货币** | 转化金额，例如交易金额。货币为 3 位字母代码，默认为 EUR。仅在您填写时才会发送金额。 |
| **联系人** | 可选。转化所属的联系人。 |
| **电子邮件**、**电话**、**名字**、**姓氏** | 人员详细信息。当该人员不是联系人时，或为了补充联系人已有信息时填写。 |
| **您自己的人员 ID** | 来自您自己系统的人员 ID，例如 CRM ID。 |
| **事件 ID** | Meta 用于对事件进行去重计数的 ID。请参阅下文。 |
| **事件时间** | 转化发生的时间，以 Unix 秒数或日期表示。最多可追溯至 7 天前。留空则使用步骤运行的时间。 |
| **页面 URL** | 转化所关联的页面（如有）。 |
| **测试事件代码** | 仅用于测试运行：来自 Meta“测试事件”选项卡的测试代码。使用此代码发送的事件会显示在“测试事件”下，且不会计入您的广告效果。实时事件请留空。 |

至少填写 **联系人**、**电子邮件** 或 **电话** 中的一项。该人员不必是联系人：达到“赢单”状态的 HubSpot 交易可以发送包含交易金额和买家电子邮件的“购买”事件。

当您选择一个 **联系人** 时，将使用其电话、电子邮件和姓名。如果他们来自脚本匹配到的广告点击，点击详情也会一并发送，这有助于 Meta 将事件与广告进行匹配。电子邮件、电话和姓名在发送前会进行哈希处理。点击 ID、IP 地址和浏览器信息将按 Meta 要求发送。

**事件 ID 与重复计数**

Meta 会将具有相同事件名称和相同事件 ID 的事件计为一次。当其他工具也报告相同的转化，或者自动化流程可能为此运行两次时，请使用固定的 ID（例如交易 ID）。留空则每次运行都会生成一个新的 ID，因此每次运行都会被计数。

**它与标签事件的区别**

标签的 **发送到 Meta** 事件对于每个联系人，每个标签只会发送一次（30 天内最多一次）。此操作在每次运行时都会发送。事件 ID 是防止转化被重复计算的机制。

**示例：已关闭的交易和已预约的咨询**

1. 启动一个在交易达成时运行的自动化：在您的 CRM 交易事件上设置一个 **App event**（应用事件）触发器，并添加一个 **Condition**（条件），以便仅处理已达成的交易。HubSpot 仅向开发者应用发送交易阶段事件，因此对于 HubSpot，请使用 **Schedule**（计划）触发器，配合 HubSpot 搜索功能查找自上次运行以来达到“已达成”（Closed Won）状态的交易，并使用 **Loop**（循环）遍历它们。
2. 添加 **Send conversion to Meta**（发送转化至 Meta）。将 **Event name**（事件名称）设置为 **Purchase**（购买），将 **Value**（价值）设置为交易金额（使用 **+** 按钮插入），并将 **Currency**（货币）设置为您的货币。在 **Email**（电子邮件）中填入买家邮箱，在 **Event ID**（事件 ID）中填入交易 ID，以确保同一笔交易不会被重复计算。
3. 对于预约咨询，请使用 **Appointment booked**（预约已预订）触发器启动第二个自动化，并添加 **Send conversion to Meta**（发送转化至 Meta），将 **Event name**（事件名称）设置为 **Schedule**（预约），并在 **Contact**（联系人）中填入触发器中的联系人信息。如果需要，您可以添加第二个 **Send conversion to Meta**（发送转化至 Meta）步骤，发送一个具有固定价值（例如咨询价格）的 **Purchase**（购买）事件。

您也可以通过 `POST https://api.youraiconnector.com/v1/ad-attribution/meta-event` 使用 API 发送转化。它采用相同的蛇形命名法字段：`event_name`、`value`、`currency`、`contact_id`、`email`、`phone`、`first_name`、`last_name`、`external_id`、`event_id`、`event_time`、`event_source_url` 和 `test_event_code`。

---

## 常见问题

**如果我的广告直接打开 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 链接。

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