Web SDK 设置 - OneSignal

概述

本指南将带您完成向网站添加 OneSignal 网页推送通知的全流程——从仪表板配置到 SDK 安装。OneSignal 支持 Chrome、Firefox、Edge、Safari 以及其他主流浏览器。

要求

HTTPS 网站：网页推送在 HTTP 或隐身/私人模式下不起作用。
服务器访问权限：您需要将 service worker 文件上传到您的站点。
单一源：网页推送遵循同源策略。如果您有多个源（域名/子域名），您需要多个 OneSignal 应用（每个源一个）。要符合此浏览器限制，您可以：
- 将流量重定向到单一源进行订阅。
- 创建多个 OneSignal 应用——每个源一个。

如果您的团队已经创建了 OneSignal 账户，请申请成为管理员以便您可以设置应用。否则，请在 onesignal.com 注册免费账户开始使用！

配置您的 OneSignal 应用和平台

在 OneSignal 仪表板中：

转到 设置 > 推送和应用内 > Web。

选择集成类型：

典型站点（推荐）

无需额外编码，直接通过 OneSignal 仪表板管理提示和设置。

WordPress

使用 WordPress 和我们的官方插件时必需。

自定义代码

为需要对提示和 SDK 配置进行全面控制的开发人员提供。

站点设置

添加站点详情：

站点名称：您站点的名称和默认通知标题。
站点 URL：您站点的 URL。有关更多详情，请参阅站点 URL。
自动重新订阅：启用此功能可在用户清除浏览器数据后返回您的站点时自动重新订阅（无需新的权限提示）
默认图标 URL：上传一个 256x256 像素的正方形 PNG 或 JPG 图片，该图片将出现在通知和提示中。如果未设置，我们将使用铃铛作为默认图标。

站点 URL

输入您站点的确切源，例如 https://yourdomain.com。如果您的站点没有配置为这样，请避免使用 www.。如果您有多个源：

重定向到单个源。
或者为每个源设置一个 OneSignal 应用。

本地测试

我们的 Web SDK 可以在 localhost 环境中测试。如果您在 localhost 上进行测试，我们建议设置一个与您的生产应用不同的 OneSignal 应用。

Localhost 配置

将 站点 URL 设置为与您的 localhost 环境 URL 完全匹配。它必须是一个常见的 localhost URL，示例：

http://localhost
https://localhost:3000
http://127.0.0.1
https://127.0.0.1:5000

如果您的 localhost 使用 HTTP，请选择 将 HTTP localhost 视为 HTTPS 进行测试。Google Chrome 将 http://localhost 和 http://127.0.0.1 视为安全源，即使在 HTTP 上也允许 HTTPS 集成。这就是为什么您无法在 HTTPS localhost 上测试其他非标准源的原因。

OneSignal localhost 配置，显示将 HTTP localhost 视为 HTTPS 选项

将 `allowLocalhostAsSecureOrigin` 添加到您的 OneSignal `init` 选项

在您的 localhost 站点上初始化 OneSignal 时，请在 OneSignal init 选项中添加 allowLocalhostAsSecureOrigin: true,。此外，如果您在 HTTPS 上使用自签名证书测试 localhost，您可能需要要求 Chrome 忽略无效证书进行测试： --allow-insecure-localhost。Firefox 和 Safari 提供内置机制来添加安全证书的异常。

  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "YOUR_OS_APP_ID",
        allowLocalhostAsSecureOrigin: true,
      });
    });
  </script>

权限提示

典型站点设置允许您或您的团队成员随时通过 OneSignal 仪表板添加、删除和更新权限提示。

网页权限提示

配置浏览器权限对话框向您的用户显示的时间和方式。

欢迎通知（可选）

您还可以设置欢迎通知，在用户订阅推送通知时发送给他们。

高级设置

在 OneSignal 仪表板中可配置的其他功能。

Webhooks

我们的 Web SDK 提供了将特定的网页推送事件 POST 到您选择的 URL 的能力。网页推送 Webhook 是与 Event Webhook 独立的实现，不能混用。

网页推送 Webhook

通过 POST 请求将网页推送事件发送到您的服务器。

Service workers

在网页推送配置的下一页中，将为您提供 OneSignalSDKWorker.js service worker 文件。我们的 Web SDK 默认在您站点的根目录中查找此文件。如果您想要更改我们的 service worker 文件位置、名称和/或范围，您可以在这里更新这些设置。

