如何创建自定义事件

摘要

在 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 立即开始接收该数据。