阿里云移动推送

更新记录

0.0.6（2023-09-27）

Android SDK升级至最新的3.8.7，ios SDK升级至最新的2.0.4

0.0.5（2023-05-22）

Android推送升级至3.8.6版本

0.0.4（2023-01-13）

Android增加查询标签功能

平台兼容性

Android	Android CPU类型	iOS
适用版本区间：4.4 - 11.0	armeabi-v7a：支持，arm64-v8a：支持，x86：支持	适用版本区间：9 - 15

原生插件通用使用流程：

购买插件，选择该插件绑定的项目。
在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

基本说明

本插件是阿里云移动推送uniapp 插件

参考 uniapp 插件开发文档开发，封装了阿里云移动推送能力

插件说明：

Aliyun-Push是阿里云移动推送插件支持Android iOS
Aliyun-ThirdPush是阿里云移动推送Android厂商通道扩展包，使用此插件必须接入Aliyun-Push

接入过程中如果有使用问题，可以在钉钉搜索群号加入EMAS开发者服务官方答疑群，群号：35248489

准备

待接入的uniapp应用
申请阿里云账号，创建移动应用，注意包名和uniapp应用最终生成的Android、iOS应用包名和bundle id 必须一致，得到阿里云平台的AppKey和AppSecret
如果需要厂商通道，需要参考厂商通道集成说明准备和配置各厂商通道。具体包括在各厂商（华为、小米、oppo、vivo、魅族）申请创建应用，开通移动推送、在阿里云控制台配置各厂商通道推送参数，获取各厂商通道需要在应用代码中配置的参数

本地插件接入

本地插件的接入整体参考uniapp说明

大体步骤如下：

在插件市场点击下载 for 离线打包，下载插件包
复制本地插件包 Aliyun-Push Aliyun-ThirdPush 到uniapp应用的nativeplugins目录
用HBuilder打开uniapp应用，打开manifest.json文件，在App原生插件配置菜单，点击选择本地插件
勾选阿里云移动推送和阿里云移动推送-厂商通道（如果没有厂商通道，可以不选此项。后续相关步骤标为可选）
配置阿里云移动推送的AppKey和AppSecret，Android和iOS如果是一样的，就配置一样的AppKey和AppSecret。
（可选）使用哪个厂商通道，就配置哪个厂商通道的参数，不配置则不使用，具体参数由各厂商平台提供。有些厂商是需要配置多个参数，请注意参数配置完整
在uniapp 应用中注册初始化推送
在uniapp项目的manifest.json中 APP模块配置中打开 Push模块，但是不勾选uniPush

远程插件接入

在插件市场，选择购买 for 云打包，按步骤为应用添加插件
在HBuilder中，选择 manifest.json文件，选择 APP原生插件配置，点击云端插件选择，勾选阿里云移动推送阿里云移动推送-厂商通道两个插件
勾选后，在APP原生插件配置里，会增加阿里云移动推送相关的参数配置
配置阿里云移动推送的AppKey和AppSecret，Android和iOS如果是一样的，就配置一样的AppKey和AppSecret。
（可选）使用哪个厂商通道，就配置哪个厂商通道的参数，不配置则不使用，具体参数由各厂商平台提供。有些厂商是需要配置多个参数，请注意参数配置完整
在uniapp 应用中注册初始化推送
在uniapp项目的manifest.json中 APP模块配置中打开 Push模块，但是不勾选uniPush

初始化示例代码如下：

Android

通知通道创建

Android 8.0开始，通知展示需要设置NotificationChannel，所以需要先创建NotificationChannel

const channel = uni.requireNativePlugin('Aliyun-Push-NotificationChannel');
channel.createChannel({
  id: 'aaa',
  name: '测试通道A',
  desc: '测试创建通知通道',
  importance: 3,
});

可以根据需要创建不同的NotificationChannel，支持参数参考api说明

注册推送

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
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);
  }
});

回调的registerPush事件是注册成功失败的说明。注意：注册推送的回调，同时负责接收推送相关的数据

（可选）注册厂商通道

const aliyunThirdPush = uni.requireNativePlugin('Aliyun-ThirdPush');
aliyunThirdPush.registerThirdPush({}, result => {
  const data = JSON.stringify(result);
  console.log("receive third push : " + data);
});

注册之后，才可以接收到厂商通道推送的数据。注意：厂商通道是厂商控制的，所以此回调只有在用户点击通知之后才能触发。用户未点击或者直接移除，应用是无法感知的。

iOS

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

注册前台推送通知的回调接口

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.setNotificationCallback({}, result => {
    this.handleResult("setNotificationCallback", result);
});

注册用户点击推送通知的回调接口

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.setNotificationResponseCallback({}, result => {
    this.handleResult("setNotificationResponseCallback", result);
});