Service worker 文件路径 是您将放置这些文件的目录路径。
主要和更新程序 service worker 文件名 可以只是 OneSignalSDKWorker.js 或者如果您想要重命名此文件。必须使用 .js 文件扩展名。
Service worker 注册范围 是此文件可以在其上工作的页面。对于推送通知，这并不重要，最初设计用于您想要向 service worker 文件添加更多功能的情况。您应该将其设置为与您的位置相同的路径。

使用此示例，您应该能够在 https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js 看到该文件的代码可公开访问。

OneSignal Service Worker

高级 service worker 配置、自定义集成以及从其他提供商迁移。

Click behavior

控制用户在点击通知时如何导航到您设置的 URL。如果用户没有在任何选项卡中打开您的站点，浏览器会打开新选项卡并导航到通知 URL。如果用户已经打开了您的站点，行为取决于您选择的设置：

设置	匹配	操作
Exact Navigate（默认）	精确 URL（如 `example.com/product`）	在匹配的标签页中导航到通知 URL
Origin Navigate	源（如 `example.com`）	在匹配的标签页中导航到通知 URL
Exact Focus	精确 URL	聚焦匹配的标签页，不刷新
Origin Focus	源	聚焦匹配的标签页，不刷新

Persistence

默认的网页推送行为是它们在设备上弹出大约 5 秒钟，然后被移动到通知中心，在被操作系统删除之前保存大约 1 周。某些设备和版本的 Chrome 和 Edge 允许您在屏幕上更久地持续通知。这意味着通知将保留在屏幕上，直到用户与其交互。这可能会烦扰您的用户，不推荐使用。 此外，如果您启用持久性，它将通过减少字符数量来影响通知对订阅者的显示方式，并可能影响图片和按钮的显示方式。在更改它们时，它们只对访问具有更新设置的站点的订阅者生效。如果您没有看到这些选项的更改，您将需要等待。

Safari certificate (Optional)

OneSignal 自动提供与 Safari 浏览器配合使用的必要证书，无需额外费用。如果您已经拥有自己的 Safari Web 推送证书，请打开此选项以上传您的 Safari Web .p12 推送证书 和密码。

上传 service worker 文件

将 OneSignalSDKWorker.js service worker 文件添加到您的站点。从 OneSignal 仪表板下载，或从 GitHub 下载。

将此文件放置在站点的根目录或子目录中均可。如果放在子目录中，您需要在高级设置 > Service workers 部分设置 Service worker 文件路径。文件上传到您的服务器后，检查以下内容以确保其正常工作：

验证位置

确保文件位于与高级设置 > Service worker 中设置的相同的 Service worker 文件路径 中。如果您没有更新这些设置，那么您应该将文件放在根目录中。例如：

https://yourdomain.com/OneSignalSDKWorker.js
https://yourdomain.com/some-subdirectory/OneSignalSDKWorker.js

它必须在您的源上可公开访问

OneSignalSDKWorker.js 文件必须在您的源上可公开访问和可用。它不能通过 CDN 托管或放置在不同的源上进行重定向。当您访问文件的 URL 时，您应该看到代码。

它必须使用 content-type: application/javascript 提供服务

这是一个 javascript 文件，需要作为这样提供服务。它不能有 text/html 的 content-type。

OneSignal Service Worker

高级配置以及从其他网页推送提供商迁移。

将代码添加到您的网站

以下 JavaScript SDK 代码适用于任何站点。如果您的站点是使用 Angular、React JS 或 Vue JS 构建的，请点击相应链接。要使用我们的 JavaScript SDK 在您的站点上初始化 OneSignal，请将提供的代码复制/粘贴到您网站的 <head> 标签中。我们的仪表板将提供以下代码，但包含您的 OneSignal 应用 ID。

  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(async function(OneSignal) {
      await OneSignal.init({
        appId: "YOUR_ONESIGNAL_APP_ID",
      });
    });
  </script>

iOS web push support

Apple 开始在运行 iOS 16.4+ 的 iPhone 和 iPad 上支持网页推送通知。不像 Android 设备只要在支持的浏览器上访问就能”正常工作”，Apple 添加了更多要求，例如 manifest.json 文件和用户操作以将您的站点添加到他们的主屏幕。

iOS Web Push Setup

添加必需的 manifest.json 文件并指导用户将您的站点添加到他们的主屏幕。

测试 OneSignal SDK 集成

本指南帮助您验证 OneSignal SDK 集成是否正常工作，通过测试推送通知和订阅注册。

检查网页推送订阅

在测试设备上启动您的网站。

测试时使用 Chrome、Firefox、Edge 或 Safari。
请勿使用无痕或隐私浏览模式。 用户无法在这些模式下订阅推送通知。
提示应根据您的权限提示配置出现。
在原生提示上点击允许以订阅推送通知。

