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.content
  const extras = event.extras
  
  uni.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 开发技巧。