注册推送消息的回调接口

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
aliyunPush.setMessageCallback({}, result => {
    this.handleResult("setMessageCallback", result);
});

初始化之后需要业务方处理的逻辑

推送初始化之后，可以通过api获取设备ID，需要将设备ID发给业务方服务器，方便后端服务通过设备ID进行推送

获取设备ID的方法如下

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
const result = aliyunPush.getDeviceId();
this.handleResult("getDeviceId", result, function(){
    console.log("getDeviceId : " + result.data.deviceId);
    modal.toast({
        message: "getDeviceId : " + result.data.deviceId,
        duration: 2
    });
});

推送测试

阿里云支持多种推送维度，基本的方式是基于设备推送。推送通知的整体逻辑如下

uniapp 注册推送之后，获取设备ID，上报业务服务
业务侧在需要推送时，获取设备ID，调用阿里云移动推送服务SDK的相关推送api
阿里云服务在接收到推送请求后，查询设备是否在线，然后推送数据给设备

推送消息一般都是设备在前台时进行，走阿里云自有通道，不涉及通知展示和厂商通道

Android 推送通知

Android推送区分设备是否在线

在线，通过阿里云自有通道推送，uniapp在registerPush的回调中，接收到推送相关的数据和事件，sdk会创建相关的通知
离线，如果配置了厂商通道，通过厂商通道推送，当用户点击通知时，通过registerThirdPush的回调获取推送数据

注意：使用厂商通道需要设置一个辅助弹窗，本插件写死辅助弹窗为com.alibaba.uniplugin.android.third.push.ThirdPushPopupActivity，效果为用户点击通知之后拉起应用。

iOS 推送通知

iOS 推送主要区分设备是否在前台

在前台，通过setNotificationCallback注册的回调接口接收推送数据，通知不展示
在后台或者应用未运行，通知直接展示，当用户点击通知时，拉起应用，通过setNotificationResponseCallback注册的回调接口接收推送数据；如果用户直接移除通知，应用无感知

api

Aliyun-Push-NotificationChannel

此模块主要用于创建、更新NotificationChannel，方便应用维护NotificationChannel。使用参考Android文档

获取代码

const channel = uni.requireNativePlugin('Aliyun-Push-NotificationChannel');

createChannel

创建通知通道，内部调用的是Android平台的NotificationManager.createNotificationChannel(NotificationChannel channel)方法，支持的参数如下：

            String id = options.getString("id");
            String name = options.getString("name");
            int importance = options.getIntValue("importance");
            String desc = options.getString("desc");
            String groupId = options.getString("groupId");
            Boolean allowBubbles = options.getBoolean("allowBubbles");
            Boolean light = options.getBoolean("light");
            Integer color = options.getInteger("lightColor");
            Boolean showBadge = options.getBoolean("showBadge");
            String soundPath = options.getString("soundPath");
            Integer soundUsage = options.getInteger("soundUsage");
            Integer soundContentType = options.getInteger("soundContentType");
            Integer soundFlag = options.getInteger("soundFlag");
            Boolean vibration = options.getBoolean("vibration");
            JSONArray vibrationPatternJSONArray = options.getJSONArray("vibrationPattern");

参数相关含义，可以参考NotificationChannel说明

注意：如果要设置groupId，必须先通过createGroup创建通知分组

示例

                channel.createChannel({
                    id: 'aaa',
                    name: '测试通道A',
                    desc: '测试创建通知通道',
                    importance: 3,
                });

createGroup

创建通知分组，内部调用的是Android平台的createNotificationChannelGroup(NotificationChannelGroup group)方法，支持的参数如下

            String id = options.getString("id");
            String name = options.getString("name");
            String desc = options.getString("desc");

参数相关含义，可以参考NotificationChannelGroup说明

示例

                channel.createGroup({
                    id: 'BBB',
                    name: '测试通道分组',
                    desc: '测试创建通知分组',
                });
                channel.createChannel({
                    id: 'b1',
                    name: '测试通道b1',
                    desc: '测试在分组下创建通知通道',
                    importance: 3,
                    groupId: 'BBB',
                });

isNotificationEnabled

判断通知通道是否开启。由于用户可以在设置中管理应用的通知通道，包括关闭通知通道，我们需要判断，并在合适的时机提示用户。

支持的参数如下

String id = options.getString("id");

id为NotificationChannel的ID，可以不传，当不传时，判断的是应用通知的总开关是否开启。有id时，判断的是对应NotificationChannel是否开启。

示例

                // 检查 应用通知的总开关
                const result = channel.isNotificationEnabled({});
                if(result.code == 'success'){
                    modal.toast({
                        message: '通知开关 '+result.data,
                        duration: 2
                    });
                }

                // 检查 应用通知通道的开关
                const result = channel.isNotificationEnabled({
                    id : 'aaa',
                });
                if(result.code == 'success'){
                    modal.toast({
                        message: '通知通道开关 '+result.data,
                        duration: 2
                    });
                }