检查您的 OneSignal 控制台

前往受众 > 订阅。
您应该看到状态为已订阅的新条目。

您已成功创建了网页推送订阅。当用户首次订阅您网站的推送通知时，将创建网页推送订阅。

设置测试订阅

测试订阅有助于在发送消息前测试推送通知。

添加到测试订阅。

在控制台中，在订阅旁边，点击选项（三个点）按钮并选择添加到测试订阅。

命名您的订阅。

命名订阅，以便您后续在测试订阅选项卡中轻松识别您的设备。

创建测试用户细分。

前往受众 > 细分 > 新建细分。

命名细分。

将细分命名为 Test Users（名称很重要，因为后续会用到）。

添加测试用户过滤器并点击创建细分。

您已成功创建了测试用户细分。现在我们可以测试向这个单独设备和测试用户组发送消息。

通过 API 发送测试推送

获取您的应用 API 密钥和应用 ID。

在您的 OneSignal 控制台中，前往设置 > 密钥和 ID。

更新提供的代码。

在下面的代码中将 YOUR_APP_API_KEY 和 YOUR_APP_ID 替换为您的实际密钥。这段代码使用了我们之前创建的 Test Users 细分。

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

运行代码。

在您的终端中运行代码。

检查图片和确认投递。

如果所有设置步骤都成功完成，测试订阅应该会收到通知。

仅 Chrome 支持图片。图片在收缩的通知视图中显示很小。展开通知以查看完整图片。

检查确认投递。

在您的控制台中，前往投递 > 已发送消息，然后点击消息查看统计数据。您应该看到已确认统计数据，表示设备收到了推送。

Safari 不支持确认投递。

推送通知消息报告

查看推送通知的投递、点击和转化统计数据。

您已成功通过 API 向细分发送了通知。

如果通知未到达，请联系 support@onesignal.com 并提供以下信息：

API 请求和响应（复制粘贴到 .txt 文件中）
您的订阅 ID
包含 OneSignal 代码的网站 URL

用户识别

上一节介绍了如何创建网页推送订阅。本节将扩展到使用 OneSignal SDK 识别跨所有订阅（包括推送、电子邮件和短信）的用户。涵盖外部 ID、标签、多渠道订阅、隐私和事件追踪，帮助您统一并跨平台互动用户。

分配外部 ID

使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码中一致地识别用户。这确保您的消息在渠道和第三方系统中保持统一（对集成尤其重要）。使用 SDK 的login 方法在您的应用每次识别用户时设置外部 ID。

OneSignal 为订阅（订阅 ID）和用户（OneSignal ID）生成唯一的只读 ID。当用户在不同设备上下载您的应用、订阅您的网站和/或在应用外提供电子邮件地址和电话号码时，将创建新的订阅。强烈建议通过 SDK 设置外部 ID，以在用户的所有订阅中识别用户，无论订阅是如何创建的。

添加数据标签

标签是字符串数据的键值对，您可以使用它们存储用户属性（如 username、role 或偏好设置）和事件（如 purchase_date、game_level 或用户交互）。标签为高级消息个性化和细分提供支持，允许更高级的使用场景。当应用中发生事件时，使用 SDK 的addTag 和 addTags 方法设置标签。在这个例子中，用户达到了 6 级，可通过名为 current_level 的标签识别，值设置为 6。

我们可以创建一个等级在 5 到 10 之间的用户细分，然后使用它来发送针对性和个性化的消息：

添加电子邮件和/或短信订阅

OneSignal SDK 在用户选择加入时自动创建网页推送订阅。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。

使用addEmail 方法创建电子邮件订阅。
使用addSms 方法创建短信订阅。

如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 将将其添加到现有用户，不会创建重复。您可以通过控制台中的受众 > 用户或View user API查看统一用户。

多渠道沟通的最佳实践

在添加电子邮件或短信订阅之前获得明确同意。
向用户解释每个沟通渠道的好处。
提供渠道偏好设置，以便用户可以选择他们喜欢的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意门控方法：

setConsentRequired(true)：在给予同意之前阻止数据收集。
setConsentGiven(true)：一旦获得同意就允许数据收集。

有关隐私和安全的更多信息：

SDK 收集的数据

了解 OneSignal SDK 从用户收集的数据。

处理个人数据

依据隐私法规管理和保护用户数据。

监听推送、用户和应用内事件

使用 SDK 监听器对用户操作和状态变化做出反应。 SDK 为您提供了多个事件监听器可以钩入。查看我们的SDK 参考指南了解更多详情。

