3：开发者实现

此页面介绍手动集成，内容涵盖以下方面：

为 CRM 集成构建有效负载
生成访问口令和准备 API 调用
发送测试有效负载
发送生产数据

此部分的内容仅适用于您决定使用手动集成方式和开发者资源来完成 CRM 集成的情况。如果您决定通过合作伙伴来完成 CRM 集成，请按照相应合作伙伴的说明进行集成。合作伙伴集成完成后，您可以跳到此指南的 4：验证数据部分。

您需要拥有商务管理平台管理员权限，才能完成这些集成步骤。如果您之前获邀成为开发者，可通过发送给您的邮件获取权限。否则，请联系商务管理平台管理员，请求获得权限。

第 1 步：构建有效负载

这个步骤将阐明高潜客户集成的有效负载规范，并就如何从您的服务器发送有效负载提供一些建议。

从您 CRM Pixel 像素代码的设置选项卡打开 CRM 集成指南，开始操作。

参阅转化 API 开发者指南，了解转化 API 如何运作。

建议使用有效负载设置助手来构建有效负载。有效负载设置助手会设置有效负载的格式，并检查是否存在错误。解决了所有有效负载错误后，点击有效负载设置助手中的获取代码按钮，以便生成所用编程语言的代码模板。

以下是必要参数清单。请参阅高潜客户集成 - 有效负载规范指南，查看每个参数的完整描述。该有效负载规范应仅用于“高潜客户优化”事件。这意味着，事件应仅与 Meta 潜客广告相关，而且应具有有效的潜在客户编号。避免将该有效负载规范用于其他事件类型（例如“网站潜在客户”事件）。

参数

名称	描述
`event_name` 字符串	自由格式的字段，用于获取您在 CRM 中使用的潜在客户阶段。 `event_name` 参数应表明潜在客户在 CRM 销售漏洞中的阶段更进一步。请务必在潜在客户出现任何阶段（包括原始潜在客户阶段）更新时发送事件。
`event_time` 整数	Unix 时间戳（以秒为单位），表示 CRM 更新潜在客户阶段更新事件的时间。该时间戳必须晚于潜客开发广告开始投放的时间，否则事件可能会被弃用。
`action_source` 字符串	值：`system_generated` （使用转化 API，即表示您同意：就您所知，`action_source` 参数准确无误。）
`lead_id` 整数	已下载的潜客信息中的 15 或 16 位数 `leadgen_id`。
`lead_event_source` 字符串	事件来源 CRM 的名称。
`event_source` 字符串	值：`crm`

示例
有效负载示例可能如以下所示。注意：您必须使用有效的 lead_id，否则系统会拒绝您的事件。

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

如果事件不遵循有效负载规范或与 Meta 潜客广告不匹配，这些事件不会获得集成认可，也不会用于模型训练。
例如，此网络有效负载将被转化 API 接受，并且会显示在事件管理工具中，但不会获得这个集成认可。您还必须使用有效的 lead_id，否则系统会拒绝您的事件。
只有高潜客户有效负载才会获得集成认可，并用于训练。

第 2 步：创建访问口令和 API 调用

配置要发送的内容之后，下一步是配置数据发送的目标位置。

这个步骤将帮助您生成 Meta Pixel 像素代码的访问口令，后续该口令将用于在您的服务器和转化 API 之间建立连接。

从 CRM Pixel 像素代码的设置选项卡中可以返回到 CRM 集成指南。

向下滚动到创建端点部分，然后点击生成访问口令按钮。该访问口令将用于构建 API 调用。
生成新访问口令的方法有两种：返回 CRM 集成指南；或前往事件管理工具中的设置选项卡，导航到转化 API 部分，然后点击生成访问口令链接。

此指南的其余部分将根据您是否使用 Meta 的 SDK 而有所不同。建议使用 Meta Business SDK，因为该 SDK 可以提供更好的错误和诊断消息服务。您需要拥有 Pixel 像素代码编号和访问口令，才能通过 Meta Business SDK 执行 API 调用。如要获取访问口令，您可以在 CRM 集成指南中点击复制访问口令并保存该口令。如需 SDK API 调用示例，请参阅转化 API 开发者指南或使用 Meta 有效负载设置助手中的获取代码功能。

以下是在不使用 SDK 的情况下，向转化 API 执行 POST 请求所使用的端点格式。如要获取整个端点，您可以在 CRM 集成指南中点击复制端点并保存该端点。
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION：当前的市场营销 API 版本
- PIXEL_ID：可以从每个 Pixel 像素代码的事件管理工具中获取 Pixel 像素代码编号
- ACCESS_TOKEN：通过上述步骤生成的访问口令
您可以在 API 版本文档中看到市场营销 API 的发行日期和到期日期。请务必在市场营销 API 的到期日期之前在代码中更新 API 版本或 Meta Business SDK。在代码中使用已停用的版本可能会导致出现错误，而且系统可能会弃用您的事件。