goNotificationSettings

跳转到通知的设置界面，用于在需要用户修改通知状态时使用。

支持的参数如下

String id = options.getString("id");

id为NotificationChannel的ID，可以不传，当不传时，跳转应用通知管理界面。有id时，跳转对应NotificationChannel的管理界面。

示例

channel.goNotificationSettings({});

channel.goNotificationSettings({
  id : 'aaa',
});

Aliyun-Push

此模块是移动推送的主要模块，主要API都在此模块

获取代码

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

registerLog(Android)

注册日志接口，用于接收推送相关的日志，主要用于debug、定位问题

                aliyunPush.registerLog({}, result => {
                    console.warn("push plugin log : " + result);
                });

setLogLevel(Android)

设置输出的日志级别

支持参数logLevel，包括debug、info、error、off，注意off是关闭日志

示例

aliyunPush.setLogLevel({
  logLevel: 'debug'
});

registerPush(Android)

注册推送，开始接收数据。

回调接口主要包括event和data，event表示事件，data是数据，具体字段不同的事件不同，参考回调数据说明

示例

const aliyunPush = uni.requireNativePlugin('Aliyun-Push');
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);
  }
});

turnOnDebug（iOS）

开启iOS侧 sdk 日志，用于在开发测试过程中排查问题

调用示例

                console.log("call turnOnDebug");
                aliyunPush.turnOnDebug({});

setNotificationCallback（iOS）

调用示例

                console.log("call setNotificationCallback ");
                aliyunPush.setNotificationCallback({}, result => {
                    this.handleResult("setNotificationCallback", result);
                });

setNotificationResponseCallback （iOS）

注册iOS侧接收推送通知被用户点击时的回调。

调用示例

                console.log("call setNotificationResponseCallback ");
                aliyunPush.setNotificationResponseCallback({}, result => {
                    this.handleResult("setNotificationResponseCallback", result);
                });

setMessageCallback （iOS）

注册iOS侧接收推送消息的回调

调用示例

                aliyunPush.setMessageCallback({}, result => {
                    this.handleResult("setMessageCallback", result);
                });

showNoticeWhenForeground （iOS）

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

当设置为true时，应用在前台时，推送通知，不会回调setNotificationCallback注册的回调接口，而是展示通知，当用户点击通知时，会回调setNotificationResponseCallback注册的回调接口

调用示例

                console.log("call showNoticeWhenForground");
                aliyunPush.showNoticeWhenForeground({
                    enable: true
                });

getDeviceId(Android iOS)

获取设备推送ID，注意必须注册推送成功之后，才能获取

调用示例

                const result = aliyunPush.getDeviceId();
                console.log("getDeviceId : " + result.deviceId);

bindAccount(Android iOS)

绑定账号，参考 https://help.aliyun.com/document_detail/195008.html#title-zzo-xuu-r3o

account是要绑定的账号参数

调用示例

                aliyunPush.bindAccount({
                    account: this.account
                }, result => {
                    this.handleResult('bindAccount', result);
                });

unBindAccount(Android iOS)

解绑账号，参考 https://help.aliyun.com/document_detail/195008.html#title-yd6-fa8-u5g

调用示例

                aliyunPush.unBindAccount({}, result => {
                    this.handleResult('unBindAccount', result);
                });

addAlias(Android iOS)

添加设备别名，参考https://help.aliyun.com/document_detail/195011.html#title-kjd-ybj-odm

alias是要添加的别名

调用示例

                aliyunPush.addAlias({
                    alias: this.alias
                }, result => {
                    this.handleResult('addAlias', result);
                });

removeAlias(Android iOS)

移除设备别名，参考https://help.aliyun.com/document_detail/195011.html#title-p9d-rqh-8oc

alias是要移除的别名参数

调用示例

                aliyunPush.removeAlias({
                    alias: this.alias
                }, result => {
                    this.handleResult('removeAlias', result);
                });

listAliases(Android iOS)

查询别名，参考https://help.aliyun.com/document_detail/195011.html#title-buq-5yf-r0i

aliases 为响应的多个别名字符串，格式为别名1,别名2,别名3

调用示例

                aliyunPush.listAliases({}, result => {
                    this.handleResult('listAliases', result, function(){
                        console.log('listAliases '+result.aliases);
                        modal.toast({
                            message: 'listAliases '+result.aliases,
                            duration: 2
                        });
                    });
                });

bindTag(Android iOS)

绑定标签，可以给设备、账号、别名绑定，参考https://help.aliyun.com/document_detail/195010.html#title-l97-wc7-904

tags 为要绑定的标签列表

target 1表示给设备绑定，2表示给账号绑定，3表示给别名绑定

alias 是给别名绑定时，指定的别名值

