更新记录

1.1.0（2024-04-15）

1.安卓、IOS支持自定义通知铃声。 2.修复安卓点击消息后只能监听到一次内容问题。

1.0.0（2024-02-28）

1.友盟消息推送SDK新鲜出炉。

平台兼容性

原生插件通用使用流程：

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

付费原生插件目前不支持离线打包。
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已经内嵌了部分通用依赖，本插件仅集成了推送的依赖，如果本插件集成全部依赖，则本插件重复依赖会导致插件异常，在使用本插件同时，请在Hbuilderx中勾选友盟统计模块，这样相当于集成了友盟推送和友盟统计。并且在Hbuilderx中请务必勾选Push(消息推送)模块，无需勾选uniPush，否则可能导致无法收到通知。

地址围栏推送暂时不支持。

集成依赖版本一览

使用方式

配置插件

选择云端插件，并配置下列参数，如图所示：

引入插件

const UmPush = uni.requireNativePlugin("spx-umpush");

Android端

1.初始化

初始话获取devuceToken，请务必遵守合规指南在中向用户告知使用友盟SDK，确保用户同意《隐私政策》之后，再初始化友盟+SDK。参考官方合规三步走：跳转

/**
  * 初始化推送 
  * @param res  异步回调结果
  */
UmPush.initUmPush(res);

调用示例：

// 初始化推送 
UmPush.initUmPush((res) => {
    console.log(res);
})

返回示例：

{
    "deviceToken": "Ag1Now4kZ4If9GaK2NpsRvfNnpv_I5bBESbclOt4b6VU", //设备的 DeviceToken
    "message": "success",
    "code": 0
}

2.监听消息

请在初始化方法前调用。消息后续动作：打开应用(无需实现，默认自动打开app)、打开链接(无需实现，默认自动打开对应链接)、打开指定页面(需要用户自己书写逻辑去实现)、自定义消息、透传消息均会在此收到消息。

/**
  * 监听消息 
  * @param res  异步回调结果
  */
UmPush.onPushMessage(res);

调用示例：

// 监听消息
UmPush.onPushMessage((res)=>{
    console.log(res);
});

点击回调或者消息透传返回示例：

{
    "timestamp": 1698894578015, //时间戳
    "payload": {
        "body": { // 消息体，当display_type=message时，body的内容只有custom有值，当display_type=notification时，body包含如下参数:
            "custom": "", // 自定义消息
            "activity": "hello", //跳转页面
            "title": "我是标题", //通知标题
            "after_open": "go_activity",// "go_activity":打开特定的activity "go_custom":用户自定义内容
            "ticker": "我是标题", // 通知栏提示文字
            "text": "我是内容" // 通知文字描述
        },
        "extra": {}, // JSON格式，用户自定义key-value。
        "display_type": "notification" // 消息类型: notification(通知)、message(消息)
    }
}

3.设置角标

设置角标数字（支持华为、vivo、荣耀、OPPO(需申请)），也可以调用5+ API plus.runtime.setBadgeNumber 动态设置角标数字进行设置。

/**
  * 设置角标数字（支持华为、vivo、荣耀、OPPO(需申请)）(同步方法无返回值)
  * @param number 角标数字
  */
UmPush.setBadgeNum(number);

调用示例：

// 设置角标数字为1
UmPush.setBadgeNum(1);

角标数字（支持华为、荣耀）递增减

/**
  * 角标数字（支持华为、荣耀）递增减(同步方法无返回值)
  * @param number 递增减数值
  */
UmPush.changeBadgeNum(number);

调用示例：

// 华为、荣耀设备的通知消息：用户点击后，角标数字会自动减1
UmPush.changeBadgeNum(1);

华为、荣耀设备的通知消息：用户点击后，角标数字会自动减1

4.推送降耗设置

/**
  * 推送降耗(同步方法无返回值)
  * @param enable true打开/false关闭
  */
UmPush.setSmartEnable(enable);

