跳至主要內容

10 【消息推送 uni-push】

约 7729 字大约 26 分钟...

10 【消息推送 uni-push】

1.概述

  • uni-push是DCloud推出的、全端的、云端一体的统一推送服务。

    1. 客户端方面,uni-push2支持App、web、小程序。
    • App端,内置了苹果、华为、小米、OPPO、VIVO、魅族、谷歌FCM等手机厂商的系统推送和个推第三方推送
    • 小程序端,内置了socket在线推送。如需模板消息/订阅消息,另见uni-subscribemsgopen in new window
    • web端,内置了socket在线推送 (uni-push1仅支持app,且app必须包含个推原生sdk。uni-push2在app端如不需要厂商推送,只需在线推送,无需集成个推原生sdk)
    1. 服务端方面,uni-push2支持uniCloud云端一体,无需再编写复杂代码轻松完成push。 (uni-push1.0仅支持使用传统服务器开发语言如php,未和客户端有效协同,流程比uni-push2.0繁琐)
    2. uni-push还自带一个web控制台。不写代码也可以在web页面发推送。uni-push1.0的web控制台在dev.dcloud.net.cnopen in new window。uni-push2.0的web控制台是开源的,属于uni-admin插件详见open in new window
    3. 如果你的项目由于特殊原因不能通过uniCloud的云函数使用uni-push2.0,你希望直接通过调用个推服务器推送消息。在这种情况下:
    • uni-app项目,需要使用老版的 uni-push1.0open in new window 。相关密钥获取方式:登录开发者中心open in new window左侧菜单->uni-push->uni-push 2.0(支持全端推送)->消息推送->应用配置->应用信息
    • uni-app-x 项目,虽然只能使用 uni-push2.0,但支持在开发者中心open in new window左侧菜单-uni-push->uni-push 2.0(支持全端推送)-> 厂商推送设置 在顶端注意事项中,点击获取个推的MasterSecret

    请注意,直接调用个推服务器进行推送可能需要更多的配置和操作步骤,具体请参考调用个推服务器open in new window的相关文档。

2.什么是push?

push,指服务器主动向客户端发送消息的技术。无需客户端持续轮询服务器,即可获得即时数据。

轮询有很多弊端:1) 客户端应用必须实时在线;2) 手机端耗电严重;3) 服务器负载高且浪费资源

手机的通知栏、小程序的订阅消息都是一种push,由手机操作系统或微信在底层提供了push通道,屏蔽了轮询的各种弊端。你的应用可以被关闭,只要手机有网,操作系统提供的push通道即是实时在线的。

提醒:web浏览器的webnotification其实是一个本地通知栏功能,浏览器厂商没有提供push通道。

当客户端在线时,push通过socket协议实现。当客户端离线时,服务器找不到客户端,开发者无法自己实现推送,只能依托手机操作系统、小程序底层提供的离线消息推送,调用指定的手机厂商或小程序厂商的服务器接口来发送消息。

所以一个push系统需要3部分协作:开发者的业务服务器 + 专业push服务器 + 开发者的客户端应用。

其主要流程是:

  1. 开发者的业务服务器向专业push服务器发送指令,告知需要向哪些客户端发送什么样的消息
  2. 专业push服务器再向客户端发送消息
  3. 若手机应用在线,直接收到push;若不在线,手机用户在操作系统的通知栏中看到push消息,点击后呼起客户端应用,客户端代码可以接收响应获得消息;如果是小程序的话,则是在微信消息里看到订阅消息,点击后呼起小程序并拿到启动参数。

由于手机厂商众多,他们各自都有不同的推送服务,包括Apple、google(仅能在海外使用)、华为、小米、oppo、vivo、魅族,以及还有一些没有专业推送服务的中小手机品牌。他们对App后台耗电都有查杀机制,除了微信等大应用,普通应用很难常驻后台。

如果开发者把上述每个平台的客户端和服务器的SDK都对接一遍,还自己处理没有push服务的中小品牌手机,那过于困难了。所以业内有专业的推送服务厂商把各种手机厂商的通道封装成一套统一的API,如个推(属于上市公司每日互动);同时这些三方专业推送厂商还提供了高速socket通道。当应用在线时,也可以直接通过socket下发消息。否则开发者需要写很多判断代码、搭建socket服务器、处理在线时和离线时各种差异。

