网络 SDK - 故障排除与最佳实践

关注
Avatar
Jared Ornstead
Updated
文件

概述

本指南涵盖常见的实施问题、最佳实践和解决方案，可帮助您避免跟踪问题并确保数据准确性。

常见实施错误

错误 1：重复实施（本地 + GTM）

问题：最常见的错误是同时实施本地 JavaScript SDK 和 Google Tag Manager SDK。这会导致每个会话和事件都被跟踪两次，使所有指标膨胀 200%。

重要！Singular 不会自动重复计算事件。使用这两种实现方法会重复计算所有数据。

如何识别此问题：

  • 检查网站源代码中的 Singular SDK 脚本
  • 检查 Google 标签管理器中的 Singular 标签
  • 在浏览器开发工具中，通过singular 过滤网络请求，并计算页面加载时的请求数量（应为 1 个，而非 2 个）

解决方案：

  1. 决定使用哪种实现方法（建议使用本地 JS）
  2. 完全删除其他实现方法
  3. 进行测试以验证每个事件只触发一个请求
  4. 监控数据 24-48 小时，确保指标恢复正常

错误 2：产品 ID 格式不正确

问题：使用了错误的产品 ID 格式。在所有子域中，Web 应用程序的产品 ID 应保持一致。

常见错误：

  • 使用网站 URL： www.mycompany.com ❌
  • 使用破折号：my-company-store ❌
  • 使用前向 DNS：mycompany.com.store ❌
  • 使用空格：my company store ❌

正确格式（反向 DNS 符号）：

  • com.mycompany ✓

提示！将您的产品 ID 想象成移动应用程序捆绑标识符。使用小写字母，以反向域名开头，并使用点来分隔组件。

如何识别此问题：

  • 在开发人员工具中检查网络请求 - 查找 400 或 403 错误
  • 通过浏览器开发工具验证请求有效载荷中的i 参数。
  • 检查浏览器控制台中的错误

解决方案：

  1. 从奇异应用页面获取正确值（BundleId）
  2. 用正确的格式更新您的实现
  3. 测试并验证网络请求中的 200 状态代码

错误 3：事件触发多次

问题：由于页面重载、用户快速点击或缺乏重复数据删除逻辑，事件会多次触发。这会导致事件计数和转换数增加。

常见原因

  • 用户多次快速点击按钮
  • 每次页面呈现时都运行事件代码（React、Vue、Angular 应用程序）
  • 未阻止默认行为的表单提交
  • 页面刷新或返回按钮导航
  • Google 标签管理器触发器多次触发

重要！与某些分析平台不同，Singular 不会自动重复事件。您有责任实施安全机制，防止重复跟踪。

解决策略：

查看实施指南中的策略，了解更多详情。本地 JS、GTM

错误 4：SDK 无法加载

问题：Singular SDK 脚本无法加载，导致无法跟踪。

常见原因：

  • 脚本被广告拦截器拦截（主要影响 GTM）
  • 内容安全策略（CSP）限制
  • 脚本放置在页面上的错误位置
  • 执行代码中的语法错误
  • 网络连接问题

如何诊断

  1. 打开浏览器开发工具控制台选项卡
  2. 查找提及 "singular "或 "sdk "的错误
  3. 在控制台中键入typeof singularSdk - 应该返回 "函数"，而不是 "未定义"。
  4. 检查网络选项卡，查看脚本加载是否失败
  5. 禁用广告拦截器并再次测试

解决方案：

  • 广告拦截器：切换到本地 JavaScript 实现（被阻止的可能性较小）
  • CSP 问题：在内容安全策略中添加奇异域
  • 脚本位置：确保 SDK 脚本位于<head> 标签中
  • 语法错误：验证 JavaScript 代码

内容安全策略配置

如果您的网站使用 CSP 标头，请添加这些指令：

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

最佳实践

产品 ID 管理

  • 每个网站或网络应用使用一个产品 ID
  • 在所有页面和子域中保持产品 ID 一致
  • 在团队知识库中记录产品 ID
  • 在开发、暂存和生产环境中使用单独的产品 ID

事件命名约定

