前提条件
- 支持 HTTPS 的网站。
- 您可以在 GTM 中为网站的容器发布更改。
- 您已完成 OneSignal Web SDK 设置流程,直到将代码添加到网站步骤。这将为您提供:
- OneSignal Web Push 应用和 App ID。
- OneSignal Service Worker 设置。
设置
1. 设置您的 OneSignal Web 应用
按照 Web SDK 设置直到将代码添加到网站步骤。这是您获取 OneSignal App ID 的地方。
到达此步骤后,您需要对代码进行一些调整以便与 Google Tag Manager 配合使用。
2. 创建 GTM 变量
为您在标签中引用的值创建 GTM 变量。这可以避免硬编码,并使您的设置更易于维护。 创建ONESIGNAL_APP_ID 变量
- 在 GTM 中,转到 Variables > New。
- 选择 Constant。
- 将其命名为
ONESIGNAL_APP_ID - 将值设置为您的 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 标签
- 在 GTM 中,转到 Tags > New
- 为标签命名:
OneSignal - Init - Tag Type:Custom HTML
- 粘贴以下代码。
- 在 Advanced Settings > Tag firing options 下,设置 Once per page。
- 在 Triggering 下,选择 Initialization - All Pages。
HTML

配置 OneSignal - Init 标签
4. 设置 External ID 和标签
设置 External ID 是可选的,但建议设置,因为它允许您跨设备识别用户并与您的后端同步。 将ONESIGNAL_EXTERNAL_ID 推送到 dataLayer
此示例展示如何将用户 ID 推送到 dataLayer,以便 GTM 可以通过 ONESIGNAL_EXTERNAL_ID 变量(在步骤 2 中创建)读取它。
HTML
- 标签名称:
OneSignal – Set External ID - 标签类型:Custom HTML
- Tag firing options:Once per page
- Trigger:
- 创建
OneSignalInitialized的自定义事件触发器(在上面的 OneSignal - Init 标签中设置),并且 - 可选地,如果您知道用户 ID 在页面加载时可用。
- 创建
设置标签
此步骤使用 Web SDK 发送 OneSignal 标签。 标签配置:- 名称:
OneSignal - Add Tags - Tag Type:Custom HTML
- Tag firing options:Once per page
- Trigger:
OneSignalInitialized,以及- 您的标签数据可用条件(例如:登录后、个人资料页面、购买后)。
HTML
仅在有用户数据可用时发送标签(例如,登录后、加载个人资料后或已知转化事件后)。
Consent Mode 和隐私注意事项
如果您的网站使用 Consent Mode / CMP,请决定 OneSignal 应何时加载:- 仅在同意后(欧盟/英国常见),或
- 立即(在默认允许”功能性”存储的地方常见)。
测试
- 在 GTM 中,打开 Preview 模式。
- 加载您的网站并确认:
OneSignal - Init触发一次。OneSignalInitialized出现在 GTM 事件时间线中(如果您保留了事件推送)。
- 订阅您的网站。有关提示详细信息,请参阅网页权限提示。
- 在 OneSignal 控制面板中,转到 Audience > Subscriptions 并确认:
- 选择加入后出现订阅。
- 如果设置了 External ID,则可见 External ID。
- 从 Messages > New Push 发送测试推送。
如果初始化正常工作,您将看到选择加入后 OneSignal 中出现订阅。
故障排除
-
Init 标签触发,但 SDK 从未加载
- 检查是否有 Content Security Policy (CSP) 阻止
https://cdn.onesignal.com。 - 检查广告拦截器/脚本拦截器。
- 检查是否有 Content Security Policy (CSP) 阻止
-
dataLayer错误- 确保在任何
dataLayer.push()调用之前设置window.dataLayer = window.dataLayer || []。
- 确保在任何
-
重复提示 / 重复 SDK 加载
- 确保您没有通过网站代码、CMS 插件或另一个 GTM 标签加载 OneSignal。
-
Add Tags 运行但未出现在 OneSignal 中
- 确认 Trigger Group 等待
OneSignalInitialized。 - 确认您的用户操作触发器实际触发。
- 确认标签是有效的键/值对,并在计划限制内。
- 确认 Trigger Group 等待