调用示例：

// 开启
UmPush.setSmartEnable(true);
// 关闭
UmPush.setSmartEnable(false);

5.标签(Tag)与别名(Alias)

标签可以给某一类人群推送消息，别名可以给指定用户推送消息。最佳实践：

• 客户端开发者在应用内调用 addTags 或者 addAlias来设置对应关系；
• 【友盟+】消息后台存储相应的关系设置；
• 在服务器端推送消息时，指定向之前设置过的别名或者标签推送。

添加标签

/**
  * 添加标签 
  * @param res  异步回调结果
  * @param tags 标签 数组字符串形式例如:["标签1","标签2"]
  */
UmPush.addTags(res,tags);

调用示例：

// 将“标签1”、“标签2”绑定至该设备
UmPush.addTags((res)=>{
    console.log(res);
},["标签1","标签2"]);

删除标签

/**
  * 删除标签,将之前添加的标签中的一个或多个删除
  * @param res  异步回调结果
  * @param tags 标签 数组字符串形式例如:["标签1","标签2"]
  */
UmPush.deleteTags(res,tags);

调用示例：

// 将“标签1”、“标签2”删除
UmPush.deleteTags((res)=>{
    console.log(res);
},["标签1","标签2"]);

获取服务器端的所有标签

/**
  * 获取服务器端的所有标签
  * @param res 异步回调结果
  */
UmPush.getTags(res);

调用示例：

// 获取服务器端的所有标签
UmPush.getTags((res)=>{
    console.log(res);
});

别名增加

/**
  * 别名增加，将某一类型的别名ID绑定至某设备，老的绑定设备信息还在，别名ID和device_token是一对多的映射关系
  * alias和alias_type两个字段的长度限制分别为128，64个字符
  * alias和alias_type的格式仅支持半角大小写字母，数字，下划线
  * 默认单个alias下同时生效的deviceToken数最多10个，pro可调整，需要绑定大量设备（>1k)的场景用tag更合适
  * 默认单个Appkey下同时生效的alias_type数最多10个
  * @param alias 别名ID
  * @param alias_type 别名类型 
  * @param res 异步回调结果
  */
UmPush.addAlias(alias,alias_type,res);

调用示例：

// 别名增加
UmPush.addAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

别名绑定

/**
  * 别名绑定，将某一类型的别名ID绑定至某设备，老的绑定设备信息被覆盖，别名ID和deviceToken是一对一的映射关系
  * alias和alias_type两个字段的长度限制分别为128，64个字符
  * alias和alias_type的格式仅支持半角大小写字母，数字，下划线
  * 默认单个alias下同时生效的deviceToken数最多10个，pro可调整，需要绑定大量设备（>1k)的场景用tag更合适
  * 默认单个Appkey下同时生效的alias_type数最多10个
  * @param alias 别名ID 
  * @param alias_type 别名类型 
  * @param res 异步回调结果
  */
UmPush.setAlias(alias,alias_type,res);

调用示例：

// 别名绑定
UmPush.setAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

移除别名

/**
  * 移除别名ID
  * @param alias 别名ID 
  * @param alias_type 别名类型 
  * @param res 异步回调结果
  */
UmPush.deleteAlias(alias,alias_type,res);

调用示例：

// 移除别名
UmPush.deleteAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

6.获取厂商Token

可通过调用API接口设置厂商Token的回调，获取厂商的Token：

/**
  * 获取厂商Token
  * @param res 异步回调结果
  */
UmPush.setThirdTokenCallback(res);

调用示例：

// 获取厂商Token
UmPush.setThirdTokenCallback((res)=>{
    console.log(res);
});
// 返回示例：
{
    "message": "success", //信息
    "code": 0,     //状态码
    "data":{
        "type":"xxx",
        "token":"xxx"
    }
}

7.设置通知免打扰时段

为避免打扰用户，默认在“23:00”到“7:00”之间收到通知消息时不响铃，不振动，不闪灯。