调用示例

                // 给设备绑定tag
                aliyunPush.bindTag({
                    tags: [this.tag],
                    target: 1
                }, result => {
                    this.handleResult('bindTag', result);
                });

                // 给账号绑定tag
                aliyunPush.bindTag({
                    tags: [this.tag],
                    target: 2
                }, result => {
                    this.handleResult('bindTag', result);
                });

                // 给别名绑定tag
                aliyunPush.bindTag({
                    tags: [this.tag],
                    target: 3,
                    alias: this.alias
                }, result => {
                    this.handleResult('bindTag', result);
                });

unBindTag(Android iOS)

解绑标签，参考https://help.aliyun.com/document_detail/195010.html#title-9r1-7qq-5s5

功能与绑定标签相反，参数含义一致

调用示例

                // 设备解绑标签
                aliyunPush.unBindTag({
                    tags: [this.tag],
                    target: 1,
                }, result => {
                    this.handleResult('unBindTag', result);
                });

                // 账号解绑标签
                aliyunPush.unBindTag({
                    tags: [this.tag],
                    target: 2,
                }, result => {
                    this.handleResult('unBindTag', result);
                });

                // 别名解绑标签
                aliyunPush.unBindTag({
                    tags: [this.tag],
                    target: 3,
                    alias: this.alias
                }, result => {
                    this.handleResult('unBindTag', result);
                });

bindPhoneNumber(Android)

绑定手机号，用于补充短信发送场景，参考https://help.aliyun.com/document_detail/195014.html#title-t02-yj2-n12

phone是要绑定的手机号

调用示例

                aliyunPush.bindPhoneNumber({
                    phone: this.phone
                }, result => {
                    this.handleResult('bindPhoneNumber', result);
                });

unBindPhoneNumber(Android)

解绑手机号，参考 https://help.aliyun.com/document_detail/195014.html#title-k21-32f-fay

调用示例

                aliyunPush.unBindPhoneNumber({}, result => {
                    this.handleResult('unBindPhoneNumber', result);
                });

回调数据说明

字段	类型	说明
event	string	注册推送结果事件 (Android)
code	string	错误码， success ：表示成功
msg	string	错误信息
data	json	事件数据

注册推送事件（注册推送后触发）

字段	类型	说明
event	string	registerPush：注册事件
code	string	success ：表示成功其它：错误码
data.deviceId	string	推送使用的设备ID

接收推送数据事件，在接收到自有通道的数据时发生，本质是推送SDK的回调接口执行，参考SDK文档说明。逻辑是当回调接口触发时，发送和回调方法同名的事件，所有参数封装到data中。

比如

字段	类型	说明
event	string	onNotification：通知接收回调
data.title	string	推送通知标题
data.content	string	推送通知内容
data.extra	json	推送的扩展参数，对应回调方法中的Map<String, String> extraMap参数

字段	类型	说明
event	string	：通知消息接收回调
data.title	string	推送消息标题
data.content	string	推送消息内容

iOS的回调数据字段如下

字段	类型	说明
data.title	string	推送通知标题
data.subTitle	string	推送通知副标题
data.content	string	推送消息内容
data.badgeNum	number	推送角标
data.date	number	推送时间
data.userInfo	json	推送扩展参数
data.action	string	用户点击的操作名称

Aliyun-ThirdPush

此模块主要处理厂商通道相关逻辑

获取代码

const aliyunThirdPush = uni.requireNativePlugin('Aliyun-ThirdPush');

registerLog

注册日志接口

                aliyunThirdPush.registerLog({}, result => {
                    console.warn("third push plugin log : " + result);
                })

registerThirdPush

注册厂商通道的数据接收回调。在用户点击厂商通道推送的通知后，应用通过此接口接收数据。本质是SDK接收到回调之后，把参数封装为数据发送给js。SDK接口参考这里，在onSysNoticeOpened回调执行时，调用此方法注入的回调发送数据

调用示例

                aliyunThirdPush.registerThirdPush({}, result => {
                    const data = JSON.stringify(result);
                    console.log("receive third push : " + data);
                    modal.toast({
                        message: data,
                        duration: 5
                    });
                });

其它说明

以上示例中出现的handleResult方法，是demo对回调数据的统一处理，仅为示意，调用方应该根据业务需要实现每个接口的回调。为了理解接口的回调数据，展示handleResult代码如下

            handleResult(label, result, action) {
                if (result.code === 'success') {
                    if(action) {
                        action();
                    } else {
                        console.log(label + " 成功 ");
                        modal.toast({
                            message: label + " 成功 ",
                            duration: 2
                        });
                    }
                } else {
                    console.log(label + " " + result.code + " " + result.msg);
                    modal.toast({
                        message: label + " " + result.code + " " + result.msg,
                        duration: 2
                    });
                }
            },