解决聊天窗口小部件未显示在网站页面上的问题

当您设置实时聊天或基于规则的聊天机器人时，聊天小部件可能不会出现在预期的网页上，或者不会向目标联系人显示。请按照以下步骤排查并解决聊天小工具缺失的最常见原因。

确保已安装跟踪代码

如果您要在 HubSpot 外部托管的网站上添加聊天流，您需要在页面上 安装 HubSpot 跟踪代码 。您可以在设置中访问跟踪代码：

请注意： 如果您的网站上已经安装了 HubSpot 跟踪代码 ，或者您的网站是托管在 HubSpot 上的，则 无需 单独安装此代码片段。

1. 在 HubSpot 帐户中，单击顶部导航栏中的 “设置”图标。
2. 在左侧边栏菜单中，导航至 跟踪 & Analytics > 跟踪代码 。
3. 要复制代码并 将其添加到网站上，请单击 " 复制"。或单击 " 通过电子邮件发送给开发人员 "，然后输入 电子邮件地址 ，将代码发送给网络开发人员或 IT 资源。

添加跟踪代码后，请确认其已正确安装： 

• 如果跟踪代码是手动安装的，请确保已将代码片段原样复制（未作任何修改），并将其安装在页面头部预期的位置。 

• 如果使用标签管理器，请确认 HubSpot 标签已在测试页面上发布并启动。

安装好跟踪代码后，接下来请确认相关聊天流程已启用。

打开聊天流

确认跟踪代码已安装后，请检查聊天流程本身是否已开启。已关闭的聊天流程不会出现在任何网站页面上，无论您的跟踪或定向配置如何。

确认聊天流已打开：

1. 在你的 HubSpot 帐户中，单击更多，然后导航到服务 > 聊天流。如果你的帐户中未显示更多，请直接导航到服务 > 聊天流。
2. 在非活动聊天流旁边的 状态栏 中，单击以打开 状态 开关。
   

启用聊天流程后，请配置其定位规则，使其显示在您希望的外部页面上，例如包含您域名的网站 URL 规则。

查看定向和排除规则

建立聊天流程时，您可以在 目标定位设置中指定聊天窗口小部件应显示在哪些页面上。您还可以根据 访客的已知信息确定目标。在聊天流程的 " 目标 "选项卡 上查看您的 定位规则 ，确保标准与您希望在网站页面上看到的内容一致。

指定正确的域和子域

首先，请确认您希望看到聊天流的页面已包含在目标定位规则中。如果您希望聊天流显示在特定域的页面上，请确保输入正确的域。例如，如果您的定位规则是 Website | contains | www.coffeeshop.com，聊天流将显示在 www 子域上托管的任何页面上，包括 www.coffeeshop.com、www.coffeshop.com/contact 和 www.coffeeshop.com/pricing。

但是，除非您在目标定位规则中添加 博客 子域，否则聊天流 不会 出现在 blog.coffeeshop.com 上。

或者，您也可以在目标定位规则中指定 根域 。在此示例中，如果您使用目标定位规则 Website | contains | coffeeshop.com， 聊天流将出现在具有此根域的任何页面上。

确认用于定位的页面 URL

加载聊天窗口小部件时，它会将页面 URL 发送给 HubSpot，以根据您的目标定位规则决定是否显示聊天流。

检查正在使用的 URL：

1. 在浏览器中打开您的网站。
2. 右键单击页面上的任意位置并选择 " 检查"，或按 Ctrl + Shift + I (Windows) 或 Cmd + Option + I (Mac)，打开开发工具。
3. 单击 网络 选项卡。
4. 刷新页面。
5. 查找与聊天部件相关的请求（例如，请求中包含 conversations 或 messages).
6. 单击请求，然后检查 " 标题 "选项卡。
7. 找到 X-Hubspot-Messages-Uri 标题并查看其值。

确认此标题中的 URL 符合您的聊天流定位规则。例如，包含 https://hubspot.com 开头的 URL 将无法匹配 https://www.hubspot.com 开头的 URL。 www 子域。

如果您的网站使用反向代理，请确保代理在转发请求时保留 X-Hubspot-Messages-Uri 标头。如果没有此标题，聊天窗口小部件可能无法按预期加载。

检查排除规则

如果聊天流未按预期显示，请确保页面 URL 未包含在排除规则中。导航到聊天流程，然后在 目标 选项卡上查看并根据需要删除任何排除规则。

核实访客信息和行为

如果您 根据游客信息和行为定位聊天流程，请确保联系人符合目标标准。例如，如果您的聊天流程只显示给点击了网站上特定 CTA 的联系人，请导航到 联系人记录 并 筛选联系人的 CTA 活动。如果联系人没有点击所选的 CTA，他们将看不到聊天流程。

