> ## 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.
# Vue JS Web SDK 设置
> 使用 onesignal-vue 或 @onesignal/onesignal-vue3 插件将 OneSignal Web 推送通知集成到您的 Vue.js 应用中。了解如何安装、配置和自定义服务工作器以实现无缝推送投递。
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 推送通知集成到 Vue.js 应用中。它涵盖了使用官方 OneSignal Vue 插件的 Vue 2 和 Vue 3，以及包括服务工作器配置和 TypeScript 支持在内的关键设置注意事项。
***
## 要求
* 已配置的 OneSignal 应用和平台。请参阅 [Web 推送设置](./web-push-setup) 开始使用。
### Vue 兼容性
确保安装与您的 Vue 环境兼容的插件版本。
| Vue | OneSignal Plugin |
| --- | ------------------------------------------------------------- |
| 2 | [onesignal-vue](https://github.com/OneSignal/onesignal-vue) |
| 3 | [onesignal-vue3](https://github.com/OneSignal/onesignal-vue3) |
***
## 安装
通过您首选的包管理器安装：
```bash yarn theme={null}
yarn add onesignal-vue
# or yarn add @onesignal/onesignal-vue3
```
```bash npm theme={null}
npm install --save onesignal-vue
# or npm install --save @onesignal/onesignal-vue3
```
***
## 初始化
在您的根组件中导入 OneSignal 服务并初始化它。`init` 函数返回一个在 OneSignal 加载时解析的 promise。
将 `YOUR_APP_ID` 替换为在[密钥和 ID](./keys-and-ids) 中找到的 OneSignal 应用 ID。
```javascript Vue2 theme={null}
import Vue from 'vue'
import OneSignalVue from 'onesignal-vue'
Vue.use(OneSignalVue);
new Vue({
render: h => h(App),
beforeMount() {
this.$OneSignal.init({ appId: 'YOUR_APP_ID' });
}
}).$mount('#app')
//Example 1
await this.$OneSignal.init({ appId: 'YOUR_APP_ID' });
// do other stuff
//Example 2
this.$OneSignal.init({ appId: 'YOUR_APP_ID' }).then(() => {
// do other stuff
});
```
```javascript Vue3 theme={null}
/*
在 Vue 3 中，您可以直接将 OneSignal 初始化选项作为参数传递给 `use` 函数。如果您更喜欢编辑器的好处（如代码补全），您仍然可以单独初始化。
*/
import { createApp } from 'vue'
import OneSignalVuePlugin from '@onesignal/onesignal-vue3'
createApp(App).use(OneSignalVuePlugin, {
appId: 'YOUR_APP_ID',
}).mount('#app');
// OR
import { createApp } from 'vue'
import OneSignalVuePlugin from '@onesignal/onesignal-vue3'
createApp(App).use(OneSignalVuePlugin).mount('#app');
// component
this.$OneSignal.init({
appId: "YOUR_APP_ID"
});
```
OneSignal 插件自动公开一个在应用内部可访问的 `$OneSignal` 全局属性。
### Composition API
您还可以通过 `useOneSignal()` 钩子来利用 Vue 的 [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)，该钩子可以从 [`setup`](https://vuejs.org/api/composition-api-setup.html#basic-usage) 中调用。
### 自定义初始化选项
您可以使用额外的 [`init` 参数](./web-sdk-reference#init) 自定义您的初始化。
### 服务工作器设置
如果您还没有这样做，您需要[下载 OneSignal 服务工作器文件](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip)添加到您的站点。
`OneSignalSDKWorker.js` 文件必须是公开可访问的。您可以将其放在 `public` 目录、顶级根目录或子目录中。但是，如果您将文件放在子目录中和/或您的站点有另一个服务工作器，那么请确保指定路径。详情请参阅 [OneSignal 服务工作器](./onesignal-service-worker)。
| 选项 | 描述 |
| -------------------- | ---------------------------------------------------------------------------- |
| `serviceWorkerParam` | 由 OneSignal 工作器控制的范围。**建议：** 使用自定义子路径（例如 `"/onesignal/"`）。 |
| `serviceWorkerPath` | 您托管的 OneSignal 服务工作器文件的路径（例如 `"onesignal/OneSignalSDKWorker.js"`）。必须是公开可访问的。 |
**Example:**
```javascript theme={null}
this.$OneSignal.init({
appId: 'YOUR-ONESIGNAL-APP-ID',
serviceWorkerParam: {
scope: '/onesignal/'
},
serviceWorkerPath: 'onesignal/OneSignalSDKWorker.js'
});
```
#### 托管工作器
* Public root (default): `/OneSignalSDKWorker.js`
* Custom folder (recommended): e.g., `/onesignal/OneSignalSDKWorker.js` as set in the previous step.
#### 验证服务工作器托管
在浏览器中访问该路径以确认其可访问。
如果您使用了根路径：
```
https://your-site.com/OneSignalSDKWorker.js
```
如果使用示例路径：
```
https://your-site.com/onesignal/OneSignalSDKWorker.js
```
它应该返回有效的 JavaScript。
### 重要注意事项
* 避免在开发中重复初始化
* 在开发环境中测试时，您可能会看到 OneSignal SDK 初始化两次，这可能导致控制台错误。
* 这是由于 `` 导致效果在开发中运行两次。要解决此问题，请在开发期间从根组件中移除 ``。
严格模式只影响开发环境——不会影响生产构建。
***
## 测试 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 设置指南。
***
需要帮助？
与我们的支持团队聊天或发送邮件至 `support@onesignal.com`
请包含以下信息：
* 您遇到的问题详情以及复现步骤（如有）
* 您的 OneSignal 应用 ID
* 外部 ID 或订阅 ID（如适用）
* 您在 OneSignal 控制台中测试的消息 URL（如适用）
* 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)
我们很乐意为您提供帮助！