推送通知事件

点击事件监听器：检测通知何时被点击。
前台生命周期监听器：控制通知在前台的行为。

用户状态变化

用户状态变化事件监听器：检测外部 ID 何时被设置。
权限观察器：追踪用户与原生推送权限提示的特定交互。
推送订阅变化观察器：追踪推送订阅状态何时变化。

高级设置和功能

探索更多功能以增强您的集成：

迁移到 OneSignal

从其他推送服务迁移到 OneSignal。

集成

将 OneSignal 与第三方工具和平台连接。

操作按钮

为推送通知添加互动按钮。

多语言消息

以用户首选语言发送本地化消息。

身份验证

使用服务器端身份验证保护您的 SDK 集成。

自定义结果

追踪与消息关联的自定义转化事件。

Web SDK 设置和参考

网页推送设置

为您的集成启用所有关键网页推送功能。

Web SDK 参考

可用方法和配置选项的完整详情。

恭喜！您已成功完成 Web SDK 设置指南。

FAQ

网页推送在 HTTP 站点上有效吗？

不行。网页推送需要 HTTPS。浏览器将此作为安全要求强制执行。唯一的例外是 localhost 和 127.0.0.1，浏览器出于开发目的将其视为安全源。

为什么我需要 service worker 文件？

Service worker 在后台运行，即使用户没有打开您的站点也能处理传入的推送通知。没有它，浏览器就无法显示通知。OneSignalSDKWorker.js 文件必须在您的源上可公开访问。

我可以在 iOS（iPhone/iPad）上使用网页推送吗？

可以，从 iOS 16.4+ 开始支持。但是，Apple 需要一个 manifest.json 文件，并且用户必须先将您的站点添加到他们的主屏幕。有关完整要求，请参阅 iOS 网页推送设置。

为什么我的通知没有显示？

常见原因包括 service worker 文件放置位置不正确、仪表板中站点 URL 不匹配，或用户在其浏览器设置中屏蔽了通知。有关完整的故障排除清单，请参阅通知显示成功但未显示。

需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：

您遇到的问题详情以及复现步骤（如有）
您的 OneSignal 应用 ID
外部 ID 或订阅 ID（如适用）
您在 OneSignal 控制台中测试的消息 URL（如适用）
任何相关的日志或错误信息

我们很乐意为您提供帮助！

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

​概述

​要求

​配置您的 OneSignal 应用和平台

典型站点（推荐）

WordPress

自定义代码

​站点设置

​站点 URL

​本地测试

​将 allowLocalhostAsSecureOrigin 添加到您的 OneSignal init 选项

​权限提示

网页权限提示

​欢迎通知（可选）

​高级设置

​Webhooks

网页推送 Webhook

​Service workers

OneSignal Service Worker

​Click behavior

​Persistence

​Safari certificate (Optional)

​上传 service worker 文件

OneSignal Service Worker

​将代码添加到您的网站

​iOS web push support

iOS Web Push Setup

​测试 OneSignal SDK 集成

​检查网页推送订阅

​设置测试订阅

​通过 API 发送测试推送

推送通知消息报告

​用户识别

​分配外部 ID

​添加数据标签

​添加电子邮件和/或短信订阅

​隐私和用户同意

SDK 收集的数据

处理个人数据

​监听推送、用户和应用内事件

​推送通知事件

​用户状态变化

​高级设置和功能

迁移到 OneSignal

集成

操作按钮

多语言消息

身份验证

自定义结果

​Web SDK 设置和参考

网页推送设置

Web SDK 参考

​FAQ

​网页推送在 HTTP 站点上有效吗？

​为什么我需要 service worker 文件？

​我可以在 iOS（iPhone/iPad）上使用网页推送吗？

​为什么我的通知没有显示？

概述

要求

配置您的 OneSignal 应用和平台

站点设置

站点 URL

本地测试

将 `allowLocalhostAsSecureOrigin` 添加到您的 OneSignal `init` 选项

权限提示

欢迎通知（可选）

高级设置

Webhooks

Service workers

Click behavior

Persistence

Safari certificate (Optional)

上传 service worker 文件

将代码添加到您的网站

iOS web push support

测试 OneSignal SDK 集成

检查网页推送订阅

设置测试订阅

通过 API 发送测试推送

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

监听推送、用户和应用内事件

推送通知事件

用户状态变化

高级设置和功能

Web SDK 设置和参考

FAQ

网页推送在 HTTP 站点上有效吗？

为什么我需要 service worker 文件？

我可以在 iOS（iPhone/iPad）上使用网页推送吗？

为什么我的通知没有显示？