如果他们确实点击了 CTA，请查看本指南中的其他故障排除步骤，或了解更多有关 跟踪 Cookie 如何影响聊天流是否显示的信息。

检查单页应用程序（SPA）

如果您的网站是单页面应用程序或 SPA，您的定位规则可能无法按预期运行，因为当您导航到其他页面时，SPA 的网站内容是动态更新的，而不是重新加载。HubSpot 无法检测新的页面 URL，这会导致页面上出现错误的聊天流程，或根本无法显示。如果您要在单页面应用程序中使用 即时聊天 或 机器人 ，建议您与开发人员合作，使用 聊天部件 SDK 来定位您的页面。使用 .widget-refresh 方法在不同页面指定不同的聊天流程。了解更多信息，请访问 HubSpot 的 开发人员文档。

检查聊天可用性设置

如果您的聊天流仍未显示在页面上，请检查聊天频道的可用性设置。您可以通过编辑 可用性设置来控制何时隐藏聊天小工具，包括没有团队成员在线或工作时间以外的情况：

1. 在 HubSpot 帐户中，单击顶部导航栏中的 “设置”图标。
2. 在左侧边栏菜单中，导航至 收件箱 & Help Desk：
   • 要编辑连接到对话收件箱的聊天频道， 选择 收件箱 。
   • 要编辑连接到帮助台的聊天频道，请选择 帮助台。然后，在 " 票单来源和路由"下单击 " 通道"。
   • 将鼠标悬停在聊天频道上，然后单击 " 编辑"。
3. 导航至 可用性 选项卡。选择一个选项：

• • 基于用户可用性： 如果您的 分配规则 中至少有一名指定的团队成员可用，游客就可以与您的团队聊天。
  • 基于聊天工作时间： 设置您的团队何时可以聊天，让游客知道何时可以收到回复。
    
    • 使用下拉菜单设置团队的工作时间。单击 + 添加时间 ，添加其他日期和时间范围。
    • 聊天全天候可用：如果您的团队总是可以聊天，请选择此复选框。

4. 在 可用性行为 部分，根据团队的可用性配置聊天体验，让游客知道何时可以收到回复。选择一个选项：

• • 要设置团队可用时游客的体验，请单击 " 可用 "选项卡。单击 " 显示典型回复时间 "下拉菜单，让访客知道何时会收到回复。
  • 要设置团队在工作时间外出时的访客体验，请单击 " 外出 "选项卡。单击 " 显示外出信息 "下拉菜单，选择外出模式 Widget 行为。
    
    
    

  需要订阅 当您的团队达到最大容量时，需要使用 Service Hub Enterprise 订阅 来设置访客体验。

  • 要设置游客在团队达到最大容量时的体验，请单击 " 如果所有团队成员都达到最大容量，则 "下拉菜单，然后选择显示等待消息、隐藏聊天启动器或什么都不做。了解有关 为用户配置聊天容量限制的更多信息。

• • 要设置游客在团队工作时间以外的体验，请单击 " 工作时间以外 "选项卡 ，然后单击 " 设置离线行为 "下拉菜单，选择在游客在工作时间以外访问网站时显示返回时间、显示离开消息或隐藏聊天启动器。

5. 单击 保存。

如果您正在使用包含机器人的聊天流，如果您没有自定义机器人的可用性首选项，聊天流可能仍然会出现。了解如何 根据团队的可用性编辑 聊天流程的显示时间。

了解为什么会出现不同的聊天流程

如果游客在您的一个页面上开始了一个主题，然后导航到另一个页面，在那里应该出现不同的聊天流程，那么对话将在 原始 主题中继续。因此，其他聊天流将不会出现。例如

• 聊天流 A 应该出现在 www.coffeeshop.com上 。
• 聊天流 B 应该出现在 blog.coffeeshop.com上 。
• 一位游客开始与聊天流 A 聊天，然后浏览了 blog.coffeeshop.com。
• 聊天流程 B 将 不会 出现，游客可以继续使用聊天流程 A 开始的主题。

检查聊天流优先级

如果页面上有多个聊天流，您可以决定游客访问网站时 HubSpot 应优先处理哪个聊天流。如果没有出现预期的聊天流，请检查 聊天流 与页面上其他聊天流相比的 优先级 。

检查是否有脚本阻止程序或 cookie 同意限制

如果聊天窗口小部件仍未显示，请检查是否有 Cookie 同意横幅、脚本阻止程序或其他第三方或自定义 JavaScript 阻止 HubSpot 的跟踪脚本加载。有些同意管理平台会阻止 HubSpot 脚本，直到游客接受 Cookie，这样就会阻止聊天窗口小部件的显示。

