如何创建自定义事件

摘要

在 HubSpot 中使用自定义事件，可定义并跟踪您企业特有的事件。自定义事件可与事件属性相关联，随后您可在 HubSpot 的各项工具中使用这些属性。例如，您可能希望跟踪线下活动，如参加线下产品发布会的情况。

了解创建自定义事件的三种不同方法。您可以通过 API 发送自定义事件、上传包含事件数据的电子表格，或使用 webhook（仅限Data HubProfessional 和 Enterprise 版）。

设置自定义事件后，您可以在不同工具中查看相关数据。您可以基于自定义事件数据创建报告、在联系人时间轴上查看事件发生记录，并在工作流中使用自定义事件。

最后，在自定义事件管理工具中跟踪自定义事件的绩效。您可能还需要在自定义事件管理工具中解决未知属性错误。

创建自定义事件有哪些方法？

事件创建过程包括两个部分：

• 在 HubSpot 中定义该事件，包括任何自定义事件属性。
• 创建 JavaScript 代码片段或定义 将触发该事件的 API 调用 。

创建自定义事件有以下几种方式： 

• 通过 API 发送：使用“自定义事件定义”端点创建您的事件。随后，使用您的事件 ID 配合“发送自定义事件”端点，将事件发生记录发送至 HubSpot。
• 无需 API 即可从网站捕获数据：
  • 编写 JavaScript：通过自定义 JavaScript，您可以使用代码编辑器将自定义代码插入到 HubSpot 跟踪脚本中。
  • 使用事件可视化工具：通过在网站上选择目标元素，追踪页面浏览量或点击元素。了解如何使用事件可视化工具创建自定义事件。
• 导入电子表格：上传包含事件数据的电子表格，以捕获离线活动、补全数据，或手动将任何工具与 HubSpot 集成。
• 设置 Webhook（数据中心 仅限专业版 和企业版）：自定义触发 Webhook 的条件以及将发送的数据。 

请注意：在旧版“自定义事件”工具中创建的任何事件，自 2025 年 8 月 1 日起将不再有效。

如何通过 API 创建自定义事件？

如果您是通过 API 将数据发送至 HubSpot，可以使用“通过 API 发送”选项 ，或 使用自定义事件定义端点来创建事件 。有关如何定义 API 调用的更多信息，请参阅HubSpot 开发者文档。

您需要为 API 调用准备几项信息，这些信息可在 HubSpot 内部获取：

• 事件名称：该事件的内部名称。 
• 属性名称：您将向其发送数据的属性的内部名称。

要完成事件创建并通过 API 发送数据：

• 选择“将数据发送至 HubSpot”，并 复制跟踪 ID。
• 点击“创建”。

查找现有事件的内部事件名称及属性名称：

1. 在您的 HubSpot 账户中，导航至“数据管理”>“事件管理”。
2. 点击事件名称。随后您将进入事件详情页面。
3. 在页面顶部，找到“内部名称”下的事件名称。要复制内部名称，请点击名称旁边的复制图标。 
   
   
   
4. 要查找您将要更新的属性的内部名称，请点击某个属性的名称。
5. 在右侧面板中，点击代码图标，然后查看“内部名称”下的名称。

如何使用 JavaScript 代码创建自定义事件？

1. 在您的 HubSpot 账户中，导航至“数据管理”>“事件管理”。
2. 在右上角，点击“创建事件”，然后选择“创建自定义事件”。
3. 选择“JavaScript 代码”。

4. 输入“事件名称”，并可选填“事件描述”。
5. 选择“关联对象”。这使您能够将事件发生与 HubSpot 中的不同对象（包括联系人、公司、商机和 工单）相关联。 

6. 点击“下一步”。

如何向事件添加属性？

创建事件时，将提供默认的事件属性。您也可以创建自己的自定义属性。事件属性与其他 CRM 属性分开存储，且专属于该事件（即您无法通过账户设置编辑这些属性）。 

1. 若要关闭默认事件属性的创建，请将“默认事件属性”切换为“关闭”。
2. 若要创建自定义属性，请点击该属性的“字段类型”以选择属性类型。选项包括： 
   • 自定义字符串属性：创建一个纯文本字符串属性。 
   • 自定义数字属性：创建一个数值属性。
   • 自定义时间戳属性：创建一个日期值的属性。您必须以纪元毫秒或 ISO8601 格式发送数据。
   • 自定义日期属性：创建一个日期值的属性。
   • 自定义布尔属性：创建一个布尔值属性。 
   • 自定义枚举属性：创建一个包含一组预定义值的属性。