如下图所示: 首先开发者的uniCloud应用服务器向uni-push服务器发送push消息,然后

  • 如果客户端应用在线,客户端通过socket直接收到push在线消息;
  • 客户端应用不联网时,uni-push服务器根据客户端类型,把push消息发给某个手机厂商的push服务器或小程序的订阅消息服务器;然后厂商push通道会把这条消息发到手机的通知栏或微信的订阅消息里;手机用户点击通知栏消息或小程序订阅消息后,启动App或小程序,客户端才能收到离线消息。
image-20241229152759305
image-20241229152759305

总结下uni-push提供的功能:

  1. 一个在线的socket下行服务,无论app、小程序、web,只要在线,都可以从服务器推送消息。尤其对于uniCloud用户,这个免费socket下行服务用途很多。
  2. app平台,提供app离线时的推送,聚合了所有已知手机厂商的push通道;对于未提供push通道的小手机厂商,提供后台常驻进程接收push消息(受手机rom节电设置约束)
  3. 小程序平台,目前提供了下行socket通道,后续会整合小程序离线时的订阅消息
  4. web平台,目前提供了下行socket通道,后续会提供webnotification的封装。当标签卡在后台时(注意不是关闭时),仍然可以在屏幕上弹出通知栏。
  5. 快应用平台,目前提供了下行socket通道,后续会提供离线push的封装
  6. 一个uni-adminopen in new window插件,开源的web控制台,无需编程,可视化界面发送push消息 详见open in new window

uni-starteropen in new window里,还提供了app push权限判断、申请、开关设置,搭配使用可以大量降低开发工作量。

注意:app申请创建通知栏消息、web申请弹出通知,均会由操作系统或浏览器自动弹窗询问用户是否同意。小程序下需要手机用户主动发起订阅行为,才能送达消息。

uni-push即降低了开发成本,又提高了push送达率,还支持全平台,并且免费,是当前推送的最佳解决方案。

3.自定义基座

如果要自定义原生层,则需要走一遍iOS或Android的打包流程,由XCode或Android studio编译打包生成ipa或apk安装包。

但打包后无法方便调试,不能热重载和显示控制台日志。所以HBuilder在打包时提供了一个特殊选项,打包“自定义运行基座”。

3.1 项目设置

首先需要将uni-app的项目进行一些设置:

  1. 菜单栏工具 -> 设置 -> 运行配置,这里需要配置adb路径,以便打包之后能够正常启动app。同时需要检查该路径下是否只有一个adb版本。 image-20241229154113485image-20241229154216388
  2. 项目manifest.json -> 安卓/IOS常用其它设置,这里需要设置安卓的minSdkVersion支持CPU类型。详见安卓/IOS专题-其它配置open in new windowimage-20241229154337298

3.2 自定义基座设置

以上设置完成后就可以开始自定义基座的配置:

  1. 入口: image-20241229153741788
  2. 按照框住的部分配置即可: image-20241229154713071image-20241229154726917
  3. 点击打包即可开始创建自定义基座。
  4. 打包完成后,可以在开发者中心open in new window左侧菜单栏应用管理 -> 我的应用 -> 应用详情 -> Android云端证书中看到生成的云端证书。 image-20241229155159277

3.3 使用自定义基座启动项目

  1. 首先打开一个手机模拟器,我使用的是雷电模拟器v5.0.82
  2. 运行入口: image-20241229155313582
  3. 点击运行即可。 image-20241229155849663

4.开通 uni-push

4.1 初始化应用

  • 使用 HBuilder 账号登录 开发者中心open in new window
  • 在左侧菜单栏找到uni-push-uni-push 2.0(支持全端推送)-应用信息,点击“当前应用”选择要操作的应用。 可进入uni-push 应用开通界面。

4.2 填写应用信息

