Heap分析问题：自定义事件属性仅跟踪首个值

问题场景 #

在React单页应用中使用以下自定义Hook绑定Heap事件属性：

export function useHeapAddEventCaseCode(caseData?: CaseEntity) {
  return useEffect(() => {
    if (caseData?.code) {
      // As a best practice, we recommend calling clearEventProperties before addEventProperties on every page
      window.heap.clearEventProperties() 
      window.heap.addEventProperties({ caseCode: caseData.code })
    }
  }, [caseData])
}

遇到异常：仅能跟踪到caseCode的第一个值，切换其他case code后，Heap分析平台始终无法显示新值；控制台打印的heap数组中存在其他caseCode，但未上报/展示在平台。

核心原因与解决方法 #

1. 精准清除单个属性，避免全局缓存干扰 #

clearEventProperties()会清除所有全局事件属性，可能导致Heap内部缓存逻辑异常。改用removeEventProperty精准清除caseCode，同时处理caseData为空的场景：

export function useHeapAddEventCaseCode(caseData?: CaseEntity) {
  useEffect(() => {
    if (caseData?.code) {
      window.heap.removeEventProperty('caseCode')
      window.heap.addEventProperties({ caseCode: caseData.code })
    } else {
      // 无case数据时主动清除属性，避免残留旧值
      window.heap.removeEventProperty('caseCode')
    }
  }, [caseData])
}

2. 手动触发事件上报，强制同步新值 #

SPA页面切换无浏览器刷新，Heap可能不会自动同步属性变化。添加自定义跟踪事件，确保平台接收最新值：

export function useHeapAddEventCaseCode(caseData?: CaseEntity) {
  useEffect(() => {
    const caseCode = caseData?.code
    if (caseCode) {
      window.heap.removeEventProperty('caseCode')
      window.heap.addEventProperties({ caseCode })
      // 触发自定义事件，携带当前caseCode完成上报
      window.heap.track('Case Code Updated', { caseCode })
    } else {
      window.heap.removeEventProperty('caseCode')
    }
  }, [caseData])
}

3. 修正useEffect依赖，确保触发时机正确 #

React的useEffect依赖是浅比较，如果caseData是同一对象引用仅内部code变化，Hook不会重新执行。直接依赖caseData?.code确保值变化时触发：

export function useHeapAddEventCaseCode(caseData?: CaseEntity) {
  useEffect(() => {
    const caseCode = caseData?.code
    if (caseCode) {
      window.heap.removeEventProperty('caseCode')
      window.heap.addEventProperties({ caseCode })
      window.heap.track('Case Code Updated', { caseCode })
    } else {
      window.heap.removeEventProperty('caseCode')
    }
  }, [caseData?.code])
}

4. 检查Heap的SPA模式配置 #

确保Heap初始化时开启SPA支持，避免路由切换时跟踪失效：

// Heap初始化代码示例
window.heap.load('YOUR_PROJECT_ID', {
  autocapture: true,
  trackPageViews: true,
  spa: true // 明确开启SPA路由跟踪
});

额外排查点 #

• 查看Heap控制台的Live View，实时验证事件是否携带最新caseCode
• 检查浏览器控制台是否有Heap相关报错（如跨域、脚本加载失败）
• 注意Heap数据上报存在1-5分钟延迟，不要立即刷新平台查看

内容的提问来源于stack exchange，提问作者Huy Nguyen