3. 选择属性后，请在右侧面板中配置该属性：

8. 为属性输入名称，并输入属性描述。
   • 对于枚举属性，请点击“下一步”，然后输入属性的“标签”和“值”。
     • 枚举属性可设置为单选或多选。若要启用多选功能，请打开“支持多选”开关。

• • • 在向字段发送数据前，必须先设置其值和标签。如果在发送列表中未包含的数据前未完成此步骤，该数据将无法使用。若需通过 API 发送多个值，请用分号分隔。

9. 点击“下一步”。
10. 设置完事件及其属性后，您可以通过选择“JavaScript 代码片段”将此事件添加到网站的跟踪代码中。
11. 点击“完成”。

使用 JavaScript 代码片段创建事件，可自动将 JavaScript 代码添加到您的 HubSpot 跟踪代码中。这可用于捕获跟踪代码默认无法捕获的更复杂的事件数据。 

1. 选择“JavaScript 代码片段”。使用右侧面板中的代码片段在 HubSpot 中跟踪该事件。任何创建的自定义属性都将在代码片段中预先定义。 
2. 根据需要在右侧面板中输入文本来修改代码片段。您添加的任何代码都将自动作为 HubSpot 跟踪代码的一部分。
3. 完成后，点击“创建”以 完成事件设置并自动开始跟踪。
    
   
   

如何从电子表格导入自定义事件数据？

您可以上传线下活动的参会数据、来自未与 HubSpot 集成的应用程序的带时间戳数据、来自供应商的一次性潜在客户或营销活动数据，或任何其他以电子表格形式呈现的活动数据。活动功能可帮助您捕获用户行为，并将其应用于 HubSpot 的各个环节。 

导入操作可 创建和更新以下 记录：

• 联系人

• 公司
• 商机
• 工单
• 服务
• 项目
• 预约
• 课程
• 列表 
• 订单
• 自定义对象

所需属性因对象类型而异。

事件导入仅适用于已发生的事件。 自定义事件导入文件必须包含以下内容：

• 联系电子邮件地址。
• 发生于时间戳。了解有关导入文件中日期属性格式的更多信息。

示例文件

导入自定义事件的方法：

1. 在 HubSpot 帐户中，导航到数据管理 > 事件管理。
2. 在右上角，点击“创建活动”，然后选择“创建自定义活动”。
3. 选择“导入电子表格”。
4. 点击“创建新活动”或“导入到现有活动”。
   • 如果您选择“导入到现有活动”，请使用下拉菜单选择现有活动，然后继续执行步骤上传电子表格。
   • 如果您选择“创建新活动”，请继续执行以下步骤。
5. 输入活动名称，并可选填活动描述。
6. 选择关联对象。目前，通过导入创建的活动只能与联系人关联。
7. 上传电子表格或直接从电子表格中粘贴。选择导入对象的方式和文件语言，然后点击“下一步”。
8. 将列映射到事件和联系人属性，然后点击“下一步”。
9. 确认导入文件的名称。
10. 勾选复选框，表示您同意联系人期待收到您的消息，且您的导入文件不包含购买的列表。了解有关HubSpot 合理使用政策的更多信息。
11. 选择“发生时间”属性的日期格式。
12. 点击“完成导入”。

如何通过 API 端点发送自定义事件？

1. 在您的 HubSpot 账户中，导航至“数据管理”>“活动管理”。
2. 在右上角，点击“创建活动”，然后选择“创建自定义活动”。
3. 选择“通过 API 发送”。

4. 输入“事件名称”，并可选填“事件描述”。 

5. 要添加自定义事件属性：
   • 输入属性名称。该名称也将作为内部名称使用。
   • 点击“字段类型”下拉菜单，并选择字段类型。
   • 可选：添加描述。
   • 若要添加更多自定义属性，请点击“+ 添加自定义属性”。
   • 点击“下一步”。

6. 要关联对象：
   • 点击“选择主对象”下拉菜单，然后选择一个关联对象。这使您可以将事件发生记录与不同的对象（包括联系人、公司、商机和工单）建立关联。
   • 点击“自定义匹配”，并在事件与对象记录之间选择匹配 ID。只有当两者的匹配 ID 完全一致时，事件才会与对象记录建立关联。如果您使用自定义匹配 ID，所选的对象属性必须要求值唯一。
7. 点击“下一步”。
8. 要在 HubSpot 中跟踪该事件，请点击跟踪 ID 旁边的“复制”。
9. 点击“创建事件”。

如何使用 webhook 创建自定义事件？

设置将触发 Webhook 的条件。

