阿里云移动推送+uni-app最佳实践

阿里云移动推送+uni-app最佳实践

前言

uni-app 是一个基于 Vue.js 的框架,允许开发者编写一套代码即可发布到 iOS、Android、Web 以及各种小程序(如微信、支付宝等)和快应用。

移动推送是大多数移动应用所需的基本功能,但直接接入原生的移动推送 SDK uni-app 开发者来说可能较为复杂。为此,我们提供了专门针对 uni-app 的阿里云移动推送插件,简化这一过程。

  • 阿里云移动推送 :阿里云移动推送插件,支持 Android iOS 平台,让开发者能够轻松集成移动推送功能。

  • 阿里云移动推送-厂商通道 :作为 Android 厂商通道扩展包,需与 Aliyun-Push 配合使用,进一步增强推送能力。

通过这些插件,uni-app 开发者可以更简单快捷地实现移动推送功能,无需处理复杂的原生集成问题。

前提条件

请先确保已在 EMAS 控制台完成项目和应用的创建,若尚未完成,请详见 快速入门

1. 获取各厂商通道推送参数

小米

  1. 请登录 小米开放平台 -> 推送运营平台 ,创建您的 App,并开启应用的推送服务。

  2. 请登录 小米开发平台 ,得到注册应用的 AppID、AppKey、AppSecret。

  3. 请登录 EMAS 移动推送控制台,设置您的小米推送密钥(AppSecret),设置方法参见 配置厂商通道密钥

华为

  1. 请登录 华为开发者联盟 ,注册您的应用,在应用信息中获取 APP ID SecretKey。

  2. 参考 配置 AppGallery Connect 文档 在华为开发者联盟配置应用的 SHA256 证书指纹。

  3. 参考 消息回执 文档配置推送的消息回执。请将 https://amspush-ack.aliyuncs.com/hw/ 配置为消息回执地址。

  4. 请登录 EMAS 移动推送控制台,设置您的华为推送密钥(AppID、AppSecret、默认回执 ID),设置方法参见 配置厂商通道密钥

荣耀

  1. 请登录 HONOR Develops , 注册您的应用。在应用服务→推送服务→应用查看中获取 App ID、Client ID、Client Secret 等信息。

  2. 参考 证书指纹生成指南 文档 在荣耀开发者平台上配置签名证书指纹。

  3. 参考 消息回执 文档配置推送的消息回执。请将 https://amspush-ack.aliyuncs.com/ho/ 配置为消息回执地址。

  4. 请登录 EMAS 移动推送控制台,设置您的荣耀推送密钥(App ID),设置方法参见 配置厂商通道密钥

VIVO

  1. 请登录 vivo 开放平台 ,注册您的应用。在应用信息中获取 AppID、AppKey、AppSecret。

  2. 请在 vivo 开放平台的推送服务里待配置应用的应用信息中,开通“APP 回执地址”。请将 https://amspush-ack.aliyuncs.com/vivo/ 配置为消息回执地址。

  3. 请登录 EMAS 移动推送控制台,设置您的 vivo 推送密钥(AppID、AppSecret 和默认回执 ID),设置方法参见 配置厂商通道密钥

OPPO

  1. 请登录 OPPO 开放平台 ,在推送服务中注册您的应用。在配置管理>应用配置中获取 AppKey、AppSecret MasterSecret。

  2. 请登录 EMAS 移动推送控制台,设置您的 OPPO 推送密钥(AppKey MasterSecret),设置方法参见 配置厂商通道密钥

魅族

  1. 请登录 魅族开放平台 ,在魅族消息推送服务中注册您的应用。在应用信息中获取 AppID AppSecret。

  2. 请在魅族推送平台的应用列表,单击打开应用,进入配置管理>回执管理页面,在回执管理页面配置回执链接。请将 http://amspush-ack.aliyuncs.com/mz/ https://amspush-ack.aliyuncs.com/mz/ 配置为消息回执地址。

  3. 请登录移动推送控制台,设置您的魅族推送密钥(AppID AppSecret),设置方法参见 配置厂商通道密钥

谷歌

  1. 请登录 Firebase 创建项目,创建完成后进入项目,在项目中新增 App,并下载对应 App google-services.json 文件。同时记录 google-services.json 文件中的“project_number”, “mobilesdk_app_id”,“project_id”,“current_key”这四个 key 对应的 value, 分别对应为:sendId、applicationId、projectId、apiKey。

  2. Firebase 控制台的项目设置-服务账号中,生成下载私钥文件。

  3. 请登录 EMAS 移动推送控制台,上传您在 Firebase 控制台生成下载的 FCM 服务账号密钥 json 文件,设置方法参见 配置厂商通道密钥

2. Demo 实现获取(可选)

