跳转到主要内容
仅在需要高级配置或程序化控制时使用此自定义代码设置。对于大多数用户，我们推荐：
如果您使用 JavaScript 框架，请遵循以下专门指南：

​
要求

  • HTTPS 网站：Web 推送在 HTTP 或无痕/隐私模式下无法工作。
  • 服务器访问权限：您需要将服务工作器文件上传到您的网站。
  • 单一源：Web 推送遵循同源策略。如果您有多个源（域名/子域名），则需要多个 OneSignal 应用（每个源一个）。要遵守此浏览器限制，您可以：
    • 将订阅流量重定向到单一源。
    • 为每个源创建多个 OneSignal 应用。

​
配置您的 OneSignal 应用和平台

在 OneSignal 仪表板中：
  • 前往 Settings > Push & In-App > Web。
  • 选择 Custom Code 集成类型。

​
站点设置

添加站点详细信息：
  • Site Name：您的网站名称和默认通知标题。
  • Site URL：您网站的确切源，例如 https://yourdomain.com。如果您的网站没有配置 www.，请避免使用它。如果您有多个源，请参阅要求。
  • Auto Resubscribe：启用此功能可在用户清除浏览器数据后返回您的网站时自动重新订阅（无需新的权限提示）。
  • Default Icon URL：上传在通知和提示中显示的正方形 256x256px PNG 或 JPG 图像。如果未设置，则默认使用铃铛图标。
OneSignal web push configuration showing site name, URL, and icon settings

​
本地测试

要在 localhost 上测试，请使用与生产应用不同的 OneSignal 应用，并在 init 选项中添加 allowLocalhostAsSecureOrigin: true。 如果您使用自签名证书在 HTTPS 上测试 localhost，可能需要使用 --allow-insecure-localhost 告知 Chrome 忽略无效证书。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>

​
Safari Web 推送证书（可选）

OneSignal 免费自动提供 Safari 证书。仅当您有需要使用的现有 Safari Web 推送证书时才启用此功能。
Safari certificate upload option
如果启用，请上传您的 Safari Web .p12 Push Certificate 并输入密码。 点击 Save 继续。

​
上传服务工作器文件

在 Web 推送配置的下一页，您将获得 OneSignalSDKWorker.js 服务工作器文件。 Web SDK 默认在您网站的根目录中查找此文件，例如 https://yourdomain.com/OneSignalSDKWorker.js。您可以在代码中更改文件位置、名称和作用域。

OneSignal 服务工作器

高级服务工作器配置、自定义集成以及从其他提供商迁移。

​
将代码添加到网站

将此代码添加到您网站的 <head> 部分。替换：
  • YOUR_ONESIGNAL_APP_ID 为您在 OneSignal 仪表板中的实际应用 ID
  • YOUR_SAFARI_WEB_ID 为您在 OneSignal 仪表板中的实际 Safari Web ID
HTML
<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",
      safari_web_id: "YOUR_SAFARI_WEB_ID",
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

​
iOS Web 推送支持

Apple 开始在运行 iOS 16.4+ 的 iPhone 和 iPad 上支持 Web 推送通知。与 Android 设备不同（在支持的浏览器上访问即可使用），Apple 添加了一些额外要求，例如 manifest.json 文件和用户将您的网站添加到主屏幕的操作。

iOS Web 推送设置

添加所需的 manifest.json 文件并引导用户将您的网站添加到主屏幕。

​
测试 OneSignal SDK 集成

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

​
检查网页推送订阅

1

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

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

检查您的 OneSignal 控制台

  • 前往受众 > 订阅。
  • 您应该看到状态为已订阅的新条目。
OneSignal 控制台订阅页面，显示一个状态为已订阅的网页推送订阅
您已成功创建了网页推送订阅。 当用户首次订阅您网站的推送通知时，将创建网页推送订阅。

​
设置测试订阅

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

添加到测试订阅。

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

命名您的订阅。

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

创建测试用户细分。

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

命名细分。

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

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

细分编辑器，已选择测试用户过滤器，细分命名为 Test Users
您已成功创建了测试用户细分。 现在我们可以测试向这个单独设备和测试用户组发送消息。

​
通过 API 发送测试推送

1

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

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

更新提供的代码。

在下面的代码中将 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"
}'
3

运行代码。

在您的终端中运行代码。
4

检查图片和确认投递。

如果所有设置步骤都成功完成，测试订阅应该会收到通知。
仅 Chrome 支持图片。图片在收缩的通知视图中显示很小。展开通知以查看完整图片。
Chrome macOS 上展开的推送通知，显示自定义图片
5

检查确认投递。

在您的控制台中，前往投递 > 已发送消息，然后点击消息查看统计数据。您应该看到已确认统计数据，表示设备收到了推送。
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 在用户选择加入时自动创建网页推送订阅。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。 如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 将将其添加到现有用户，不会创建重复。 您可以通过控制台中的受众 > 用户或View user API查看统一用户。
多渠道沟通的最佳实践
  • 在添加电子邮件或短信订阅之前获得明确同意。
  • 向用户解释每个沟通渠道的好处。
  • 提供渠道偏好设置，以便用户可以选择他们喜欢的渠道。

​
隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意门控方法： 有关隐私和安全的更多信息：

SDK 收集的数据

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

处理个人数据

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

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

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

​
推送通知事件

​
用户状态变化

​
高级设置和功能

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

迁移到 OneSignal

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

集成

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

操作按钮

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

多语言消息

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

身份验证

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

自定义结果

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

​
Web SDK 设置和参考

网页推送设置

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

Web SDK 参考

可用方法和配置选项的完整详情。
恭喜！您已成功完成 Web SDK 设置指南。

​
常见问题

​
Web 推送通知需要 HTTPS 吗？

是的。所有现代浏览器都需要 HTTPS 才能支持推送通知。如果您的网站使用 HTTP，您必须在设置 Web 推送之前迁移到 HTTPS。

​
我可以将此设置用于单页应用程序 (SPA) 吗？

可以。Custom Code 设置是使用 React、Angular 或 Vue 等框架构建的 SPA 的推荐方法。请参阅本页顶部的框架特定指南，了解 Angular、React 和 Vue。

​
如果用户清除其浏览器数据会怎样？

用户的推送订阅将被删除。如果启用了 Auto Resubscribe，他们下次访问您的网站时将自动重新订阅。

​
相关页面

权限请求

配置提示用户订阅的时间和方式。

Web SDK 参考

OneSignal Web SDK 的完整 API 参考。