如果需要改变默认的静音时间，可以使用以下方法：

/**
  * 设置通知免打扰时段(同步方法无返回值)
  * @param startHour 开始---时
  * @param startMinute 开始---分
  * @param endHour 结束---时
  * @param endMinute 结束---分
  */
UmPush.setNoDisturbMode(startHour, startMinute, endHour, endMinute);

调用示例：

// 设置通知免打扰时段 例如：设置“23:00”到“7:00”之间收到通知消息时不响铃，不振动，不闪灯
UmPush.setNoDisturbMode(23, 0, 7, 0);
// 可以通过下面的设置，来关闭免打扰模式
UmPush.setNoDisturbMode(0, 0, 0, 0);

8.设置冷却时间

默认情况下，同一台设备在1分钟内收到同一个应用的多条通知时，不会重复提醒，可以通过如下方法来设置冷却时间：

/**
  * 设置冷却时间(同步方法无返回值)
  * @param seconds 单位/秒
  */
UmPush.setMuteDurationSeconds(seconds);

调用示例：

// 设置冷却时间
UmPush.setMuteDurationSeconds(seconds);

9.设置App处于前台时显示/隐藏通知

如果您的应用在前台，您可以设置不显示通知消息。默认情况下，应用在前台是显示通知的。开发者更改前台通知显示设置后，会根据更改生效。若希望前台时不显示通知，调用方法如下：

/**
  * 设置App处于前台时显示/隐藏通知
  * @param onForeground true显示/false隐藏
  */
UmPush.setNotificationOnForeground(onForeground);

调用示例：

// 设置App处于前台时显示
UmPush.setNotificationOnForeground(true);
// 隐藏(不显示)
UmPush.setNotificationOnForeground(false);

10.推送开关设置

推送默认时开启的，推送开启或者关闭可以调用以下方法：

/**
  * 推送开关设置
  *
  * @param switchFlag 开true/关false
  * @param res        异步回调结果
  */
UmPush.pushSwitch(switchFlag,res);

调用示例：

// 打开推送
UmPush.pushSwitch(true,(res)=>{
    console.log(res);
});
// 关闭推送
UmPush.pushSwitch(false,(res)=>{
    console.log(res);
});

11.自定义铃声

Android端的自定义推送渠道，由此可以实现设置推送铃音。注意Android8.0之上才可以设置推送渠道，8.0之前版本在推送json里设置铃音的方式实现自定义铃音。

插件实现原理说明

首先Android8.0以下只需要有对应的声音文件就可以进行自定义铃声的调用，而Android在8.0以上时，Android使用推送渠道的配置来进行通知的创建（可自定义铃音），所以才由此插件来设置通知渠道，从而设置铃音。

手机厂商支持

现支持小米、华为的自定义铃音。华为申请 自分类权益 后，可以通过铃声文件名称进行下发，华为自定义铃音服务端api配置 ；而小米需要在小米开发者平台的控制台配置自定义渠道名称，后端发送通知时需携带小米的自定义渠道名称。请结合友盟推送自定义声音进行服务端api接口的设置。另外，本地自建通知也可以使用本插件进行铃音设置。

配置

在项目中输入名称 nativeResources（注意大小写敏感），确定并创建目录。

继续创建“android”子目录、创建“assets”、“res”二级子目录，结构如下：

在res目录下创建raw目录，在raw目录下放置需要播放的铃声即可。

设置自定义渠道

UmPush.setCustomPushChannel(options,error);

options

error

错误信息的回调

void error(msg){
}

msg : 错误信息。

示例

UmPush.setCustomPushChannel({
                soundName: "xxx",//铃声名称，无需文件后缀
                channelId: "1",
                channelName:'测试',
                channelDesc: "渠道描述",
                enableLights: true,
                enableVibration: true,
                importance: 3,
                lockscreenVisibility: 0
            }, (errorCB) => {
                console.log(errorCB)
            }); 

删除指定渠道

