跳转到主要内容
本指南展示如何使用 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 设置面板中的将代码添加到网站步骤
您必须将 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 变量
现在您可以在 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
<!--
  OneSignal – 使用 Google Tag Manager 初始化 Web SDK

  此代码片段：
  - 加载 OneSignal Web SDK
  - 使用您的 App ID 初始化 OneSignal
  - 启用订阅铃铛 (notifyButton)

  适用于大多数网站。
-->

<!-- 1. 加载 OneSignal Web SDK (v16) -->
<!-- 此脚本必须在您希望 OneSignal 可用的每个页面上加载 -->
<script
  src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js"
  defer>
</script>

<script>
  // 确保 GTM dataLayer 存在
  // 此处仅用于可选地推送 "OneSignalInitialized" 事件
  window.dataLayer = window.dataLayer || [];

  // OneSignalDeferred 是一个队列，在 SDK 完全加载后运行
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  // 2. SDK 就绪后初始化 OneSignal
  window.OneSignalDeferred.push(function (OneSignal) {

    OneSignal.init({
      /*
        必填
        建议将 OneSignal App ID 设置为 GTM 变量。
        您可以在 OneSignal 控制面板中找到：
        Settings > Keys & IDs
      */
      appId: "{{ONESIGNAL_APP_ID}}",

      /*
        可选 – 仅在您的 SERVICE WORKER 不在根目录时需要

        如果您的 service worker 位于：
          /OneSignalSDKWorker.js

        …则不应设置 serviceWorkerPath 或 serviceWorkerParam。

        仅在您的 service worker 位于子目录中时取消注释并更新以下选项
        （例如：/push/onesignal/）。
      */

      //serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      //serviceWorkerParam: { scope: "/push/onesignal/" },

      /*
        可选
        启用 OneSignal 订阅铃铛 (notifyButton)，
        允许用户订阅或取消订阅通知。
        更多提示选项请参见：https://documentation.onesignal.com/docs/en/permission-requests
      */
      notifyButton: {
        enable: true
      }
    })
    .then(function () {
      // OneSignal 初始化成功
      console.log("[OneSignal] init success");

      // 推荐：推送事件到 GTM 以触发其他标签
      window.dataLayer.push({
        event: "OneSignalInitialized"
      });
    })
    .catch(function (e) {
      // 初始化失败（无效 App ID、缺少 service worker 等）
      console.log("[OneSignal] init failed", e);
    });
  });
</script>
在 Google Tag Manager 中配置 OneSignal - Init 标签
如果您使用同意横幅 / CMP，请参阅下面的 Consent Mode 和隐私注意事项选项。

​
4. 设置 External ID 和标签

设置 External ID 是可选的，但建议设置，因为它允许您跨设备识别用户并与您的后端同步。 将 ONESIGNAL_EXTERNAL_ID 推送到 dataLayer 此示例展示如何将用户 ID 推送到 dataLayer，以便 GTM 可以通过 ONESIGNAL_EXTERNAL_ID 变量（在步骤 2 中创建）读取它。
HTML
<script>
  window.dataLayer = window.dataLayer || [];

  // 从数据库或身份验证系统获取您的用户 ID。
  // 确保这是一个字符串值。
  var userId = "your_user_id_here";

  dataLayer.push({
    ONESIGNAL_EXTERNAL_ID: String(userId),
  });
</script>
创建 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 时序问题。
<script>
  // OneSignalDeferred 确保在 OneSignal SDK 就绪后运行
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  window.OneSignalDeferred.push(function (OneSignal) {
    /*
      从 Google Tag Manager 读取 External ID。
      这应该是一个 GTM 变量（Data Layer Variable 或 Custom JS Variable）。
    */
    var externalId = "{{ONESIGNAL_EXTERNAL_ID}}";

    console.log("[OneSignal] raw external ID from GTM:", externalId);

    /*
      基本验证：
      - GTM 可能将 undefined/null 替换为字符串
      - OneSignal.login 需要一个字符串
    */
    if (!externalId || externalId === "undefined" || externalId === "null") {
      console.log("[OneSignal] External ID missing, skipping login");
      return;
    }

    // 确保 External ID 是一个干净的字符串
    externalId = String(externalId).trim();

    console.log("[OneSignal] Calling OneSignal.login with External ID:", externalId);

    /*
      使用 External ID 将用户登录到 OneSignal。
      这将当前浏览器/设备链接到此用户。
    */
    OneSignal.login(externalId)
      .then(function () {
        console.log("[OneSignal] External ID set successfully:", externalId);
      })
      .catch(function (e) {
        console.log("[OneSignal] Failed to set External ID", e);
      });
  });
</script>

​
设置数据标签

此步骤使用 Web SDK 发送 OneSignal 用户标签。 标签配置：
  • 名称：OneSignal - Add Tags
  • Tag Type：Custom HTML
  • Tag firing options：Once per page
  • Trigger：
    • OneSignalInitialized，以及
    • 您的标签数据可用条件（例如：登录后、个人资料页面、购买后）。
粘贴此代码并替换示例标签 TAG 和 VALUE。
HTML
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(function (OneSignal) {
    OneSignal.User.addTags({
      TAG_1: "VALUE_1",
      TAG_2: "VALUE_2",
    });
  });
</script>
仅在有用户数据可用时发送标签（例如，登录后、加载个人资料后或已知转化事件后）。
如果您的网站使用 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 故障排除以获取常见修复方法。

​
后续步骤