应用开通 uni-push 功能时,需要提交应用相关信息,若完成了上一章自定义基座的制作,选择Android 包名会自动带出证书相关信息。

image-20241229160026027
image-20241229160026027

4.3 项目配置 uni-push

  1. 项目manifest.json -> 安卓/IOS模块配置 -> 打包模块配置。

    注意这里需要勾选离线推送,否则后续在管理后台测试消息时可以能无法识别在线人数。 image-20241229160425610

  2. 配置完成后需要重新制作自定义基座。

5.开始使用

5.1 客户端监听推送消息

监听推送消息的代码,需要在收到推送消息之前被执行。所以应当写在应用一启动就会触发的应用生命周期open in new windowonLaunch中。

示例代码:

// 文件路径:项目根目录App.vue/uvue
export default {
    onLaunch: function() {
        console.log('App Launch')
        uni.onPushMessage((res) => {
            console.log("收到推送消息:",res) //监听推送消息
        })
    },
    onShow: function() {
        console.log('App Show')
    },
    onHide: function() {
        console.log('App Hide')
    }
}

复制代码

先跟着示例代码简单体验,详细的uni.onPushMessage API介绍:uni-app 框架详情参考open in new window,uni-app x 框架详情参考open in new window

APP端真机运行注意:

  • 如果启用了离线推送,必须:经过发行原生app云打包后,客户端才能监听到推送消息。标准HBuilder运行基座无法使用。
  • 如果Android应用进入后台后(App未销毁),点击通知消息无法拉起App,请检查设备是否有禁止后台弹出界面,路径>>设置-应用管理-测试应用-权限管理-后台弹出界面,(一般是小米、oppo、 vivo设备)。

5.2 获取客户端推送标识

假如我要给“张三”打电话,那就需要知道对方的电话标识,即电话号码是多少。 同理,要给某个客户端推送消息,也需要知道该设备的客户端推送标识。

先跟着示例代码简单体验,详细的uni.getPushClientId API介绍:uni-app 框架详情参考open in new window,uni-app x 框架详情参考open in new window 代码示例:

// uni-app客户端获取push客户端标记
uni.getPushClientId({
    success: (res) => {
        let push_clientid = res.cid
        console.log('客户端推送标识:',push_clientid)
    },
    fail(err) {
        console.log(err)
    }
})

5.3 使用开发者后台进行透传消息推送

  1. 入口:开发者中心open in new window -> uni-push -> uni-push 2.0(支持全端推送) -> 消息推送: image-20241229162744143
  2. 设置描述和内容: image-20241229163117184
  3. 发送消息: image-20241229163148724image-20241229163158121
  4. 发送成功后,可以在项目的控制看到接收到的消息内容: image-20241229163508131image-20241229163528947

5.4 创建本地通知栏消息

uni.createPushMessageopen in new window

uni.onPushMessage((res) => {
    uni.createPushMessage({
        title: '测试标题2',
        content: '测试内容2',
        payload: {
            id: '1',
            name: '管理员'
        },
    });
});

在后台推送透传消息,模拟器通知显示如下:

image-20241229165102299
image-20241229165102299

点击消息跳转到对应页面:

事件类型,"click"-从系统推送服务点击消息启动应用事件;"receive"-应用从推送服务器接收到推送消息事件。

uni.onPushMessage((res) => {
    if (res.type === 'receive') {
        uni.createPushMessage({
            title: '测试标题3',
            content: res.data.content,
            payload: res.data.payload,
        });
    } else if(res.type === 'click') {
        uni.navigateTo({
            url: '/pages/demo/demo?id=' + res.data.payload.id
        })
    }
});

6.引导用户开启手机通知

默认情况下,新安装的app的通知权限是关闭,如下图所示:

image-20250130235003158
image-20250130235003158

所以需要在打开app的时候提示让用户去打开消息权限。提示消息封装代码如下:

@/utils/setPermissions.js

/**
 * 设置手机通知权限
 */
