Skip to main content
本指南展示如何使用 Google Tag Manager (GTM) 加载和初始化 OneSignal Web SDK,然后在初始化后可选地设置 External ID 和 OneSignal 标签。

前提条件

  • 支持 HTTPS 的网站。
  • 您可以在 GTM 中为网站的容器发布更改。
  • 您已完成 OneSignal Web SDK 设置流程,直到将代码添加到网站步骤。这将为您提供:

设置

1. 设置您的 OneSignal Web 应用

按照 Web SDK 设置直到将代码添加到网站步骤。这是您获取 OneSignal App ID 的地方。
OneSignal Web SDK 设置面板中的将代码添加到网站步骤

到达此步骤后,您需要对代码进行一些调整以便与 Google Tag Manager 配合使用。

您必须将 OneSignal Service Worker 文件直接上传到您的服务器。请参见 OneSignal Service Worker

2. 创建 GTM 变量

为您在标签中引用的值创建 GTM 变量。这可以避免硬编码,并使您的设置更易于维护。 创建 ONESIGNAL_APP_ID 变量
  1. 在 GTM 中,转到 Variables > New
  2. 选择 Constant
  3. 将其命名为 ONESIGNAL_APP_ID
  4. 将值设置为您的 OneSignal App ID。
  5. 保存
在 Google Tag Manager 中创建 OneSignal App ID 变量

创建 OneSignal App ID 变量

现在您可以在 GTM 的任何地方使用 {{ ONESIGNAL_APP_ID }} 引用您的 App ID。
创建 ONESIGNAL_EXTERNAL_ID 变量(推荐) 如果您使用外部标识符关联用户(例如,来自数据库或身份验证系统的用户 ID),请使用此变量。 根据值在您网站上的可用方式选择变量类型。常用选项:
  • Data Layer Variable(推荐)
  • First-Party Cookie
  • DOM Variable(高级)

3. 创建 OneSignal init 标签

  1. 在 GTM 中,转到 Tags > New
  2. 为标签命名:OneSignal - Init
  3. Tag Type:Custom HTML
  4. 粘贴以下代码。
  5. Advanced Settings > Tag firing options 下,设置 Once per page
  6. Triggering 下,选择 Initialization - All Pages
HTML
在 Google Tag Manager 中配置 OneSignal - Init 标签

配置 OneSignal - Init 标签

如果您使用同意横幅 / CMP,请参阅下面的 Consent Mode 和隐私注意事项选项。

4. 设置 External ID 和标签

设置 External ID 是可选的,但建议设置,因为它允许您跨设备识别用户并与您的后端同步。 ONESIGNAL_EXTERNAL_ID 推送到 dataLayer 此示例展示如何将用户 ID 推送到 dataLayer,以便 GTM 可以通过 ONESIGNAL_EXTERNAL_ID 变量(在步骤 2 中创建)读取它。
HTML
创建 GTM 标签以设置 External ID 标签配置:
  • 标签名称:OneSignal – Set External ID
  • 标签类型:Custom HTML
  • Tag firing options:Once per page
  • Trigger:
    • 创建 OneSignalInitialized 的自定义事件触发器(在上面的 OneSignal - Init 标签中设置),并且
    • 可选地,如果您知道用户 ID 在页面加载时可用。
设置 External ID 的必需方法是 OneSignal.login(externalId),其中 externalId 是一个字符串。如果 {{ONESIGNAL_EXTERNAL_ID}} 为空(或 GTM 替换为 “undefined” / “null”),login 调用将被跳过,External ID 将不会被设置。这是一个常见的 GTM 时序问题。

设置标签

此步骤使用 Web SDK 发送 OneSignal 标签 标签配置:
  • 名称:OneSignal - Add Tags
  • Tag Type:Custom HTML
  • Tag firing options:Once per page
  • Trigger:
    • OneSignalInitialized,以及
    • 您的标签数据可用条件(例如:登录后、个人资料页面、购买后)。
粘贴此代码并替换示例标签 TAG 和 VALUE。
HTML
仅在有用户数据可用时发送标签(例如,登录后、加载个人资料后或已知转化事件后)。
如果您的网站使用 Consent Mode / CMP,请决定 OneSignal 应何时加载:
  • 仅在同意后(欧盟/英国常见),或
  • 立即(在默认允许”功能性”存储的地方常见)。
GTM 支持 Consent Initialization 触发器和标签级同意控制,以根据用户同意管理标签行为。但是,OneSignal 也提供隐私同意方法来控制 SDK 何时加载。

测试

  1. 在 GTM 中,打开 Preview 模式。
  2. 加载您的网站并确认:
    • OneSignal - Init 触发一次。
    • OneSignalInitialized 出现在 GTM 事件时间线中(如果您保留了事件推送)。
  3. 订阅您的网站。有关提示详细信息,请参阅网页权限提示
  4. 在 OneSignal 控制面板中,转到 Audience > Subscriptions 并确认:
    • 选择加入后出现订阅。
    • 如果设置了 External ID,则可见 External ID。
  5. Messages > New Push 发送测试推送。
如果初始化正常工作,您将看到选择加入后 OneSignal 中出现订阅。

故障排除

  • Init 标签触发,但 SDK 从未加载
    • 检查是否有 Content Security Policy (CSP) 阻止 https://cdn.onesignal.com
    • 检查广告拦截器/脚本拦截器。
  • dataLayer 错误
    • 确保在任何 dataLayer.push() 调用之前设置 window.dataLayer = window.dataLayer || []
  • 重复提示 / 重复 SDK 加载
    • 确保您没有通过网站代码、CMS 插件或另一个 GTM 标签加载 OneSignal。
  • Add Tags 运行但未出现在 OneSignal 中
    • 确认 Trigger Group 等待 OneSignalInitialized
    • 确认您的用户操作触发器实际触发。
    • 确认标签是有效的键/值对,并在计划限制内。
如果您仍需要帮助,请参阅 Web SDK 故障排除以获取常见修复方法。

后续步骤