> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK 设置
> 通过 JavaScript SDK、service worker 设置和仪表板配置，将 OneSignal 网页推送通知添加到您的网站。
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
## 概述
本指南将带您完成向网站添加 OneSignal 网页推送通知的全流程——从仪表板配置到 SDK 安装。OneSignal 支持 Chrome、Firefox、Edge、Safari 以及[其他主流浏览器](./web-push-setup-faq)。
***
## 要求
* HTTPS 网站：网页推送在 HTTP 或隐身/私人模式下不起作用。
* 服务器访问权限：您需要将 service worker 文件上传到您的站点。
* 单一源：网页推送遵循[同源策略](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)。如果您有多个源（域名/子域名），您需要多个 OneSignal 应用（每个源一个）。要符合此浏览器限制，您可以：
* 将流量重定向到单一源进行订阅。
* 创建多个 OneSignal 应用——每个源一个。
如果您的团队已经创建了 OneSignal 账户，[请申请成为管理员](./manage-team-members) 以便您可以设置应用。否则，请在 [onesignal.com](https://onesignal.com) 注册免费账户开始使用！
***
## 配置您的 OneSignal 应用和平台
在 OneSignal 仪表板中：
* 转到 **设置 > 推送和应用内 > Web**。
选择集成类型：
无需额外编码，直接通过 OneSignal 仪表板管理提示和设置。
使用 WordPress 和我们的官方插件时必需。
为需要对提示和 SDK 配置进行全面控制的开发人员提供。
### 站点设置
添加站点详情：
* **站点名称**：您站点的名称和默认通知标题。
* **站点 URL**：您站点的 URL。有关更多详情，请参阅[站点 URL](#site-url)。
* **自动重新订阅**：启用此功能可在用户清除浏览器数据后返回您的站点时自动重新订阅（无需新的权限提示）
* **默认图标 URL**：上传一个 256x256 像素的正方形 PNG 或 JPG 图片，该图片将出现在通知和提示中。如果未设置，我们将使用铃铛作为默认图标。
#### 站点 URL
输入您站点的确切[源](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)，例如 `https://yourdomain.com`。如果您的站点没有配置为这样，请避免使用 `www.`。
如果您有多个源：
* 重定向到单个源。
* 或者为每个源设置一个 OneSignal 应用。
#### 本地测试
我们的 Web SDK 可以在 localhost 环境中测试。如果您在 localhost 上进行测试，我们建议设置一个与您的生产应用不同的 OneSignal 应用。
将 **站点 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 上测试其他非标准源的原因。
#### 将 `allowLocalhostAsSecureOrigin` 添加到您的 OneSignal `init` 选项
在您的 localhost 站点上初始化 OneSignal 时，请在 OneSignal `init` 选项中添加 `allowLocalhostAsSecureOrigin: true,`。
此外，如果您在 HTTPS 上使用自签名证书测试 localhost，您可能需要要求 Chrome 忽略无效证书进行测试：` --allow-insecure-localhost`。Firefox 和 Safari 提供内置机制来添加安全证书的异常。
```html theme={null}
```
### 权限提示
典型站点设置允许您或您的团队成员随时通过 OneSignal 仪表板添加、删除和更新权限提示。
配置浏览器权限对话框向您的用户显示的时间和方式。
### 欢迎通知（可选）
您还可以设置欢迎通知，在用户订阅推送通知时发送给他们。
### 高级设置
在 OneSignal 仪表板中可配置的其他功能。
#### Webhooks
我们的 Web SDK 提供了将特定的网页推送事件 `POST` 到您选择的 URL 的能力。
网页推送 Webhook 是与 [Event Webhook](./event-streams) 独立的实现，不能混用。
通过 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` 看到该文件的代码可公开访问。
高级 service worker 配置、自定义集成以及从其他提供商迁移。
#### Click behavior
控制用户在点击通知时如何导航到您设置的 [URL](./links)。
如果用户没有在任何选项卡中打开您的站点，浏览器会打开新选项卡并导航到通知 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 下载](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip)。
将此文件放置在站点的根目录或子目录中均可。如果放在子目录中，您需要在[高级设置 > Service workers](#service-workers) 部分设置 **Service worker 文件路径**。
文件上传到您的服务器后，检查以下内容以确保其正常工作：
确保文件位于与 [高级设置 > Service worker](#service-workers) 中设置的相同的 **Service worker 文件路径** 中。如果您没有更新这些设置，那么您应该将文件放在根目录中。例如：
* `https://yourdomain.com/OneSignalSDKWorker.js`
* `https://yourdomain.com/some-subdirectory/OneSignalSDKWorker.js`
`OneSignalSDKWorker.js` 文件必须在您的源上可公开访问和可用。它不能通过 CDN 托管或放置在不同的源上进行重定向。
当您访问文件的 URL 时，您应该看到代码。
这是一个 javascript 文件，需要作为这样提供服务。它不能有 text/html 的 content-type。
高级配置以及从其他网页推送提供商迁移。
## 将代码添加到您的网站
以下 JavaScript SDK 代码适用于任何站点。如果您的站点是使用 [Angular](./angular-setup)、[React JS](./react-js-setup) 或 [Vue JS](./vue-js-setup) 构建的，请点击相应链接。
要使用我们的 JavaScript SDK 在您的站点上初始化 OneSignal，请将提供的代码复制/粘贴到您网站的 `` 标签中。我们的仪表板将提供以下代码，但包含您的 [OneSignal 应用 ID](./keys-and-ids)。
```javascript theme={null}
```
### iOS web push support
Apple 开始在运行 iOS 16.4+ 的 iPhone 和 iPad 上支持网页推送通知。不像 Android 设备只要在支持的浏览器上访问就能"正常工作"，Apple 添加了更多要求，例如 `manifest.json` 文件和用户操作以将您的站点添加到他们的主屏幕。
添加必需的 `manifest.json` 文件并指导用户将您的站点添加到他们的主屏幕。
***
## 测试 OneSignal SDK 集成
本指南帮助您验证 OneSignal SDK 集成是否正常工作，通过测试推送通知和订阅注册。
### 检查网页推送订阅
* 测试时使用 Chrome、Firefox、Edge 或 Safari。
* **请勿使用无痕或隐私浏览模式。** 用户无法在这些模式下订阅推送通知。
* 提示应根据您的[权限提示](/docs/cn/permission-requests)配置出现。
* 在原生提示上点击**允许**以订阅推送通知。
* 前往**受众 > 订阅**。
* 您应该看到状态为**已订阅**的新条目。
您已成功创建了[网页推送订阅](/docs/cn/subscriptions)。
当用户首次订阅您网站的推送通知时，将创建网页推送订阅。
### 设置测试订阅
测试订阅有助于在发送消息前测试推送通知。
在控制台中，在订阅旁边，点击**选项（三个点）**按钮并选择**添加到测试订阅**。
命名订阅，以便您后续在**测试订阅选项卡**中轻松识别您的设备。
前往**受众 > 细分 > 新建细分**。
将细分命名为 `Test Users`（名称很重要，因为后续会用到）。
您已成功创建了测试用户细分。
现在我们可以测试向这个单独设备和测试用户组发送消息。
### 通过 API 发送测试推送
在您的 OneSignal 控制台中，前往**设置 > [密钥和 ID](/docs/cn/keys-and-ids)**。
在下面的代码中将 `YOUR_APP_API_KEY` 和 `YOUR_APP_ID` 替换为您的实际密钥。这段代码使用了我们之前创建的 `Test Users` 细分。
```curl theme={null}
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
***
## 用户识别
上一节介绍了如何创建网页推送[订阅](/docs/cn/subscriptions)。本节将扩展到使用 OneSignal SDK 识别跨所有订阅（包括推送、电子邮件和短信）的[用户](/docs/cn/users)。涵盖外部 ID、标签、多渠道订阅、隐私和事件追踪，帮助您统一并跨平台互动用户。
### 分配外部 ID
使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码中一致地识别用户。这确保您的消息在渠道和第三方系统中保持统一（对[集成](/docs/cn/integrations)尤其重要）。
使用 SDK 的[`login` 方法](/docs/cn/web-sdk-reference#login-external-id)在您的应用每次识别用户时设置外部 ID。
OneSignal 为订阅（订阅 ID）和用户（OneSignal ID）生成唯一的只读 ID。
当用户在不同设备上下载您的应用、订阅您的网站和/或在应用外提供电子邮件地址和电话号码时，将创建新的订阅。
强烈建议通过 SDK 设置外部 ID，以在用户的所有订阅中识别用户，无论订阅是如何创建的。
### 添加数据标签
[标签](/docs/cn/add-user-data-tags)是字符串数据的键值对，您可以使用它们存储用户属性（如 `username`、`role` 或偏好设置）和事件（如 `purchase_date`、`game_level` 或用户交互）。标签为高级[消息个性化](/docs/cn/message-personalization)和[细分](/docs/cn/segmentation)提供支持，允许更高级的使用场景。
当应用中发生事件时，使用 SDK 的[`addTag` 和 `addTags` 方法](/docs/cn/web-sdk-reference#addtag-%2C-addtags)设置标签。
在这个例子中，用户达到了 6 级，可通过名为 `current_level` 的标签识别，值设置为 `6`。
我们可以创建一个等级在 5 到 10 之间的用户细分，然后使用它来发送针对性和个性化的消息：
### 添加电子邮件和/或短信订阅
OneSignal SDK 在用户选择加入时自动创建网页推送订阅。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。
* 使用[`addEmail` 方法](/docs/cn/web-sdk-reference#addemail-%2C-removeemail)创建电子邮件订阅。
* 使用[`addSms` 方法](/docs/cn/web-sdk-reference#addsms-%2C-removesms)创建短信订阅。
如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 将将其添加到现有用户，不会创建重复。
您可以通过控制台中的**受众 > 用户**或[View user API](/reference/view-user)查看统一用户。
多渠道沟通的最佳实践
* 在添加电子邮件或短信订阅之前获得明确同意。
* 向用户解释每个沟通渠道的好处。
* 提供渠道偏好设置，以便用户可以选择他们喜欢的渠道。
***
### 隐私和用户同意
要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意门控方法：
* [`setConsentRequired(true)`](/docs/cn/web-sdk-reference#setconsentrequired)：在给予同意之前阻止数据收集。
* [`setConsentGiven(true)`](/docs/cn/web-sdk-reference#setconsentgiven)：一旦获得同意就允许数据收集。
有关隐私和安全的更多信息：
了解 OneSignal SDK 从用户收集的数据。
依据隐私法规管理和保护用户数据。
***
## 监听推送、用户和应用内事件
使用 SDK 监听器对用户操作和状态变化做出反应。
SDK 为您提供了多个事件监听器可以钩入。查看我们的[SDK 参考指南](/docs/cn/web-sdk-reference)了解更多详情。
### 推送通知事件
* [点击事件监听器](/docs/cn/web-sdk-reference#click)：检测通知何时被点击。
* [前台生命周期监听器](/docs/cn/web-sdk-reference#foregroundwilldisplay)：控制通知在前台的行为。
### 用户状态变化
* [用户状态变化事件监听器](/docs/cn/web-sdk-reference#addeventlistener-user-state)：检测外部 ID 何时被设置。
* [权限观察器](/docs/cn/web-sdk-reference#permissionchange)：追踪用户与原生推送权限提示的特定交互。
* [推送订阅变化观察器](/docs/cn/web-sdk-reference#addeventlistener-push-subscription-changes)：追踪推送订阅状态何时变化。
***
## 高级设置和功能
探索更多功能以增强您的集成：
从其他推送服务迁移到 OneSignal。
将 OneSignal 与第三方工具和平台连接。
为推送通知添加互动按钮。
以用户首选语言发送本地化消息。
使用服务器端身份验证保护您的 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 网页推送设置](./web-push-for-ios)。
### 为什么我的通知没有显示？
常见原因包括 service worker 文件放置位置不正确、仪表板中站点 URL 不匹配，或用户在其浏览器设置中屏蔽了通知。有关完整的故障排除清单，请参阅[通知显示成功但未显示](./notifications-show-successful-but-are-not-being-shown)。
***
需要帮助？
与我们的支持团队聊天或发送邮件至 `support@onesignal.com`
请包含以下信息：
* 您遇到的问题详情以及复现步骤（如有）
* 您的 OneSignal 应用 ID
* 外部 ID 或订阅 ID（如适用）
* 您在 OneSignal 控制台中测试的消息 URL（如适用）
* 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)
我们很乐意为您提供帮助！
***