UmPush.deleteChannel("1");//渠道id

IOS端

1.初始化

初始话获取devuceToken，请务必遵守合规指南在中向用户告知使用友盟SDK，确保用户同意《隐私政策》之后，再初始化友盟+SDK。参考官方合规三步走：跳转

重要：一定要在同意隐私政策之后(如果无隐私政策功能设计，也要在其他地方执行初始化，切记不能在启动中执行的代码中调用)调用，首次安装app，如果在首页或者App.vue中的onLaunch执行那么会导致获取设备deviceToken失败，并且用户在首次打开app未授权推送权限，那么也一样获取不到设备deviceToken，后续如果用户再次打开，再次执行初始化，则可以获取到设备deviceToken。ps：作者也想解决此问题，但是发现uniapp原生插件离线项目中首次安装app用户授权消息通知权限回调无论点击是或者否回调结果都是否，已经反馈uniapp官方无果，如果有大佬愿解惑，欢迎与作者交流。

/**
  * 初始化推送 
  * @param res  异步回调结果
  */
UmPush.initUmPush(res);

调用示例：

// 初始化推送 
UmPush.initUmPush((res) => {
    console.log(res);
})

2.监听消息

请在初始化方法前调用。消息后续动作：收到消息后，根据自己的逻辑处理即可

/**
  * 监听消息 
  * @param res  异步回调结果
  */
UmPush.onPushMessage(res);

调用示例：

// 监听消息
UmPush.onPushMessage((res)=>{
    console.log(res);
});

消息回调返回示例:

{
    "payload": {
        "p": 0,
        "d": "uu5itrv170044646792910", // 消息id
        "aps": {
            "alert": {
                "subtitle": "副标题", // 副标题
                "title": "标题",     // 标题
                "body": "xxx"       // 消息内容
            },
            "sound": "default"    // 铃声默认
        }
    },
    "msg_id": "uu5itrv170044646792910" //将payload中的d字段映射出来了这个是为了方便看，以payload中的参数为准
}

3.设置角标