export function setPermissions() {
    // #ifdef APP-PLUS  
    if (plus.os.name == 'Android') { // 判断是Android
        var main = plus.android.runtimeMainActivity();
        var pkName = main.getPackageName();
        var uid = main.getApplicationInfo().plusGetAttribute("uid");
        var NotificationManagerCompat = plus.android.importClass("android.support.v4.app.NotificationManagerCompat");
        //android.support.v4升级为androidx
        if (NotificationManagerCompat == null) {
            NotificationManagerCompat = plus.android.importClass("androidx.core.app.NotificationManagerCompat");
        }
        var areNotificationsEnabled = NotificationManagerCompat.from(main).areNotificationsEnabled();
        // 未开通‘允许通知’权限,则弹窗提醒开通,并点击确认后,跳转到系统设置页面进行设置  
        if (!areNotificationsEnabled) {
            uni.showModal({
                title: '通知权限开启提醒',
                content: '您还没有开启通知权限,无法接受到消息通知,请前往设置!',
                showCancel: false,
                confirmText: '去设置',
                success: function(res) {
                    if (res.confirm) {
                        var Intent = plus.android.importClass('android.content.Intent');
                        var Build = plus.android.importClass("android.os.Build");
                        //android 8.0引导  
                        if (Build.VERSION.SDK_INT >= 26) {
                            var intent = new Intent('android.settings.APP_NOTIFICATION_SETTINGS');
                            intent.putExtra('android.provider.extra.APP_PACKAGE', pkName);
                        } else if (Build.VERSION.SDK_INT >= 21) { //android 5.0-7.0  
                            var intent = new Intent('android.settings.APP_NOTIFICATION_SETTINGS');
                            intent.putExtra("app_package", pkName);
                            intent.putExtra("app_uid", uid);
                        } else { //(<21)其他--跳转到该应用管理的详情页  
                            intent.setAction(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
                            var uri = Uri.fromParts("package", mainActivity.getPackageName(), null);
                            intent.setData(uri);
                        }
                        // 跳转到该应用的系统通知设置页  
                        main.startActivity(intent);
                    }
                }
            });
        }
    } else if (plus.os.name == 'iOS') { // 判断是ISO
        var isOn = undefined;
        var types = 0;
        var app = plus.ios.invoke('UIApplication', 'sharedApplication');
        var settings = plus.ios.invoke(app, 'currentUserNotificationSettings');
        if (settings) {
            types = settings.plusGetAttribute('types');
            plus.ios.deleteObject(settings);
        } else {
            types = plus.ios.invoke(app, 'enabledRemoteNotificationTypes');
        }
        plus.ios.deleteObject(app);
        isOn = (0 != types);
        if (isOn == false) {
            uni.showModal({
                title: '通知权限开启提醒',
                content: '您还没有开启通知权限,无法接受到消息通知,请前往设置!',
                showCancel: false,
                confirmText: '去设置',
                success: function(res) {
                    if (res.confirm) {
                        var app = plus.ios.invoke('UIApplication', 'sharedApplication');
                        var setting = plus.ios.invoke('NSURL', 'URLWithString:', 'app-settings:');
                        plus.ios.invoke(app, 'openURL:', setting);
                        plus.ios.deleteObject(setting);
                        plus.ios.deleteObject(app);
                    }
                }
            });
        }
    }
    // #endif  
}

在启动的时候调用该函数即可:

App.vue

  import { setPermissions } from '@/utils/setPermissions.js';

  export default {
    onLaunch() {
       //  提示用户开启手机通知
      setPermissions();

      uni.getPushClientId({
        success(res) {
          console.log(res.cid);
        },
      });

      uni.onPushMessage(res => {
        console.log(res);

        if (res.type === 'receive') {
          uni.createPushMessage({
            content: res.data.content,
            payload: res.data.payload,
          });
        }
      });
    },
  };

效果如下:

image-20250130235727174
image-20250130235727174

7.使用uni-admin-push推送消息

7.1 初始化uni-admin项目

  1. 使用uni-app提供的uni-admin模板创建项目: image-20250131233338144
  2. 初始化云空间:
    1. 关联云空间: image-20250131233526663
    2. 上传所有云函数至云端: image-20250131233546209
    3. 初始化云数据库: image-20250131233601657
  3. 启动项目: image-20250131233753554

7.2 新增uni-push-admin插件

  1. 在dcloud插件市场搜索uni-push-admin插件安装: image-20250131234001265

  2. 上传云函数和云数据库的db schema

  3. 重启admin项目,在系统管理 -> 菜单管理 -> 待添加菜单 会出现推送管理相关菜单,添加即可: image-20250131234859056

  4. 项目的 pages.json 文件 pages 节点新增相关菜单:

    {
        "path": "uni_modules/uni-push-admin/pages/extra/extra",
        "style": {
            "navigationBarTitleText": "push-admin"
            /* #ifndef H5 */
            ,"navigationStyle": "default"
            /* #endif */
        }
    }, {
        "path": "uni_modules/uni-push-admin/pages/log/list",
        "style": {
            "navigationBarTitleText": "推送记录"
            /* #ifndef H5 */
            ,"navigationStyle": "default"
            /* #endif */
        }
    }, {
        "path": "uni_modules/uni-push-admin/pages/log/detail",
        "style": {
            "navigationBarTitleText": "推送详情",
            "navigationStyle": "default"
        }
    }, {
        "path": "uni_modules/uni-push-admin/pages/sendMessage/sendMessage",
        "style": {
            "navigationBarTitleText": "消息推送"
            /* #ifndef H5 */
            ,"navigationStyle": "default"
            /* #endif */
        }
    }
    
  5. 重启项目,展示如下: image-20250131235832939

8.使用云函数url化生成消息推送接口

8.1 服务端API

以下为uni-cloud-push扩展库的api文档;关于uni-cloud-push扩展库的详细介绍,以及如何在需要操作uni-push的云函数里,手动配置uni-cloud-push扩展库详情参考open in new window

8.1.1 推送消息

推送目标选择

发送push可以基于如下维度选择目标设备:

  • 不指定,所有启动过应用的设备
  • user_id,指定的用户id,基于uni-id账户体系
  • user_tag,指定用户标签,基于uni-id账户体系
  • device_id,指定的设备id,基于opendb表的device设备(未开通uni统计的应用,必须基于uni-id-co登录后才可使用)
  • push_clientid,个推客户端id(也会存在opendb表中)。
  • getui_alias,个推自定义客户端别名。
  • getui_custom_tag,由用户自定义的个推客户端标签。该功能需要申请相关套餐,请点击右侧“技术咨询”了解详情
  • getui_big_data_tag,个推大数据标签。

注意user_iduser_tagdevice_idpush_clientidgetui_custom_taggetui_big_data_taggetui_alias不可多选。全为空表示向所有启动过应用的设备推送。

如果用户处于未登录状态,你可以基于device_id向用户推送消息,但是推送服务器底层只识别push_clientid,需要通过查数据库获得push_clientid。而device_idpush_clientid的映射关系不由uni-push提供,而是由uni统计open in new window模块内置的功能实现。如果你不使用uni统计,则需要在应用启动时调用getPushClientIdopen in new window获取push_clientid,获取成功后(应用未在manifest中启用uni-push2.0则会获取失败)调用服务端云对象的某个方法(参数:push_clientid)执行向opendb-device表写入或更新(存在时):设备信息open in new windowpush_clientid

同理基于user_id向用户推送消息,需要user_idpush_clientid的映射关系,可以直接使用uni-id-pagesopen in new window插件内置的功能实现。如果你不使用uni-id-pages需要在App.vue调用uniCloud.onRefreshTokenopen in new window 监听token发生变化(即:用户登录和token续期时),调用服务端云对象的某个方法(参数:push_clientid)操作uni-id-device表,记录device_iduser_id(防客户端伪造,需校验token)的映射关系;完整字段包含user_iddevice_idtoken_expiredpush_clientidappid。同时再向opendb-device表写入或更新(存在时):设备信息open in new windowpush_clientid

注意: 客户端上报的信息在理论上存在被篡改可能,基于device_id向用户推送消息有被窃听的风险(营销类消息不用太关心这个)。 例如:张三使用李四的device_id+张三的push_clientid。上报数据;服务器会认为李四的push_clientid更新了,从而将李四的device_idpush_clientid的映射关系,指向张三的push_clientid;张三从而窃听到,其他人发给李四的消息。 而基于user_id或者user_tag推送消息,是基于uni-id-device表,在新增/更新操作时:会校验当前用户的user_id,不会被其他用户篡改,即没有被他人窃听消息的风险。

接口形式

可以向设定的(单个、群组、全体)设备,即时或定时推送消息。支持设置:通知栏消息内容、控制响铃,震动,浮动,闪灯;手机桌面应用右上角的角标等。

await uniPush.sendMessage(OBJECT)
入参说明
名称类型必填默认值描述平台特性
user_idString、Array基于uni-id的_id,指定接收消息的用户id。 支持多个以数组的形式指定多个用户id,如["user_id-1","user_id-2"],数组长度不大于500
user_tagString、Array指定接收消息的用户标签,基于uni-id账户体系。 支持多个以数组的形式指定多个标签,如["user_tag-1","user_tag-2"],数组长度不大于500
device_idString、Array指定接收消息的设备id,基于opendb表的device设备(未开通uni统计或基于uni-id-pages开发的应用,必须基于uni-id-co登录后才可使用)
push_clientidString、Array基于uni.getPushClientIdopen in new window获取的客户端推送标识,指定接收消息的设备。 支持多个以数组的形式指定多个设备,如["cid-1","cid-2"],数组长度不大于1000
getui_custom_tagString基于个推getui_custom_tag,指定接收消息接设备; 注:该功能需要申请相关套餐,请点击右侧“技术咨询”了解详情 。
getui_big_data_tagObject Array对指定应用的符合筛选条件的设备群发推送消息。支持定时、定速功能。详见下方getui-big-data-tag 说明open in new window
getui_aliasString、Array个推自定义客户端别名,指定消息接收者。 支持多个以数组的形式指定多个设备,如["getui_alias-1","getui_alias-2"],数组长度不大于1000
platformString、Array"ALL"指定接收消息的平台,"ALL"表示所有平台。 支持用数组枚举支持的平台,如:["web","app-ios","app-android","mp-weixin"],详情见下方platform 说明open in new window 仅通过user_iduser_tag指定消息接收者时有效
check_tokenBooleantrue校验客户端登陆状态是否有效(含token过期) 仅通过user_iduser_tag指定消息接收者时有效
titleString通知栏标题,长度小于20APP
contentString通知栏内容,长度小于50APP
payloadString、Object推送透传数据,app程序接受的数据,长度小于800字符; 注意:为了确保离线厂商通道,可以获得payload的值,请用Object格式如:{"text":"xxx"}
categoryObject消息类别,鸿蒙通道为必填项,其他通道若未进行配置,会被认定为营销类别,从而受到限量推送。 当前仅有鸿蒙、华为以及 vivo 厂商支持此项配置。 例如:{"harmony":"EXPRESS", "huawei":"EXPRESS", "vivo":"ORDER"}。 其中,harmony 与 huawei 的取值相同详情查看open in new window vivo 的取值详情查看open in new windowAndroid、harmony 注意:仅HBuilderX4.31及其以上版本支持
force_notificationBooleanfalse无论是离线推送还是在线推送,都自创建通知栏消息。HBuilderX 3.5.2 及其以上版本的客户端支持ios、android
badgeNumber、String+1设置应用右上角数字,用于提醒用户未阅读消息数量,支持在原有数字上的+、-操作; 例如:badge=+1,表示当前角标+1; badge=-1,(仅iOS支持)表示当前角标-1(角标>=0); badge=1,(仅iOS和华为EMUI版本10.0.0+支持)表示当前角标置成1。ios、android-huawei、harmony-huawei
channelObject已不推荐使用,请通过category和optionsopen in new window配置。android
request_idString请求唯一标识号,10-32位之间;如果request_id重复,会导致消息丢失
group_nameString任务组名。多个消息任务可以用同一个任务组名,后续可根据任务组名查询推送情况(长度限制100字符,且不能含有特殊符号); 仅基于user_id、push_clientid、getui_custom_tag指定消息接收者,或对应用的所有用户群发推送消息时有效。
soundString消息提醒铃声设置,常见的离线语音播报功能就是用它实现。详见下方实现推送铃声open in new windowAPP
content_availableNumber00表示普通通知消息(默认为0); 1表示静默推送(无通知栏消息),静默推送时不需要填写其他参数。 苹果官方建议1小时最多推送3条静默消息ios
open_urlstring填写该值将:强制push类型为“通知栏消息”,点击后系统浏览器将打开此链接。以http(s)://开头的有效可访问链接,华为通道必须使用https。长度小于300android
settingsObject推送条件设置,详细解释见下方settingsopen in new window说明
optionsObject实现部分厂商特定功能,包括仅部分厂商支持、不常用或厂商临时新增的功能(不依赖 uni-push,厂商文档支持的参数可直接使用)。例如:推送渠道 ID、消息分类(部分厂商未配置时可能被限量推送或静默推送,即静音且需下拉系统通知栏才可见通知内容)、通知栏富文本更多关于options的说明open in new windowAPP

注意事项

HBuilderX 4.31 内置的uni-push-cloud扩展库存在options参数丢失的问题,不能连接本地云函数调试,只能连接云端云函数才能正常使用;下个版本会修复此问题。

频次限制说明:

  • 多客户端接收消息推送API,频次限制200万次/天,申请修改请点击右侧“技术咨询”了解详情。
  • 通过getui_big_data_tag(根据条件筛选设备推送)指定消息接收者推送API,频次限制100次/天,每分钟不能超过5次(推送限制和接口执行群推共享限制),定时推送功能需要申请开通才可以使用,申请修改请点击右侧“技术咨询”了解详情。
  • 对指定应用的所有用户群发推送消息API,频次限制100次/天,每分钟不能超过5次(推送限制和接口根据条件筛选用户推送共享限制)

注意:

  • 调用一次sendMessage,最大推送设备数是500,超过将直接忽略。有超过500台以上设备接收消息的应用场景,应当分批(递归)调用,可以参考uni-push-admin插件open in new window 中的云对象uni-push-co
  • push_clientid如果3个月未登陆会失效,所以uni-id的token过期时间不能超过3个月,否则push模块会有意想不到的故障。
  • harmony 平台的api,本地调试仅 HBuilderX 4.31及其以上版本支持

getui_big_data_tag 说明

名称类型是否必需默认值描述
keyString查询条件(phone_type 手机类型; region 省市; custom_tag 客户端标签; portrait,个推用户画像使用编码,点击下载文件portrait.dataopen in new window
valuesString Array查询条件值列表,其中 手机型号使用如下参数androidios省市使用编号,点击下载文件region_code.dataopen in new window
opt_typeStringor(或),and(与),not(非),values间的交并补操作
  • 不同key之间是交集,同一个key之间是根据opt_type操作
  • eg. 需要发送给城市在A,B,C里面,没有设置tagtest标签,手机型号为android的设备,用条件交并补功能可以实现,city(A|B|C) && !tag(tagtest) && phonetype(android)

platform 说明

解释
app-iosiOS App
app-androidAndroid App
web网页
mp-weixin微信小程序
mp-alipay支付宝小程序
mp-baidu百度小程序
mp-toutiao抖音小程序
mp-lark飞书小程序
mp-qqQQ小程序
mp-kuaishou快手小程序
mp-jd京东小程序
mp-360360小程序
quickapp-webview快应用通用(包含联盟、华为)
quickapp-webview-union快应用联盟
quickapp-webview-huawei快应用华为

settings 说明

名称类型必填默认值描述
ttlNumber1小时消息离线时间设置,单位毫秒,-1表示不设离线,-1 ~ 3 * 24 * 3600 * 1000(3天)之间
strategyObject厂商通道策略,详细内容见strategy
speedNumber0定速推送,例如100,个推控制下发速度在100条/秒左右,0表示不限速
schedule_timeNumber设置定时推送时间(仅向所有启动过应用的设备群发时有效),必须是7天内的时间,格式:毫秒时间戳,此功能需要单独申请开通,如需开通请点击右侧“技术咨询”了解详情

strategy 厂商下发策略选择

注意此功能需要单独申请开通,若有需要,请点击右侧“技术咨询”了解详情

名称类型必填默认值描述
defaultNumber1默认所有通道的策略选择1-4 1: 表示该消息在设备在线时推送个推通道,设备离线时推送厂商通道; 2: 表示该消息只通过厂商通道策略下发,不考虑设备是否在线; 3: 表示该消息只通过个推通道下发,不考虑设备是否在线; 4: 表示该消息优先从厂商通道下发,若消息内容在厂商通道代发失败后会从个推通道下发。 其中名称可填写: ios、st、hw、xm、vv、mz、op,如有疑问请点击右侧“技术咨询”了解详情。
iosNumberios通道策略1-4,表示含义同上,要推送ios通道,需要在个推开发者中心上传ios证书,建议填写2或4,否则可能会有消息不展示的问题
stNumber通道策略1-4,表示含义同上,需要开通st厂商使用该通道推送消息
...Number通道策略1-4,表示含义同上

实现推送铃声

  1. 本功能App客户端依赖uni原生插件自定义推送铃声和渠道open in new window,注意需要打包后生效。铃声文件建议iOS和Android铃声使用一致的文件名称,直接填写文件名,不含扩展名;如:pushsound.caf或pushsound.mp3,直接填写pushsound即可。
  2. Android平台需要在options参数中根据厂商规范配置相关参数,详情参考options示例open in new window

响应体说明

多个别名推送返回值示例:

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "$taskid":{
            "$alias1":{
                "$cid1":"$status",
                "$cid2":"$status"
            },
            "$alias2":{
                "$cid3":"$status",
                "$cid4":"$status"
            }
        }
    }
}

