> ## 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 - 自定义代码设置
> 使用自定义代码集成设置 OneSignal Web 推送通知的完整指南。为 Chrome、Firefox、Safari 和其他 Web 浏览器配置 JavaScript SDK、服务工作器和 Safari 证书。
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
;
};
仅在需要高级配置或程序化控制时使用此自定义代码设置。对于大多数用户，我们推荐：
* [典型 Web 推送设置](./web-push-setup)
* [WordPress 设置](./wordpress)
* [Shopify 设置](./shopify)
如果您使用 JavaScript 框架，请遵循以下专门指南：
* [Angular 设置](./angular-setup)
* [React JS 设置](./react-js-setup)
* [Vue JS 设置](./vue-js-setup)
## 要求
* HTTPS 网站：Web 推送在 HTTP 或无痕/隐私模式下无法工作。
* 服务器访问权限：您需要将服务工作器文件上传到您的网站。
* 单一源：Web 推送遵循[同源策略](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)。如果您有多个源（域名/子域名），则需要多个 OneSignal 应用（每个源一个）。要遵守此浏览器限制，您可以：
* 将订阅流量重定向到单一源。
* 为每个源创建多个 OneSignal 应用。
***
## 配置您的 OneSignal 应用和平台
在 OneSignal 仪表板中：
* 前往 **Settings > Push & In-App > Web**。
* 选择 **Custom Code** 集成类型。
### 站点设置
添加站点详细信息：
* **Site Name**：您的网站名称和默认通知标题。
* **Site URL**：您网站的确切[源](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)，例如 `https://yourdomain.com`。如果您的网站没有配置 `www.`，请避免使用它。如果您有多个源，请参阅[要求](#requirements)。
* **Auto Resubscribe**：启用此功能可在用户清除浏览器数据后返回您的网站时自动重新订阅（无需新的权限提示）。
* **Default Icon URL**：上传在通知和提示中显示的正方形 `256x256px` PNG 或 JPG 图像。如果未设置，则默认使用铃铛图标。
#### 本地测试
要在 localhost 上测试，请使用与生产应用不同的 OneSignal 应用，并在 `init` 选项中添加 `allowLocalhostAsSecureOrigin: true`。
如果您使用自签名证书在 HTTPS 上测试 localhost，可能需要使用 `--allow-insecure-localhost` 告知 Chrome 忽略无效证书。Firefox 和 Safari 提供内置机制来为安全证书添加例外。
```html theme={null}
```
### Safari Web 推送证书（可选）
OneSignal 免费自动提供 Safari 证书。仅当您有需要使用的现有 Safari Web 推送证书时才启用此功能。
如果启用，请上传您的 `Safari Web .p12 Push Certificate` 并输入密码。
点击 **Save** 继续。
### 上传服务工作器文件
在 Web 推送配置的下一页，您将获得 `OneSignalSDKWorker.js` 服务工作器文件。
Web SDK 默认在您网站的根目录中查找此文件，例如 `https://yourdomain.com/OneSignalSDKWorker.js`。您可以在代码中更改文件位置、名称和作用域。
高级服务工作器配置、自定义集成以及从其他提供商迁移。
### 将代码添加到网站
将此代码添加到您网站的 `` 部分。替换：
* `YOUR_ONESIGNAL_APP_ID` 为您在 OneSignal 仪表板中的实际应用 ID
* `YOUR_SAFARI_WEB_ID` 为您在 OneSignal 仪表板中的实际 Safari Web ID
```html HTML theme={null}
```
### iOS Web 推送支持
Apple 开始在运行 iOS 16.4+ 的 iPhone 和 iPad 上支持 Web 推送通知。与 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 设置指南。
***
***
## 常见问题
### Web 推送通知需要 HTTPS 吗？
是的。所有现代浏览器都需要 HTTPS 才能支持推送通知。如果您的网站使用 HTTP，您必须在设置 Web 推送之前迁移到 HTTPS。
### 我可以将此设置用于单页应用程序 (SPA) 吗？
可以。Custom Code 设置是使用 React、Angular 或 Vue 等框架构建的 SPA 的推荐方法。请参阅[本页顶部](#)的框架特定指南，了解 [Angular](./angular-setup)、[React](./react-js-setup) 和 [Vue](./vue-js-setup)。
### 如果用户清除其浏览器数据会怎样？
用户的推送订阅将被删除。如果启用了 **Auto Resubscribe**，他们下次访问您的网站时将自动重新订阅。
***
## 相关页面
配置提示用户订阅的时间和方式。
OneSignal Web SDK 的完整 API 参考。