前提条件
- 支持 HTTPS 的网站。
- 您可以在 GTM 中为网站的容器发布更改。
- 您已完成 OneSignal Web SDK 设置流程,直到将代码添加到网站步骤。这将为您提供:
- OneSignal Web Push 应用和 App ID。
- OneSignal Service Worker 设置。
设置
1. 设置您的 OneSignal Web 应用
按照 Web SDK 设置直到将代码添加到网站步骤。这是您获取 OneSignal App ID 的地方。
2. 创建 GTM 变量
为您在标签中引用的值创建 GTM 变量。这可以避免硬编码,并使您的设置更易于维护。 创建ONESIGNAL_APP_ID 变量
- 在 GTM 中,转到 Variables > New。
- 选择 Constant。
- 将其命名为
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

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 等待