跳转到主要内容

​
概述

本指南介绍如何将 OneSignal 推送通知集成到 Vue.js 应用中。它涵盖了使用官方 OneSignal Vue 插件的 Vue 2 和 Vue 3，以及包括服务工作器配置和 TypeScript 支持在内的关键设置注意事项。

​
要求

  • 已配置的 OneSignal 应用和平台。请参阅 Web 推送设置 开始使用。

​
Vue 兼容性

确保安装与您的 Vue 环境兼容的插件版本。
VueOneSignal Plugin
2onesignal-vue
3onesignal-vue3

​
安装

通过您首选的包管理器安装： 
yarn add onesignal-vue
# or yarn add @onesignal/onesignal-vue3

​
初始化

在您的根组件中导入 OneSignal 服务并初始化它。init 函数返回一个在 OneSignal 加载时解析的 promise。 将 YOUR_APP_ID 替换为在密钥和 ID 中找到的 OneSignal 应用 ID。 
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
});
OneSignal 插件自动公开一个在应用内部可访问的 $OneSignal 全局属性。

​
Composition API

您还可以通过 useOneSignal() 钩子来利用 Vue 的 Composition API，该钩子可以从 setup 中调用。

​
自定义初始化选项

您可以使用额外的 init 参数 自定义您的初始化。

​
服务工作器设置

如果您还没有这样做，您需要下载 OneSignal 服务工作器文件添加到您的站点。 OneSignalSDKWorker.js 文件必须是公开可访问的。您可以将其放在 public 目录、顶级根目录或子目录中。但是，如果您将文件放在子目录中和/或您的站点有另一个服务工作器，那么请确保指定路径。详情请参阅 OneSignal 服务工作器。
选项描述
serviceWorkerParam由 OneSignal 工作器控制的范围。建议： 使用自定义子路径（例如 "/onesignal/"）。
serviceWorkerPath您托管的 OneSignal 服务工作器文件的路径（例如 "onesignal/OneSignalSDKWorker.js"）。必须是公开可访问的。
Example: 
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 初始化两次，这可能导致控制台错误。
    • 这是由于 <React.StrictMode> 导致效果在开发中运行两次。要解决此问题，请在开发期间从根组件中移除 <React.StrictMode>。
严格模式只影响开发环境——不会影响生产构建。

​
测试 OneSignal SDK 集成

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

​
检查网页推送订阅

1

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

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

网页推送原生权限提示

2

检查您的 OneSignal 控制台

检查 OneSignal 控制台：
  • 前往受众 > 订阅。
  • 您应该看到状态为已订阅的新条目。

控制台显示订阅状态为'已订阅'

您已成功创建了网页推送订阅。 当用户首次订阅您网站的推送通知时，将创建网页推送订阅。

​
设置测试订阅

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

添加到测试订阅。

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

将设备添加到测试订阅

2

命名您的订阅。

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

控制台显示'命名您的订阅'字段

3

创建测试用户细分。

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

命名细分。

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

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

使用测试用户过滤器创建'测试用户'细分

您已成功创建了测试用户细分。 现在我们可以测试向这个单独设备和测试用户组发送消息。

​
通过 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。

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

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

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


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

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

之前我们看到了我们的 SDK 如何创建网页推送订阅来发送推送。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。 如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 将将其添加到现有用户，不会创建重复。 您可以通过控制台中的受众 > 用户或View user API查看统一用户。

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

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

​
隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意门控方法： 查看我们的隐私和安全文档了解更多：

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

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

​
推送通知事件

​
用户状态变化

​
高级设置和功能

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

​
Web SDK 设置和参考

通过查看Web 推送设置指南，确保您已启用所有关键功能。 有关可用方法和配置选项的完整详情，请访问Web SDK 参考。
恭喜！您已成功完成 Web SDK 设置指南。
需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：
  • 您遇到的问题详情以及复现步骤（如有）
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID（如适用）
  • 您在 OneSignal 控制台中测试的消息 URL（如适用）
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助！