DCloud 插件市场点击 下载示例代码 ZIP 获取 uni-app 集成阿里云移动推送的 Demo 实现。

image

3. 插件依赖和推送参数配置

插件依赖

uni-app 有两种依赖插件的方式,分别为云端插件方式依赖和本地插件方式依赖。以下内容为使用两种不同的方式依赖阿里云移动推送插件和阿里云移动推送-厂商通道插件。

云端插件方式依赖

  1. DCloud 插件市场 点击 购买(0 元)for 云打包 ,购买 阿里云移动推送 插件和 阿里云移动推送-厂商通道 插件。

B2DDA12C-35E7-431E-B753-6424F2975CFA

72A23DCA-9325-45FD-9D1E-24DAB39E09BB

  1. 选择为哪个项目购买。

CB056438-127E-49DB-A613-46E433BFA89D

  1. 填写应用包名。

752CEC25-6D1C-4F83-B5D4-D5CECB89EF35

  1. 在项目的 manifest.json 文件中点击 选择云端插件

01A3A8A1-DDC5-46F4-9A35-8465595EEC4A

  1. 在云端插件列表中选择 阿里云移动推送 插件和 阿里云移动推送-厂商通道 插件。

E3E1F509-3FB9-4488-B099-9D9B5EBFE32E

本地插件方式依赖

  1. DCloud 插件市场 点击 下载 for 离线打包 ,下载 阿里云移动推送 插件包和 阿里云移动推送-厂商通道 插件包。

CAE2C63A-7F88-47A7-A3F8-E37D868B7019

340066F0-1BC5-4E77-B104-D57F8B489C42

  1. 将下载的插件包解压,放到项目的 nativeplugins 文件夹下。

7C34C740-4A36-443D-BFDD-C14C2BFFFF1C

  1. manifest.json 文件中点击 选择本地插件

FCD876C2-44E6-4DAD-90A1-DA8AEBF653FA

  1. 在本地插件列表中选择 阿里云移动推送 插件和 阿里云移动推送-厂商通道 插件。

0536725B-9CFF-4B5F-BD36-5CDCB98595CA

推送参数配置

  1. manifest.json 文件中配置 阿里云移动推送 插件需要的 AppKey AppSecret。

D68617D6-C568-4ECF-92F1-E4991A96815A

  1. manifest.json 文件中配置 阿里云移动推送-厂商通道 插件需要的厂商通道推送参数。

09A74C7D-2509-4214-AE33-076E4C9E9BB3

  1. manifest.json 文件中选择推送模块。

489AEAF0-D0B6-40F6-943A-3AA76E82FEB4

4. 推送注册和消息接收

Android

Android 端推送注册和自有通道消息接收

注册通知通道

Android 8.0 开始,通知展示需要创建通知通道。在项目的 App.vue 文件的 onLaunch 回调方法中创建通知通道。示例代码如下:

<script>
	const channel = uni.requireNativePlugin('Aliyun-Push-NotificationChannel');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'android') {
				// 创建通知通道
				channel.createChannel({
                                  id: '${通知通道Id}',
                                  name: '${通知通道名称}',
                                  desc: '${通知通道描述}',
                                  importance: 3,
</script>

createChannel 更多参数说明如下:

parameter

是否必传

desc

id

通知通道 Id

name

通知通道名称

desc

通知通道描述

importance

通知优先级

allowBubbles

是否允许气泡通知

light

开启指示灯

lightColor

设置指示灯颜色

showBadge

是否在 app icon 的右上角显示消息未读标记

soundPath

铃声文件路径

soundUsage

铃声的使用场景,可以设置如下值:

1:媒体播放

2:语音通信

3:通话中的信令(例如“忙音”嘟嘟声或双音多频音)

4:闹钟

5:通知铃声

soundContentType

设置音频内容类型,可以设置如下值:

1:语音

2:音乐

3:电影

4:提示音或系统声音

soundFlag

定义音频的行为

vibration

是否支持震动

vibrationPattern

通知渠道的振动模式

注册推送

阿里云移动推送插件完成 Android 端自有通道的注册以及添加自有通道的消息回调(包含通知消息和透传消息)。 在项目的 App.vue 文件的 onLaunch 回调方法中完成注册。 示例代码如下:

<script>
	const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'android') {
				// 创建通知通道
				//推送注册
				aliyunPush.registerPush({}, result => {
                                  const event = result.event;
                                  if (event === 'registerPush') {
                                    if (result.code === 'success') {
                                      console.log("注册推送 成功 ");
                                    } else {
                                      console.log("注册推送 " + result.code + " " + result.msg);
                                  } else {
                                    const data = JSON.stringify(result.data);
                                    console.log("receive push event : " + event);
                                    console.log("receive push data : " + data);
</script>

result 回调字段说明如下:

字段

说明

result.event

事件类型,可以有如下值:

registerPush 注册事件。

onNotification 通知消息接收回调。

onMessage:透传消息接收回调。

onNotificationOpened :通知消息点击。

onNotificationRemoved :通知消息移除。

onNotificationReceivedInApp 应用处于前台时通知到达回调。该方法仅对自定义样式通知有效。

onNotificationClickedWithNoAction:无动作通知点击回调。

result .code

注册结果

success :注册成功

其它:注册失败返回的错误码

result .msg

注册失败反馈的错误原因

result.data .deviceId

注册成功返回 deviceId

result.data

消息数据

result.data.title

消息标题

result.data.content

消息内容

result.data.extra

通知消息的扩展参数

仅在 event = onNotificationOpened onNotificationClickedWithNoAction,有值。

result.data.extraStr

通知消息的扩展参数

仅在 event = onNotification ,有值。

result.data.openType

点击通知后的动作。可选值如下:

1:打开应用(默认值)

2:打开应用 AndroidActivity

3:打开 URL

4:无跳转

仅在 event = onNotificationReceivedInApp,有值。

result.data.openActivity

点击通知之后跳转到目标 Activity。

仅在 event = onNotificationReceivedInApp,有值。

result.data.openUrl

点击通知之后跳转的 URL 链接。

仅在 event = onNotificationReceivedInApp,有值。

result.data.msgId

消息 Id。

仅在 event = onNotificationRemoved,有值。

Android 端厂商通道注册和通知消息接收

厂商通道注册说明

厂商通道的注册由 阿里云移动推送-厂商通道 插件负责,集成了插件之后,在 app 启动的时会自动完成厂商通道的注册。

注册厂商通道通知消息回调

用户点击厂商通道消息之后,在应用中获取厂商通道通知消息内容。在项目的 App.vue 文件的 onLaunch 回调方法中注册厂商通道通知消息点击回调。示例代码如下:

<script>
	const aliyunThirdPush = uni.requireNativePlugin('Aliyun-ThirdPush');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'android') {
				// 创建通知通道
				//推送注册
				//注册厂商通道通知消息点击回调
				aliyunThirdPush.registerThirdPush({}, result => {
                                  const data = JSON.stringify(result);
                                  console.log("receive third push : " + data);
</script>
说明
  • 使用厂商通道需要设置一个辅助弹窗,本插件写死辅助弹窗为 com.alibaba.uniplugin.android.third.push.ThirdPushPopupActivity,效果为用户点击通知之后拉起应用。

  • 由于厂商通道由各厂商控制,消息点击回调仅在用户点击通知后触发。如果用户未点击或直接移除通知,应用将无法感知。

iOS

iOS 端推送注册和消息接收

注册推送

iOS 的初始化默认在应用启动时执行,不需要特别调用初始化方法 。但需要注册一些回调接口,用于接收推送数据。

注册接收通知消息回调

注册 iOS 侧接收通知消息的回调。当应用在前台,并且在前台不展示通知时,获取通知消息的内容。在项目的 App.vue 文件的 onLaunch 回调方法中注册通知消息接收回调。示例代码如下:

<script>
	const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'ios') {
				// 注册通知消息接收回调
				aliyunPush.setNotificationCallback({}, result => {
                                  const data = JSON.stringify(result);
                                  console.log("setNotificationCallback : " + data);
</script>

注册通知消息点击回调

注册 iOS 侧通知消息被用户点击时的回调。在项目的 App.vue 文件的 onLaunch 回调方法中注册通知消息点击回调。示例代码如下:

<script>
	const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'ios') {
				// 注册通知消息接收回调
				// 注册通知消息点击回调
				aliyunPush.setNotificationResponseCallback({}, result => {
                                  const data = JSON.stringify(result);
                                  console.log("setNotificationResponseCallback : " + data);
</script>

注册接收透传消息回调

注册 iOS 侧接收透传消息的回调。 在项目的 App.vue 文件的 onLaunch 回调方法中注册透传消息接收回调。 示例代码如下:

<script>
	const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
	export default {
		onLaunch: function() {
			if (uni.getSystemInfoSync().platform === 'ios') {
				// 注册通知消息接收回调
				// 注册通知消息点击回调
				// 注册透传消息接收回调
				aliyunPush.setMessageCallback({}, result => {
                                  const data = JSON.stringify(result);
                                  console.log("setMessageCallback : " + data);
</script>

5. 日志相关

日志输出控制

Android

Android 端设置日志输出级别

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.setLogLevel({
  logLevel: 'debug'
});
说明

参数 logLevel,包括 debug、info、error、off,其中 off 是关闭日志。

iOS

iOS 端开启 SDK 日志

开启 iOS 侧阿里云移动推送 SDK 日志,用于在开发测试过程中排查问题。

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.turnOnDebug({});

添加 阿里云移动推送 插件日志输出回调

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.registerLog({}, result => {
    console.warn("push plugin log : " + result);
});

添加 阿里云移动推送-厂商通道 插件日志输出回调

const aliyunThirdPush = uni.requireNativePlugin('Aliyun-ThirdPush');
aliyunThirdPush.registerLog({}, result => {
    console.warn("third push plugin log : " + result);
})

6. API

通用 API

获取 deviceId

获取设备唯一标识,指定设备推送时需要 。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
const result = aliyunPush.getDeviceId();
console.log("getDeviceId : " + result.data.deviceId);

绑定账号

将应用内账号和推送通道相关联,可以实现按账号的定向消息推送。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.bindAccount({
    account: "${account}"
}, result => {
    console.log("bindAccount : " + result);
});
说明

解绑账号

将应用内账号和推送通道解除关联。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.unBindAccount({}, result => {
    console.log("unBindAccount : " + result);
});

添加别名

为设备添加别名,可以实现按别名的定向消息推送。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.addAlias({
    alias: "${alias}"
}, result => {
    console.log("addAlias : " + result);
});
说明

移除别名

删除设备别名。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.removeAlias({
    alias: "${alias}"
}, result => {
    console.log("removeAlias : " + result);
});

查询别名

查询设备别名。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.listAliases({}, result => {
    console.log('listAliases : '+result.aliases);
});

绑定标签

为指定目标(设备,账号和别名)添加标签,可以实现按标签的定向消息推送。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.bindTag({
    tags: ["${tag}"],
    target: 3,
    alias: ${alias} // 当target为3时,需传alias参数
}, result => {
    console.log('bindTag : '+result);
});
说明

解绑标签

解绑指定目标的标签。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.unBindTag({
    tags: ["${tag}"],
    target: 1,
}, result => {
    console.log('bindTag : '+result);
});

设置数字角标

设置设备上的应用角标。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.setBadgeNum({
    badge: ${角标数字},
    badgeNum: ${角标数字}
});
说明

Android 端当前接口仅支持华为,荣耀和 vivo 机型。

Android 端角标实现说明请参考: 如何实现数字角标

Android 端传参为:badge。

iOS 端传参为:badgeNum。

Android iOS 可用 API

Android

绑定手机号

为提高信息的到达率和实效性,扩展推送的使用场景,我们推出了推送与短信的融合通知模式。开发者可以设置在一定时间内,如果用户未收到或未点击推送,通过短信补发通知用户。

为了实现推送短信融合方案,需要绑定手机号。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.bindPhoneNumber({
    phone: "${phoneNumber}"
}, result => {
    console.log('bindPhoneNumber : '+result);
});
说明

更多关于绑定/解绑手机号说明,请参考: 短信通知相关接口

解绑手机号

解绑手机号。 示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.unBindPhoneNumber({}, result => {
    console.log('unBindPhoneNumber : '+result);
});

检查通知权限是否开启

判断通知权限。 示例代码如下:

const channel = uni.requireNativePlugin('Aliyun-Push-NotificationChannel');
const result = channel.isNotificationEnabled({
    id : '${通道Id}',
});
说明

isNotificationEnabled 如果传了参数 id(通知通道 Id),返回的是通知通道是否可用。如果没有传参数 id(通知通道 Id),返回的是当前应用是否开启通知权限。

前往通知权限设置页

跳转到当前应用的通知权限管理页面。 示例代码如下:

const channel = uni.requireNativePlugin('Aliyun-Push-NotificationChannel');
channel.goNotificationSettings({
  id : '${通道Id}',
});
说明

goNotificationSettings 如果传了参数 id(通知通道 Id),跳转的页面为当前通知通道的设置页面。如果没有传参 id(通知通道 Id),跳转到当前应用的通知权限管理页面。

iOS

设置前台时是否展示通知( showNoticeWhenForeground

设置 iOS 侧,应用在前台时,是否展示推送通知,默认 false 不展示,通过 setNotificationCallback 注册的回调接收推送通知数据。

当设置为 true 时,应用在前台时,推送通知,不会回调 setNotificationCallback 注册的回调接口,而是直接展示通知,当用户点击通知时,会回调 setNotificationResponseCallback 注册的回调接口。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.showNoticeWhenForeground({
   enable: true
});

同步数字角标

同步角标个数给阿里云服务 。示例代码如下:

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.syncBadgeNum({
    badgeNum: ${角标数字}
}, result => {
    const data = JSON.stringify(result);
    console.log("syncBadgeNum : " + data);