1. 在您的 HubSpot 账户中，导航至“数据管理”>“事件管理”。
2. 在右上角，点击“创建事件”，然后选择“创建自定义事件”。
3. 选择“设置 Webhook”。
4. 输入“事件名称”并选择“关联对象”。
5. 点击“下一步”。
6. 设置测试事件：
   • 复制Webhook URL。 
   • 在您想要集成的第三方应用中，导航至Webhook 设置页面。
   • 粘贴已复制的 URL。
   • 点击“发送测试事件”。
7. 点击“下一步”。
8. 查看 Webhook 的属性。点击“属性类型”下拉菜单以选择属性类型。 

9. 点击“下一步”。
10. 从您的第三方 Webhook 中选择一个与 HubSpot 对象属性完全匹配的属性。 

在 HubSpot 中，我可以在哪里查看和使用自定义事件数据？

您可以在 HubSpot 的各项工具中查看和使用自定义事件数据。下面，了解在哪里查看事件发生情况，以及如何将这些数据整合到其他工具中。

您可通过事件列表中的操作下拉菜单、单个事件视图，或“分析”标签页中图表的右上角，直接在选定的 HubSpot 工具中打开所选事件。

如何使用自定义事件数据创建报告

您可以在“自定义事件”工具中分析自定义事件的发生情况，同时事件数据也将在自定义报告生成器和归因报告中提供。

了解有关分析自定义事件的更多信息。

如何在联系人时间轴上查看事件发生情况？

事件发生记录将显示在联系人记录的时间轴上，并附带已填充的任何属性。

要在联系人时间轴上查看事件详情：

1. 导航至发生过自定义事件的联系人记录。
2. 若要按事件发生情况筛选联系人时间轴，请点击“筛选活动”，然后选择“自定义事件”。
3. 在联系人时间轴中，点击展开该事件以显示事件详情。

请注意：您无法查看使用 webhook 创建的自定义事件的时间轴活动。

如何在工作流中使用自定义事件？

在工作流中，您可以使用 延迟至事件发生 操作 或事件加入触发器，根据自定义事件的发生来设置延迟。

1. 在 HubSpot 帐户中，导航到自动化 > 工作流。
2. 点击工作流的名称。或者，了解如何创建新工作流。
3. 要添加触发器：
   • 在工作流编辑器中，点击“设置触发器”。
   • 在左侧面板中，选择“当事件发生时”。设置触发器后，点击“应用过滤器”。
   • 若要进一步优化触发器，请点击“添加细化筛选条件”。您可以选择其他属性，以筛选出希望纳入工作流的对象。
   • 默认情况下，记录仅在首次满足加入触发器条件时加入工作流。若要启用重新加入功能，请在“是否应将 [对象] 重新加入此工作流？”部分中，选择“是，每次触发时重新加入”。
4. 添加延迟：
   • 在工作流编辑器中，点击“+”号图标添加工作流操作。
   • 在右侧面板中，选择“延迟至事件发生”。
   • 配置延迟：
     • 点击“事件”下拉菜单，然后选择一个自定义事件。
     • 然后，选择您希望延迟的事件属性。
     • 为该事件属性选择筛选条件。
     • 点击“应用筛选器”。
   • • 选择最大等待时间，或选中“尽可能长时间延迟”复选框 。
5. 点击“保存”。

请注意：所有事件注册触发器将使用“或”运算符进行分隔。这意味着只需其中一个事件注册触发器发生，记录即可注册到工作流中。

随后，工作流将延迟已加入的记录，直到它们满足指定的自定义事件条件，或者在事件发生时被触发。

如何管理、跟踪自定义事件的状态并监控交付错误？

为确保数据准确且集成按预期运行，您可以使用“事件管理”工具中的“监控”选项卡。

如何在自定义事件管理工具中跟踪性能？

• 完成趋势：在 HubSpot 帐户中，导航到数据管理 > 事件管理。 单击“监控”选项卡，比较不同时间段的事件完成量。

• 故障排除交付错误：在 HubSpot 帐户中，导航到数据管理 > 事件管理。在“监控”选项卡的左侧边栏中，选择“交付错误”。此表列出了同步失败的事件，并提供了失败的具体原因（例如，数据类型不匹配或架构违规）。

如何解决自定义事件管理工具中的“未知属性”错误？

如果通过 API 发送的数据包含 HubSpot 中从未定义过的属性，该属性将出现在错误日志中。您可以快速解决此问题：

1. 将鼠标悬停在“错误日志”表格中的事件上。

2. 点击“操作”，然后选择“向事件添加属性”。

3. 确认建议的字段类型，以便 HubSpot 立即开始接收该数据。