概述

本指南说明如何通过Google Tag Manager（GTM）实现Singular Web SDK的集成。此方法适用于无法直接访问网站代码的团队，或希望通过GTM管理跟踪的团队。

前提条件

开始前请确保您拥有：

• SDK密钥与SDK密钥： 
  • 获取路径：登录Singular账户，依次进入开发者工具 > SDK集成 > SDK密钥。
• 产品ID：
  • 定义：网站的唯一标识名，建议采用反向DNS格式（例如：com.website-name ）。
  • 重要性说明：该ID将网站关联为Singular中的应用程序，必须与您在Singular应用页面中列出的Web应用程序bundleID完全一致。 
• 您的网站已配置Google Tag Manager。
• 需具备GTM中编辑网站标签、触发器及变量的权限。根据定制需求，可能需要掌握创建自定义标签及配置标签序列的方法。 
• 若您无权限发布Google Tag Manager变更，需在测试后请他人代为发布。
• 掌握在GTM中预览和调试容器及标签的方法。 
• 需列出待追踪事件清单。可参考我们的《Singular标准事件：完整列表》及《垂直领域推荐事件》获取灵感。

实施步骤

步骤1：将Singular网络追踪模板添加至GTM容器

1. 登录您的Google Tag Manager账户并选择网站容器。
2. 前往标签>新建。
3. 为标签命名："Singular初始化标签"
4. 点击标签配置框开始设置
5. 选择标签类型：点击"在社区模板库中探索更多标签类型"。
6. 搜索"Singular"并选择"Singular Web Tracking"。点击"添加到工作区"按钮。

步骤 2：初始化 SDK

1. 填写表单字段如下：
   • 将跟踪类型设为初始化
   • 在Api Key字段输入实际SDK密钥
   • 在密钥字段输入实际SDK密钥 字段

   • 输入实际产品ID。格式应为：com.website-name ，且需与Singular平台"应用程序"页面中的BundleID值一致。

     提示！测试时请使用专用产品ID com.website-name.dev ， 正式发布前请更新该ID。 此举可确保测试数据与生产环境数据 在Singular报告中完全分离。

   • 可选：
     • 日志级别：配置SDK 调试 日志输出至控制台。默认值为无。
     • 事件去重
     • 设置全局属性
     • 启用智能横幅（仅限企业版）
     • 设置客户用户ID
     • 会话超时： 用户处于 非活动状态多长时间后 SDK将创建新会话。Singular 发送用户会话数据以计算用户留存率并启用 再互动归因。默认值为30分钟。
     • 跨子域名追踪
2. 选择"触发器"配置触发条件以使该 标签 生效。
3. 选择新建并命名触发器："Singular 初始化触发器"。
4. 点击触发器配置，选择"页面查看 - 窗口加载" 并点击"保存"。
5. 再次点击"保存"以保存标签。
6. 在标签页面点击"预览"，测试 Singular 初始化标签是否被触发。
   
   

步骤3：事件追踪

初始化 SDK 后，当用户在网站执行重要操作时即可追踪自定义事件。

Basic EventConversion EventRevenue Event

基础事件追踪

通过有效JSON格式追踪基础事件或添加自定义属性， 为事件提供更多上下文信息：

1. 使用Singular Web Tracking模板创建自定义事件标签。

2. 命名事件标签。

3. 选择跟踪类型 = 自定义事件

4. 调整"事件名称"字段或设置相应变量。

5. 调整"自定义用户ID"字段或设置相应变量。

6. 根据需要调整"属性"以在事件中传递键值对。

7. 配置触发器，确保标签仅在预期条件下触发。

8. 保存触发器和标签，并在预览中测试。

转化事件追踪

跟踪转化事件：

1. 使用Singular Web Tracking模板创建自定义事件标签。 为转化事件标签命名。

2. 命名转化事件标签。

3. 选择跟踪类型 = 转化事件

4. 调整"事件名称"字段或设置相应变量。

5. 调整"自定义用户ID"字段或设置相应变量。

6. 根据需要调整"属性"以在事件中传递键值对。

7. 配置触发器，确保标签仅在预期条件下触发。

8. 保存触发器和标签，并在预览中测试。

收入事件追踪

通过收入信息追踪转化事件，并可添加可选属性获取更多上下文：

1. 使用Singular Web Tracking模板创建自定义事件标签。 为收入事件标签命名。

2. 为收入事件标签命名。

3. 选择跟踪类型 = 收入事件

4. 调整"事件名称"字段或设置相应变量。

5. 调整"自定义用户ID"字段或设置相应变量。

6. 调整"货币"字段或设置相应变量。 请以ISO 4217三字母货币代码传递收入货币， 例如"USD"、"EUR"或"INR"。

7. 调整"收入"字段或设置相应变量。 收入必须以声明的货币单位表示。

8. 如需传递事件的键值对，可调整"属性"字段。

9. 配置触发器，确保标签仅在预期条件下触发。

10. 保存触发器和标签，并在预览中测试。

常见事件实现模式

步骤4：设置客户用户ID

您可通过Singular SDK方法向Singular发送内部用户ID。

当用户未登录状态下在网站执行操作时， 事件将通过Singular生成的用户ID发送至平台。 但用户注册或登录后， 可将网站使用的用户ID（如哈希化邮箱地址） 与事件同步发送至Singular。

在用户级数据导出（参见《导出归因日志》） 以及内部BI回传（若已配置，参见《配置内部BI回传》）中， Singular均会使用该用户ID。

向Singular发送用户ID有两种方式：