第 3 步：测试有效负载（可选）

此时，在服务器上实现代码之前，您可能希望向 Pixel 像素代码发送测试有效负载。如要执行此操作，您可以使用事件管理工具中的测试事件选项卡。

在测试服务器事件，点击图谱 API 探索工具链接。如果您使用该专属链接，系统会预填您 Pixel 像素代码中的一些信息。（根据需要，您也可以直接访问图谱 API 探索工具。）请注意 test_event_code 值，该值会随着时间的推移而改变。

在图谱 API 探索工具中完成以下事项：
1. 确保您处于 POST 模式。
2. 确保 API 版本和 Pixel 像素代码编号都正确无误。
3. 切换到 JSON 视图。
4. 输入您的有效负载。如要获取有效负载，您可以手动创建，也可以使用有效负载设置助手生成。请务必加入上一步中的 test_event_code 参数和有效的 lead_id。
输入 Pixel 像素代码访问口令，然后点击提交按钮。

如果有效负载不包含任何语法或 API 错误，您应该会收到一条包含 fbtrace_id 的成功消息。

短时间之后，测试事件应该会显示在事件管理工具的测试事件选项卡下方。

第 4 步：发送生产数据

生产数据的格式应与第 3 步中生成的有效负载格式相同，但生产数据将直接来自您的服务器。对于每个集成，这个步骤有所不同，所以此部分将提供指南，而不是演示。

发送 lead_id（而不是个人身份识别信息 (PII)）以进行匹配。

确保在潜在客户出现任何阶段更新时发送事件，其中包括原始潜在客户事件（该事件代表已在 Meta 上开发潜在客户，而且潜客信息已下载到您的 CRM 中）。下方是漏斗示例。事件名称和阶段由广告主定义，因此无需与下方示例一致。

如果您的广告系列开发了 100 个潜在客户，我们预计会上传 100 个“原始潜在客户”事件来代表第一个潜在客户阶段。发送第一个潜在客户阶段会告知系统：潜客信息已收到并得到处理。随着潜在客户沿着销售漏斗向下移动，我们预计会上传 70 个“营销合格潜在客户”、30 个“销售机会”和 15 个“已转化”阶段。

总的来说，通过这些广告系列可以开发出 100 个潜在客户，但我们预计在这个场景示例中会上传 215 个事件。

创建一个函数，用于在潜在客户状态更新时，从 CRM 的 API 或数据库中检索更新。然后使用一个自定义函数或 Meta Business SDK 将您的有效负载发送到 Meta 转化 API。至于哪种方法对您的集成最有效，这取决于您的 CRM 和数据库配置。

建议为以下参数使用变量：

lead_id
event_name
event_time

例如，如果有效负载明确规定参数值，可能如下所示：

{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

如果有效负载使用变量传递您数据库中的值，可能如下所示：

{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

每天至少上传一次数据。理想情况下，对 CRM 的调用应该实时执行，但是如果实时集成不可行，您可以使用按小时或按天批处理的方法。
如果您选择批处理方法，请确保在批处理时捕获潜在客户状态更改历史记录，而不是潜在客户的快照。例如，如果某位潜在客户的状态在不同批次之间更新了 3 次，则应该为这位潜在客户发送 3 个事件，而不只是最后一次更新的事件。
注意：每个批次最多可包含 1,000 个事件。如果批次中出现错误，整个批次将被弃用，因此我们强烈建议在尝试重试时使用较小的批次并添加逻辑。

可选。建议记录 CAPI 调用中出现的错误消息，并在出现问题时创建提醒。对这些错误进行异常处理，也是个不错的主意。

您可以回填过去最多 7 天的数据。时间差是根据 event_time 与 upload_time 计算得出。回填一些数据可能会加快训练流程。
警告：请勿试图通过修改 event_time 值来回填超过 7 天的数据。该模型依赖于准确的时间戳来进行优化。如果违反该警告，可能会导致所有回填数据都被弃用。
确保您的 event_time 值设在潜客开发广告时间戳之后，否则事件可能被弃用。

如果您的集成将事件上传到 Meta，您 Pixel 像素代码的事件管理工具应该会在一小时内开始显示这些事件。记得在有效负载中使用有效的 lead_id，只有这样系统才会显示事件。在事件管理工具中打开高潜客户 CRM 集成已发送的每个事件，并确认事件中是否已填充自定义参数 lead_event_source 和 event_source。如果事件中没有这些参数，该事件不会被报告为“高潜客户”事件。
系统会验证您的全部事件是否都是有效的“高潜客户”事件。1 天后，如果系统检测到有效事件，该集成的发送 CRM 事件步骤旁会显示一个绿色勾号。

< 2: Getting Started With the CRM Integration

4：验证数据 >