Non Hubspot弹窗表单无法创建联系人问题咨询

根本原因 #

HubSpot 非表单识别功能默认仅在页面首次加载时扫描现有 DOM 中的表单元素。你使用的 Chakra UI 模态框默认开启了挂载懒加载：弹窗未触发打开时，表单元素不会被插入到 DOM 树中，因此 HubSpot 初始扫描无法捕获到该表单，自然不会跟踪提交行为。 #

可用解决方案（按优先级排序） #

方案1：调整模态框渲染逻辑（最简单，无额外逻辑） #

直接禁用 Chakra Modal 的懒加载特性，让表单在页面初始加载时就挂载到 DOM 中（仅处于隐藏状态），HubSpot 初始扫描即可正常识别：

import { Modal } from "@chakra-ui/react"

// 模态框调用处添加两个属性即可
<Modal
  mountOnEnter={false}
  unmountOnExit={false}
  // 保留你原来的其他属性：isOpen、onClose等
>
  {/* 原有弹窗内容、表单组件 */}
</Modal>

如果你的模态框表单字段较多，担心影响首屏性能，可以选择第二种方案。

方案2：弹窗打开时手动触发HubSpot扫描 #

在模态框打开、表单完成挂载后，手动调用 HubSpot 内置的 DOM 扫描方法，识别新插入的表单：

import { Modal } from "@chakra-ui/react"

const handleModalOpen = () => {
  // 延迟执行等待模态框内容完全渲染到DOM
  setTimeout(() => {
    if(window.hubspot?.scanner) {
      window.hubspot.scanner.scan()
    }
  }, 100)
}

<Modal
  onOpen={handleModalOpen}
  // 保留原有其他属性
>
  {/* 原有弹窗内容、表单组件 */}
</Modal>

方案3：手动调用HubSpot表单提交端点（最稳定，不依赖自动扫描） #

如果前两种方案都不生效，可以直接调用 HubSpot 公开表单提交端点，既不需要使用 Contacts API，也能完整保留用户原始来源（自动读取用户本地的hubspotutkcookie，不会被标记为离线）：

1. 先在 HubSpot 后台创建一个和弹窗表单字段完全对应的普通表单，获取你的portalId和该表单的formGuid
2. 在你原有表单的提交逻辑中添加以下请求即可：

const submitForm = async (formData) => {
  const portalId = "你的HubSpot门户ID"
  const formGuid = "你创建的对应表单的GUID"
  await fetch(`https://api.hsforms.com/submissions/v3/integration/submit/${portalId}/${formGuid}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      fields: Object.entries(formData).map(([name, value]) => ({ name, value })),
      context: {
        hutk: document.cookie.split('; ').find(row => row.startsWith('hubspotutk='))?.split('=')[1]
      }
    })
  })
}

排查注意项 #

• 确保弹窗内表单所有字段的name属性和其他正常工作的注册表单完全一致，HubSpot 依赖name属性匹配联系人字段
• 不要在表单提交事件中调用e.preventDefault()后没有后续处理，HubSpot 自动跟踪依赖原生submit事件触发
• 检查 Chakra Modal 的挂载容器配置，默认会挂载到document.body下，如果你的 HubSpot 脚本配置了仅扫描指定 DOM 容器，需要将该容器加入扫描范围，或通过 Modal 的container属性指定挂载到被扫描的容器内。

内容的提问来源于stack exchange，提问作者Andrea Aldana