返回结构说明请参考公共返回结构open in new window

  • 返回参数data说明
名称类型描述
$taskidObject任务编号
$aliasString设备别名
$cidString个推客户端id
$statusObject推送结果 successed_offline: 离线下发(包含厂商通道下发), successed_online: 在线下发, successed_ignore: 最近90天内不活跃设备不下发

群发返回值示例:

{
    "errCode": 0,
        "errMsg": "",
            "data": {
                "$taskid": "RASA_123_12469008ac33dd02815014631c00000f"
            }
}

其他推送返回值示例:

{
    "errCode": 0,
        "errMsg": "",
            "data": {
                "$taskid": {
                    "$cid":"$status"
                }
            }
}

返回结构说明请参考公共返回结构open in new window

  • 返回参数data说明
名称类型描述
$taskidObject任务编号
$cidString个推客户端id
$statusObject推送结果 successed_offline: 离线下发(包含厂商通道下发), successed_online: 在线下发, successed_ignore: 最近90天内不活跃设备不下发
实操说明
  1. 首先新建一个云对象,并且添加公共依赖uni-cloud-pushimage-20250202193608885

  2. 在云对象中写法如下:

    // 云对象教程: https://uniapp.dcloud.net.cn/uniCloud/cloud-obj
    // jsdoc语法提示教程:https://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/129
    const uniPush = uniCloud.getPushManager({
        appId: "__UNI__"
    }) //注意这里需要传入你的应用appId
    
    module.exports = {
        _before: function() { // 通用预处理器
    
        },
        async sendMessage() {
            const httpInfo = this.getHttpInfo();
            console.log('请求体内容 ===>', httpInfo.body)
            return await uniPush.sendMessage(JSON.parse(httpInfo.body));
        },
    }
    
  3. 然后在开发者后台开启云函数url化: image-20250202193800112

  4. 使用接口调试工具调用接口: image-20250202201659190

已到达文章底部,欢迎留言、表情互动~
  • 赞一个
    0
    赞一个
  • 支持下
    0
    支持下
  • 有点酷
    0
    有点酷
  • 啥玩意
    0
    啥玩意
  • 看不懂
    0
    看不懂
评论
  • 按正序
  • 按倒序
  • 按热度
Powered by Waline v2.15.8