与你的开发人员合作，确保允许 HubSpot 脚本在适当的时候运行，并 验证没有 第三方工具或浏览器扩展阻止 HubSpot 脚本加载。 

检查 HubSpot 跟踪代码和聊天窗口小部件脚本是否正确加载 

安装好跟踪代码后，请检查它是否能在页面上正确加载。

跟踪代码应出现在页面源代码或 DOM 中，并带有 id 属性 hs-script-loader.

HubSpot 使用特定的脚本 id 属性来防止同一脚本被多次加载。不要在网站的其他地方使用 HubSpot 脚本 ID。如果另一个页面元素已经使用了相同的 ID，HubSpot 可能会认为脚本已经存在，而不再加载。

确认聊天窗口小部件脚本正在加载：

1. 在浏览器中打开您的网站。
2. 打开开发工具，然后查看 网络 选项卡。
3. 搜索 conversations-embed.js.该文件由 HubSpot 跟踪代码加载，应来自包含 usemessages.
4. 确认脚本具有 id 属性 hubspot-messages-loader 并包含所需的数据属性：
• data-hsjs-portal
• data-hsjs-hublet
• data-hsjs-env
5. 搜索 visitor.js.该脚本会加载聊天窗口小部件用户界面，并由 conversations-embed.js.

如果 conversations-embed.js 或 visitor.js 无法加载，请检查浏览器控制台是否存在 JavaScript 错误、内容安全策略错误或其他可能阻止 HubSpot 脚本运行的页面错误。

请注意： 如果账户中没有打开聊天流，跟踪代码可能不包括加载 conversations-embed.js 的代码。打开聊天流后，在更新的跟踪代码开始加载聊天部件脚本之前可能会出现缓存。

如果你的网站执行内容安全策略（CSP），请确保允许使用 HubSpot 脚本域。与 CSP 相关的错误通常会出现在浏览器控制台中，并显示哪个脚本被阻止及其原因。了解有关 HubSpot 内容安全策略设置中的必填域和指令的更多信息。

清除浏览器缓存

如果打开聊天流后它没有出现在您的网站上，请确认您在正确的实时域或环境中进行了测试。如果您最近对网站进行了更改，请等待几分钟或刷新页面。

然后，尝试在隐身浏览器窗口中加载您的网站。如果聊天流在隐身状态下显示，请 清除浏览器缓存和 cookie ，以便在非隐身浏览器窗口中查看聊天流。

了解跟踪 cookie

如果按照上述步骤操作后，您的聊天窗口小部件仍未出现在符合目标条件的联系人中，这很可能是由于 跟踪 cookie 的原因。要让游客看到您的聊天窗口小部件，必须在联系人数据库中将跟踪 cookie 与游客的联系人记录关联起来。如果联系人记录没有跟踪 cookie，那么您的聊天窗口小部件就不会显示给与联系人记录相关联的游客。

访客如何获得跟踪 cookie？

访问者在成为联系人之前，会通过跟踪 cookie 进行匿名跟踪。然后，HubSpot 可以通过两种方式将跟踪 cookie 上的网站活动与联系人记录联系起来：

• 访客填写 HubSpot 表单。
• 访客点击 HubSpot 营销电子邮件，进入 HubSpot 页面或安装了 HubSpot 跟踪代码 的非 HubSpot 页面。

此外，您还可以使用 跟踪代码 API 跟踪 网站访客。

在访客执行上述转换之前，HubSpot 不知道访客是谁，也不知道访客的联系记录属于哪些列表。因此，如果您的联系人尚未转化，即使他们是您数据库中的联系人或您的目标列表成员，他们也不会看到您的聊天窗口小部件。

请注意： 即使游客执行了上述两个操作之一来获取跟踪 cookie，如果游客删除了浏览器 cookie，或在不同的浏览器、隐身窗口或移动设备上访问了您的网站，那么就无法检测到他们的跟踪 cookie，您的聊天窗口小部件也不会出现。

为什么我的联系人没有跟踪 cookie？

以下是一些常见的方法，可以让联系人在不通过表单或点击营销电子邮件链接的情况下存在于您的数据库中：

• 联系人已 导入。
• 联系人是 手动添加的。
• 联系人是通过 记录的销售电子邮件创建的。

一旦数据库中的联系人被跟踪 cookie 跟踪，HubSpot 就会将其视为已知联系人。如果他们符合您的受众标准，您的聊天小工具就会在他们访问您的网站时出现。

请注意： ，在某些情况下，某些浏览器扩展（如弹出窗口、广告或脚本阻止程序）可能会阻止聊天窗口小部件的加载。如果在禁用这些扩展程序后出现了小工具，则可能是其中一个扩展程序阻止了它。