• 推荐方案：若 网站加载时已知用户ID， 请在初始化SDK时 于初始化跟踪类型中设置用户ID。 此举可确保用户ID自首次页面访问起 即对Singular可用。
• 替代方案：您可在任何时间点（通常在身份验证完成后）触发追踪类型为 "登录"的标签。建议在用户ID可用时立即调用该标签。 注意：调用此标签不会触发事件， 仅将用户ID设置为后续所有事件触发器的附加参数！

若需通过Singular设置用户ID，请添加"登录"追踪类型的Singular标签：

1. 在您的 Google 标签管理器账户中，点击标签 > 新建。
2. 在标签配置窗口中，点击 标签配置，并在标签类型 菜单中选择"Singular Web Tracking"。
3. 在追踪类型下选择"登录"。
4. 在自定义用户ID下，输入包含用户ID的Google Tag Manager变量。
5. 点击触发器并添加触发事件：用户 登录 或注册。
6. 点击保存。

若需清除用户ID，请添加具有 "注销"跟踪类型的标签：

1. 在您的 Google 标签管理器账户中，点击标签 > 新建。
2. 在标签配置窗口中，点击 标签配置，并在标签类型 菜单中选择"单一网页跟踪"。
3. 在跟踪类型下选择"注销"。
4. 点击触发器并添加触发事件：用户 注销。
5. 点击保存。

步骤5：事件去重（可选）

Google Tag Manager中的事件去重

GTM 中出现重复数据的原因

GTM可能针对同一用户操作多次评估并触发标签（例如重复触发条件或多个事件监听器），导致Singular事件导出出现重复。

GTM去重方法（推荐）

Singular SDK事件去重：在Singular Web SDK的GTM模板中启用去重功能，可移除在可配置时间窗口内匹配相同去重参数的重复事件。

实施步骤

启用事件去重：在 Singular Web SDK 初始化标签/模板中启用事件去重选项。

设置时间窗口（可选）：配置判定两个事件为重复的最大时间窗口（以毫秒为单位，默认：1000毫秒/1秒）。

去重机制原理

启用后，当相同事件在时间窗口内再次发生时，SDK将抑制该事件（页面访问除外）。抑制依据为以下参数的哈希值：EventName 、EventProductName 、IsRevenueEvent 、CustomUserId 、GlobalProperties 、MatchId 、WebUrl（以及事件"额外"负载，如收入和自定义参数）。

步骤 6：测试 GTM 实施效果

1. 开启GTM预览模式并加载您的网站。
2. 检查以下事项：

• SDK 是否加载成功（网络请求至singular-sdk.js ）
• 事件触发符合预期且每项操作仅触发一次
• 浏览器控制台无与singular相关的错误
• 网络请求是否发送至sdk-api-v1.singular.net

3. 使用浏览器开发者工具的"网络"选项卡验证 是否发送了正确的有效负载

步骤7：实现网页到应用的归因转发

网页到应用归因转发

使用Singular Web SDK追踪用户从网站到移动应用的旅程， 实现精准的网页广告活动归因至移动应用安装及 用户回访。 请按以下步骤配置网页到应用转发功能（含桌面端用户 二维码支持方案）。

1. 请参照 《网站到移动应用归因转发指南》 配置 Singular Web SDK 以实现移动网页归因。
2. 移动端网页到应用追踪操作：
   • 添加"打开应用"标签，并将触发器设置为 按钮点击事件，用于打开或安装应用。

     1. 配置"打开应用"标签时， 请在Singular管理链接页面 指定您的移动网页到应用基础链接。

        

3. 针对桌面端网页到应用的跟踪：
   • 创建二维码生成器清理标签
     1. 在GTM中导航至标签 > 新建， 选择 自定义HTML。
     2. 在代码区域添加：
        • 注入您选择的二维码库
        • 从以下链接获取网页到应用程序链接： window.singularSdk.buildWebToAppLink(baselink);
        • 根据返回的链接生成二维码。
        • 更新页面上的二维码图像。
     3. 标签命名："单一 - QR码生成器 (清理版)"
     4. 无需触发器：清理标签继承 主标签的触发器
     5. 配置您的Singular初始化标签：
        • 点击标签配置
        • 前往高级设置 > 标签序列
        • 勾选"在[Singular初始化标签]触发后执行清理标签"
        • 从下拉菜单中选择您的二维码生成器标签
        • 保存标签，并在预览模式下测试。

进阶主题

Singular横幅广告

添加全局属性

Track Type: setGlobalProperties
propertyKey: user_type
value: premium

Track Type: getGlobalProperties

Track Type: unsetGlobalProperty
propertyKey: user_type

Track Type: clearGlobalProperties

跨子域跟踪

默认情况下，Singular网站SDK会生成Singular设备ID并通过浏览器存储进行持久化。由于该存储无法在子域名间共享，SDK最终会为每个子域名生成新ID。

若需跨子域持久化 Singular 设备 ID，可采用以下任一方案：

常见GTM实施问题

最佳实践

• 保持GTM有序：为标签和触发器命名时清晰标注其用途并记录说明。
• 定期审核闲置或遗留标签。
• 尽量减少触发器数量以降低事件重复风险。
• 变更后务必在GTM预览模式下全面测试， 再推送至生产环境。
• 若使用基于Cookie的跟踪（跨子域跟踪）， 请相应更新 隐私政策。

相关文章

• 原生JavaScript实现指南
• Google Tag Manager 实施指南
• 故障排除与最佳实践
• 网络归因常见问题解答