良好的命名规范：

  • 使用清晰、描述性的名称：Purchase,Signup_Completed,Video_Play
  • 使用一致的大小写（建议使用大写标题）
  • 使用下划线代替空格
  • 将名称控制在 32 个字符以内
  • 避免使用特殊字符和表情符号

不好的例子：

  • Purchase!!!🎉 (特殊字符和表情符号）
  • user clicked the purchase button on the checkout page (太长，空格）
  • evt_123 (无描述性）

提示！创建一份事件命名文档，供营销、产品和工程团队共享，以保持一致性。

活动参数最佳实践

  • 收入：始终以数字形式发送，而不是字符串：revenue: 49.99 而不是revenue: "$49.99"
  • 货币：使用 3 个字母的 ISO 货币代码：USD,EUR,GBP
  • IDs：即使是数字，也要以字符串形式发送：product_id: "12345"
  • 参数名称：使用 snake_case 以保持一致
  • 值：字符串值保持在 100 个字符以内

测试策略

启动前，请按照此测试清单进行测试：

表格

测试 如何验证 预期结果
加载 SDK 控制台：typeof singularSdk 返回 "函数
已跟踪 Init/PageVisit 网络选项卡：过滤器"__PAGE_VISIT___" 页面加载时有 1 个请求，状态为 200
事件触发 触发事件，检查网络选项卡，验证有效负载中的事件名称（"n "参数）。 每个事件都有新请求，状态为 200
产品 ID 正确 检查请求有效载荷，验证有效载荷中的事件名称（"i "参数）。 反向 DNS 格式
无重复 快速触发同一事件 3 次 只发送 1 个请求
跟踪收入 检查购买事件有效载荷 收入显示为数字
多个页面 导航至不同页面 跟踪功能适用于所有页面
移动设备 在 iOS 和安卓浏览器上进行测试 跟踪功能在移动设备上正常运行

性能优化

  • 将 SDK 脚本放在<head> 标签中，以便尽早加载
  • 尽量减少每页跟踪的事件数量（重点关注有意义的操作和营销事件）
  • 避免对每个按键进行跟踪（使用去抖动功能）

隐私与合规

Cookie 披露

如果在配置中启用跨子域跟踪，Singular会设置一个第一方cookie。您必须在隐私政策中披露这一点。

建议使用的隐私政策语言

我们使用cookie跟踪用户行为，改善您的网站体验。具体来说，我们使用以下cookie：

singular_device_id- 此 cookie 会为访问我们网站的用户分配一个唯一的 ID。该 ID 可帮助我们在不收集个人信息的情况下跟踪用户访问期间的活动和互动。通过它，我们可以区分不同的用户，并监控不同会话中的访客行为。

  • 持续时间1 年
  • 类型：第一方 cookie第一方 cookie
  • 提供者：Singular ()Singular (https://www.singular.net/privacy-policy/)

遵守 GDPR 和隐私政策

遵守 GDPR：

  • 默认设置persistentIdentifier: false
  • 仅在用户同意后启用 cookie
  • 为用户提供退出跟踪的功能
  • 在您的 cookie 同意横幅中加入 Singular

调试工具和技术

浏览器开发工具

调试控制台命令

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

迁移清单

如果从其他分析平台迁移或升级您的实施：

  1. 审核当前实施
    • 记录当前跟踪的所有事件
    • 识别所有带有跟踪代码的页面
    • 注意任何自定义参数或用户 ID
  2. 规划新的实施
    • 将旧的事件名称映射到新的命名约定
    • 决定使用本地 JS还是GTM
    • 创建测试计划
  3. 分阶段实施
    • 从测试/暂存环境开始
    • 彻底测试（至少 1 周）
    • 在低流量期间部署到生产环境
    • 与旧系统并行运行 1-2 周
  4. 验证数据
    • 比较新旧系统的指标
    • 检查重复跟踪
    • 验证所有事件都正确启动
    • 监控 2-4 周
  5. 停用旧系统
    • 删除旧的跟踪代码
    • 更新文档
    • 对团队进行新系统培训

获取帮助

如果遇到本指南未涵盖的问题，请

  • 联系您的 Singular 客户成功经理。
  • 通过 Singular 面板提交支持单。
  • 包括浏览器控制台日志和网络请求截图。
  • 提供网站 URL 和复制任何问题的详细步骤。

相关文章