Web SDK 设置 - OneSignal

概述

网页推送通知让您能够向用户发送实时更新、提醒和个性化消息，从而提高参与度和留存率。OneSignal 支持所有主要浏览器和平台，让您只需编写一次即可跨平台推送：Chrome、Firefox、Edge、Safari 以及其他支持的浏览器。

要求

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

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

配置您的 OneSignal 应用和平台

在 OneSignal 仪表板中：

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

在 OneSignal 设置中激活网页平台

选择集成类型：

典型站点（推荐）

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

WordPress

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

自定义代码

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

站点设置

添加站点详情：

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

OneSignal 仪表板中的 Web 设置

站点 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 仪表板中的本地测试

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

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

html

  <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。

Service workers

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

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

Service worker 配置

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

有关更多详情，请参阅 OneSignal Service Worker。

Click behavior

控制用户在点击通知时如何导航到您设置的 URL。

如果用户没有在任何浏览器选项卡中打开您的站点，并点击了将他们带到您站点的通知，浏览器将打开一个新选项卡并导航到通知的 URL。
如果用户在一个或多个浏览器选项卡中打开了您的站点，并点击了将他们带到您站点的通知，浏览器可以有几种可能的行为方式供您配置：
- 精确导航（默认）- 如果通知的精确 URL（例如 example.com/product）与浏览器已经打开的选项卡匹配，浏览器将在该选项卡中导航到通知的 URL。
- 源导航 - 如果通知的源（例如 example.com）与浏览器已经打开的选项卡匹配，浏览器将在该选项卡中导航到通知的 URL。
- 精确聚焦 - 如果通知的精确 URL（例如 example.com/product）与浏览器已经打开的选项卡匹配，浏览器将聚焦在该选项卡上，但不刷新页面。
- 源聚焦 - 如果通知的源（例如 example.com）与浏览器已经打开的选项卡匹配，浏览器将聚焦在该选项卡上，但不刷新页面。

Persistence

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

Safari certificate (Optional)

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

Safari 证书配置

上传 service worker 文件

在上面高级设置 > Service worker 中简要讨论的，我们将在您的站点中添加 OneSignalSDKWorker.js Service Worker 文件。

上传 service worker 文件步骤

如果您没有在高级设置 > Service worker 部分中设置 Service worker 文件路径，您将需要将 OneSignalSDKWorker.js 文件放置在您站点的顶级根目录中。否则，您将需要将其放置在您设置的目录中。

选项 1. 在服务器上创建文件并复制代码
选项 2. 下载 zip 文件夹并上传

创建一个名为 OneSignalSDKWorker.js 的新文件并将其设为公开。
将以下导入语句复制粘贴到文件中：

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

文件上传到您的服务器后，检查以下内容以确保其正常工作：

验证位置

确保文件位于与高级设置 > 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，建议查看我们的 OneSignal Service Worker 文档。

将代码添加到您的网站

现在您应该都准备好将我们的 SDK 添加到您的站点了。我们提供的 JavaScript SDK 代码应该在任何站点上都能工作，但如果您的站点是使用 Angular、React JS 或 Vue JS 设置的，那么请进入这些链接。要使用我们的 JavaScript SDK 在您的站点上初始化 OneSignal，请将提供的代码复制/粘贴到您网站的 <head> 标签中。我们的仪表板将提供以下代码，但包含您的 OneSignal 应用 ID。

JavaScript

  <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 控制台

检查 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 支持图片。图片在收缩的通知视图中显示很小。展开通知以查看完整图片。

Chrome macOS 上带图片的展开推送通知

检查确认投递。

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

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。

OneSignal 中一个用户资料，包含名为'current_level'的标签，设置为'6'

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

细分编辑器显示针对 current_level 值大于 4 且小于 10 的用户的细分

显示针对 5-10 级细分的个性化消息推送通知的截图

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

之前我们看到了我们的 SDK 如何创建网页推送订阅来发送推送。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。

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

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

通过外部 ID 统一的具有推送、电子邮件和短信订阅的用户资料

多渠道沟通的最佳实践

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

隐私和用户同意

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

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

查看我们的隐私和安全文档了解更多：

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

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

推送通知事件

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

用户状态变化

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

高级设置和功能

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

Web SDK 设置和参考

通过查看Web 推送设置指南，确保您已启用所有关键功能。有关可用方法和配置选项的完整详情，请访问Web SDK 参考。

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

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

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

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

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

​概述

​要求

​配置您的 OneSignal 应用和平台

典型站点（推荐）

WordPress

自定义代码

​站点设置

​站点 URL

​本地测试

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

​权限提示

​欢迎通知（可选）

​高级设置

​Webhooks

​Service workers

​Click behavior

​Persistence

​Safari certificate (Optional)

​上传 service worker 文件

​将代码添加到您的网站

​iOS web push support

iOS Web Push Setup

​测试 OneSignal SDK 集成

​检查网页推送订阅

​设置测试订阅

​通过 API 发送测试推送

​用户识别

​分配外部 ID

​添加数据标签

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

​隐私和用户同意

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

​推送通知事件

​用户状态变化

​高级设置和功能

​Web SDK 设置和参考

概述

要求

配置您的 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 设置和参考