Uniapp 集成极光推送(JPush)完整指南

---

前言

在移动应用开发中，消息推送是提升用户留存和活跃度的重要手段。极光推送(JPush)作为国内领先的推送服务提供商，以其高到达率、稳定性和丰富的功能受到开发者青睐。本文将详细介绍如何在 Uniapp 项目中集成极光推送功能。

---

一、准备工作

1. 注册极光开发者账号

前往 极光官网 注册账号并登录。

2. 创建应用

在极光控制台创建新应用，获取 AppKey（后续配置需要用到）

3. Uniapp项目准备

确保你已经创建好 Uniapp 项目，建议使用 HBuilder X 作为开发工具

二、集成极光推送插件

Uniapp提供了两种集成极光推送的方式：

方法一：使用UniPush（推荐）

UniPush 是 DCloud 联合极光推送推出的推送服务，内置了厂商通道集成，可以显著提高安卓设备的推送到达率。

1. 在 HBuilder X 中打开项目
2. 右键项目 -> 选择 "使用UniPush"
3. 按照向导填写极光推送的 AppKey 等信息
4. 等待配置完成

方法二：手动集成极光推送SDK

如果需要更灵活的控制，可以手动集成：

1. 安装极光推送插件：

npm install jpush-webview-sdk --save

2. 在 main.js 中引入并初始化：

import JPush from 'jpush-webview-sdk'// 初始化极光推送
JPush.init({'appkey': '你的极光AppKey','channel': '应用渠道名称','debug': true // 开启调试模式
})// 监听推送事件
document.addEventListener('jpush.receiveNotification', function(event) {console.log('收到推送通知:', event)// 处理推送消息
}, false)

三、配置原生平台参数

Android配置

1. 在 manifest.json 中配置：

"app-plus": {"distribute": {"android": {"permissions": ["<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>","<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>","<uses-permission android:name=\"android.permission.VIBRATE\"/>","<uses-permission android:name=\"android.permission.WAKE_LOCK\"/>","<uses-permission android:name=\"android.permission.READ_PHONE_STATE\"/>"]}}
}

iOS配置

1. 在 manifest.json 中配置：

"app-plus": {"distribute": {"ios": {"capabilities": {"push": true},"UIBackgroundModes": ["remote-notification"]}}
}

需要配置推送证书，具体参考极光官方文档

四、核心功能实现

1. 获取RegistrationID

function getRegistrationID() {return new Promise((resolve, reject) => {if (window.JPush) {JPush.getRegistrationID(function(rId) {console.log("JPush registrationID: " + rId)resolve(rId)})} else {reject('JPush plugin not available')}})
}

2. 设置别名和标签

function setAlias(alias) {if (window.JPush) {JPush.setAlias({ sequence: 1, alias: alias }, (result) => { console.log('设置别名成功', result) },(error) => { console.log('设置别名失败', error) })}
}function setTags(tags) {if (window.JPush) {JPush.setTags({ sequence: 2, tags: tags }, (result) => { console.log('设置标签成功', result) },(error) => { console.log('设置标签失败', error) })}
}

3. 处理推送消息

// 监听接收通知事件
document.addEventListener('jpush.receiveNotification', function(event) {const content = event.contentconst extras = event.extrasuni.showModal({title: '收到推送',content: content,showCancel: false})// 可以根据extras中的自定义字段进行业务处理if (extras && extras.key === 'value') {// 执行特定业务逻辑}
}, false)// 监听点击通知事件
document.addEventListener('jpush.openNotification', function(event) {const extras = event.extras// 根据推送内容跳转到指定页面if (extras && extras.page) {uni.navigateTo({url: extras.page})}
}, false)

五、调试与常见问题

1. 调试技巧

开启极光调试模式：

JPush.setDebugMode(true)

在极光控制台发送测试推送

2. 常见问题

• Q: 收不到推送？

  • 检查 AppKey 配置是否正确
  • 检查网络权限是否开启
  • 检查设备是否成功注册到极光服务器

• Q: iOS收不到推送?

  • 检查证书配置是否正确
  • 检查是否在真机上测试（模拟器不支持推送）

• Q: 点击通知无法跳转?

  • 检查 openNotification 事件监听是否正确
  • 检查跳转 URL 是否有效

六、高级功能

1. 本地通知

function sendLocalNotification() {if (window.JPush) {JPush.addLocalNotification({builderId: 1,content: '本地通知内容',title: '通知标题',notificationId: 123,broadcastTime: new Date().getTime() + 3000, // 3秒后触发extras: { key: 'value' }})}
}

2. 消息统计

function reportNotificationOpened(msgId) {if (window.JPush) {JPush.reportNotificationOpened({msgId: msgId})}
}

结语

通过本文的介绍，你应该已经掌握了在 Uniapp 中集成极光推送的基本方法。极光推送提供了丰富的 API 和功能，可以根据项目需求进一步探索更多高级特性。在实际开发中，建议结合项目需求设计合理的推送策略，避免过度推送导致用户反感。

如果你在集成过程中遇到任何问题，欢迎在评论区留言讨论。也欢迎关注我的CSDN 账号，获取更多 Uniapp 开发技巧。