• 该方法仅用于同步角标数字到服务器
• 若App需要显示角标，需自行使用应用运行期调用5+ API plus.runtime.setBadgeNumber 动态设置角标数字`进行设置。

/**
  * 设置角标数量，同步服务器角标计数(同步方法无返回值)
  * 1、int类型
  * 2、>=0 && <=99
  * @param number 角标数字
  */
UmPush.setBadgeNum(number);

调用示例：

UmPush.setBadgeNum(1);

4.设置是否允许SDK自动清空角标

设置是否允许SDK自动清空角标，默认自动角标清零

/**
  * 设置是否允许SDK自动清空角标(同步方法无返回值)
  * @param badgeClear 1自动清空/0不自动清空
  */
UmPush.setBadgeClear(badgeClear);

调用示例：

// 自动清空
UmPush.setBadgeClear(1);
// 不自动清空
UmPush.setBadgeClear(0);

5.标签(Tag)与别名(Alias)

添加标签

给设备打的标签

/**
  * 添加标签 
  * @param res  异步回调结果
  * @param tags 标签 数组字符串形式例如:["标签1","标签2"] 长度限制为128个字符 单个用户的tag限制1024个 tag使用半角字符，大小写敏感tag中不要出现逗号     * （,）和双竖线（||）
  */
UmPush.addTags(res,tags);

调用示例：

// 将“标签1”、“标签2”绑定至该设备
UmPush.addTags((res)=>{
    console.log(res);
},["标签1","标签2"]);

删除标签

/**
  * 删除标签,将之前添加的标签中的一个或多个删除
  * @param res  异步回调结果
  * @param tags 标签 数组字符串形式例如:["标签1","标签2"] 长度限制为128个字符 单个用户的tag限制1024个 tag使用半角字符，大小写敏感tag中不要出现逗号     * （,）和双竖线（||）
  */
UmPush.deleteTags(res,tags);

调用示例：

// 将“标签1”、“标签2”删除
UmPush.deleteTags((res)=>{
    console.log(res);
},["标签1","标签2"]);

获取服务端的所有标签

/**
  * 获取服务器端的所有标签
  * @param res 异步回调结果
  */
UmPush.getTags(res);

调用示例：

// 获取服务器端的所有标签
UmPush.getTags((res)=>{
    console.log(res);
});

别名增加

/**
  * 别名增加
  * @param alias 别名ID 长度限制为128个字符,格式仅支持半角大小写字母，数字，下划线单个name下同时生效的device_token数最多10   * 个，pro可调整，绑定多个（>1k）设备的场景用tag更合适
  * @param alias_type 别名类型 type长度限制为64个字符type的格式仅支持半角大小写字母，数字，下划线，单个appkey下同时生效的   * alias_type数最多10个
  * @param res 异步回调结果
  */
UmPush.addAlias(alias,alias_type,res);

调用示例：

// 别名增加
UmPush.addAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

别名绑定(重置别名)

/**
  * 别名绑定(重置别名)
  * @param alias 别名ID 长度限制为128个字符,格式仅支持半角大小写字母，数字，下划线单个name下同时生效的device_token数最多10   * 个，pro可调整，绑定多个（>1k）设备的场景用tag更合适
  * @param alias_type 别名类型 type长度限制为64个字符type的格式仅支持半角大小写字母，数字，下划线，单个appkey下同时生效的   * alias_type数最多10个
  * @param res 异步回调结果
  */
UmPush.setAlias(alias,alias_type,res)

调用示例：

// 别名绑定(重置别名)
UmPush.setAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

移除别名

/**
  * 移除别名
  * @param alias 别名ID
  * @param alias_type 别名类型 
  * @param res 异步回调结果
  */
UmPush.deleteAlias(alias,alias_type,res);

调用示例：

// 移除别名
UmPush.deleteAlias("testAlias","aliasType",(res)=>{
    console.log(res);
});

6.设置前台运行收到Push时弹出Alert框

前台收到通知后会有弹窗提示(不建议使用，影响体验)，官方SDK默认打开。在接受消息通知回调的时候，作者设置了关闭，如果想打开，请自行调用以下方法：

/**
  * 设置前台运行收到Push时弹出Alert框
  * @param alert 1弹框Alert框/0不弹Alert框
  */
UmPush.setAutoAlert(alert);

调用示例：

// 弹框Alert框
UmPush.setAutoAlert(1);
// 0不弹Alert框
UmPush.setAutoAlert(0);

7.自定义铃声

自定义推送声音有以下几点要求：

1. M、MA4 (IMA/ADPCM)、µLaw、aLaw这4种格式之一。
2. 后台推送必须包含sound参数，且value必须为资源名，填写参数时必须携带后缀。
3. 资源文件的声音长度小于30s,如果超过限定，会用默认声音来播放。

输入名称 nativeResources（注意大小写敏感），确定并创建目录。

继续创建“ios”子目录、创建“Resources”二级子目录，结构如下：

在“Resources”目录下放置铃声(ps:图为参考，非正式，不懂的可以参考：原生资源文件配置)

统一返回结构体

插件中对友盟推送sdk结果进行了二次封装，统一返回结构体如下：

{
    "deviceToken": "Ag1Now4kZ4If9GaK2NpsRvfNnpv_I5bBESbclOt4b6VU", //设备DeviceToken（推送标识）只有初始化方法返回
    "message": "success", //信息
    "code": 0,     //状态码详情看状态码对照表
    "data":{},     // 除初始化方法其他方法返回，当前结果为友盟SDK回调返回结果
    "remain":12    // ios标签tag操作返回该值，剩余可用的tag数
}

字段说明：

状态码对照表

同意返回结构体中code对照表：

常见问题

1.安卓是否支持FCM通道？

答：条件限制，作者未测试，反馈了友盟官方，回答的如下：