需要HBuilderX 3.5.1 及其以上版本支持

为了更好的服务欢迎： 加入uni-push2.0 交流群

uni-push有服务器API和客户端API。

客户端API 详情参考

服务端API

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

推送消息

推送目标选择

发送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_id、user_tag、device_id、push_clientid、getui_custom_tag、getui_big_data_tag、getui_alias不可多选。全为空表示向所有启动过应用的设备推送。

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

同理基于user_id向用户推送消息，需要user_id与push_clientid的映射关系，可以直接使用uni-id-pages插件内置的功能实现。如果你不使用uni-id-pages需要在App.vue调用uniCloud.onRefreshToken 监听token发生变化（即：用户登录和token续期时），调用服务端云对象的某个方法（参数：push_clientid）操作uni-id-device表，记录device_id 与 user_id（防客户端伪造，需校验token）的映射关系；完整字段包含user_id、device_id、token_expired、push_clientid、appid。同时再向opendb-device表写入或更新（存在时）：设备信息和push_clientid。

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

接口形式

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

await uniPush.sendMessage(OBJECT)

入参说明

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

注意事项

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插件 中的云对象uni-push-co
• push_clientid如果3个月未登陆会失效，所以uni-id的token过期时间不能超过3个月，否则push模块会有意想不到的故障。
• harmony 平台的api，本地调试仅 HBuilderX 4.31及其以上版本支持

getui_big_data_tag 说明

名称	类型	是否必需	默认值	描述
key	String	是	无	查询条件(phone_type 手机类型; region 省市; custom_tag 客户端标签; portrait，个推用户画像使用编码，点击下载文件portrait.data。
values	String Array	是	无	查询条件值列表，其中 手机型号使用如下参数android和ios； 省市使用编号，点击下载文件region_code.data；
opt_type	String	是	无	or(或),and(与),not(非)，values间的交并补操作

• 不同key之间是交集，同一个key之间是根据opt_type操作
• eg. 需要发送给城市在A,B,C里面，没有设置tagtest标签，手机型号为android的设备，用条件交并补功能可以实现，city(A|B|C) && !tag(tagtest) && phonetype(android)

platform 说明

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

settings 说明

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

strategy 厂商下发策略选择

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

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

实现推送铃声

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

响应体说明

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

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

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$taskid	Object	任务编号
$alias	String	设备别名
$cid	String	个推客户端id
$status	Object	推送结果 successed_offline: 离线下发(包含厂商通道下发)， successed_online: 在线下发， successed_ignore: 最近90天内不活跃设备不下发

群发返回值示例：

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

其他推送返回值示例：

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

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$taskid	Object	任务编号
$cid	String	个推客户端id
$status	Object	推送结果 successed_offline: 离线下发(包含厂商通道下发)， successed_online: 在线下发， successed_ignore: 最近90天内不活跃设备不下发

消息任务

停止任务

对正处于推送状态，或者未接收的消息停止下发（只支持批量推和群推任务）

接口形式

await uniPush.stopTaskByTaskid(taskId)

入参说明

名称	类型	是否必须	默认值	说明
taskId	String	是	无	任务id (格式RASL-MMdd_XXXXXX或RASA-MMdd_XXXXXX)

响应体说明

 {
    "errCode":0,
    "errMsg":"success"
}

返回结构说明请参考公共返回结构

查询定时任务

该接口支持在推送完定时任务之后，查看定时任务状态，定时任务是否发送成功。

接口形式

await uniPush.getTaskScheduleByTaskid(taskId)

入参说明

名称	类型	是否必须	默认值	说明
taskId	String	是	无	任务id

响应体说明

• 返回值示例

 {
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$taskid": {
            "create_time":"",
            "status":"success",
            "transmission_content":"",
            "push_time":""
        }
    }
}

• 返回参数data说明

名称	类型	描述
$taskid	Object	key: 任务编号，value: 任务数据
create_time	String	定时任务创建时间，毫秒时间戳
status	String	定时任务状态：success/failed
transmission_content	String	透传内容
push_time	String	定时任务推送时间，毫秒时间戳

删除定时任务

用来删除还未下发的任务，删除后定时任务不再触发(距离下发还有一分钟的任务，将无法删除，后续可以调用停止任务接口。)

接口形式

await uniPush.deleteTaskScheduleByTaskid(taskId)

入参说明

名称	类型	是否必须	默认值	说明
taskId	String	是	无	任务id

响应体说明

• 返回值示例

 {
    "errCode":0,
    "errMsg":"success"
}

返回结构说明请参考公共返回结构

查询消息明细

调用此接口可以查询某任务下某cid的具体实时推送路径情况

使用该接口需要申请权限，若有需要，请点击右侧“技术咨询”了解详情

接口形式

await uniPush.getTaskDetail(OBJECT)

入参说明

名称	类型	是否必须	默认值	说明
taskId	string	true	无	任务id
cid	string	true	无	cid

响应体说明

• 返回值示例

{
    "errCode":0,
    "errMsg":"success",
    "data":{
        "deatil":[
            {
                "time":"yyyy-MM-dd HH:mm:ss",
                "event":"消息请求成功"
            },
            {
                "time":"yyyy-MM-dd HH:mm:ss",
                "event":"到达客户端"
            }
        ]
    }
}

• 返回参数data说明

名称	类型	描述
detail	array	请求返回详细数据
time	String	时间，格式：yyyy-MM-dd HH:mm:ss
event	String	事件

设备别名

开发者可对设备设定别名与标签，推送时可直接根据别名、标签进行推送，方便对设备的管理。 别名是开发者根据自身需求为每个设备设定的标识，建议对不同设备设定不同别名，保证可通过别名来唯一确认某特定设备。

例子：可将用户的邮箱、昵称、手机号等设为别名，即可通过邮箱、昵称、手机号指定目标设备下发推送。

一个cid只能绑定一个别名，若已绑定过别名的cid再次绑定新别名，则前一个别名会自动解绑，并绑定新别名。

绑定别名

一个cid只能绑定一个别名，若已绑定过别名的cid再次绑定新别名，则前一个别名会自动解绑，并绑定新别名。

接口形式

await uniPush.cidBindAlias(OBJECT)

入参说明

• 参数示例

[
	{
		"cid":"",
		"alias":""
	},
	{
		"cid":"",
		"alias":""
	}
]

• 请求参数说明 数据列表，数组长度不大于1000

名称	类型	是否必须	默认值	描述
cid	String	是	无	cid，设备标识
alias	String	是	无	别名，有效的别名组成： 字母（区分大小写）、数字、下划线、汉字; 长度<40; 一个别名最多允许绑定10个cid。

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

根据cid查询别名

通过传入的cid查询对应的别名信息

接口形式

await uniPush.getAliasByCid(cid)

入参说明

名称	类型	是否必须	默认值	说明
cid	String	是	无	设备唯一标识

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "alias": "xxx"
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
alias	String	别名

根据别名查询cid

通过传入的别名查询对应的cid信息

接口形式

await uniPush.getCidByAlias(alias)

入参说明

名称	类型	是否必须	默认值	说明
alias	String	是	无	别名

响应体说明

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "cid": ["xxx","xxx"]
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
cid	String	客户端标识

批量解绑别名

批量解除别名与cid的关系

接口形式

await uniPush.unboundAlias(Array)

入参说明

• 参数示例

	[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]

• 请求参数说明

名称	类型	是否必须	默认值	描述
cid	String	是	无	客户端标识
alias	String	是	无	别名

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

解绑所有别名

解绑所有与该别名绑定的cid

接口形式

await uniPush.unboundAllAlias(alias)

入参说明

名称	类型	是否必须	默认值	说明
alias	String	是	无	设备别名

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

客户端标签

开发者可对设备设定别名与标签，推送时可直接根据别名、标签进行推送，方便对设备的管理。 标签是设备的一种属性，每个设备（通过CID来标识 ）可以打上100个标签。 例子：“喜爱足球”，“喜爱动漫”

一个设备绑定一批标签

一个设备绑定一批标签，此操作为覆盖操作，会删除历史绑定的标签；

此接口对单个cid有频控限制，每天只能修改一次，最多设置100个标签；单个标签长度最大为32字符，标签总长度最大为512个字符，申请修改请点击右侧“技术咨询”了解详情 。

接口形式

await uniPush.cidBindCustomTags(OBJECT)

入参说明

• 参数示例

{
	"cid":"xxx",
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}

• 请求参数说明

名称	类型	是否必须	默认值	说明
cid	String	是	无	设备标识
custom_tag	String Array	是	无	标签列表，标签中不能包含空格

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

一批设备绑定一个标签

一批设备绑定一个标签，此接口为增量

此接口有频次控制(每分钟最多100次，每天最多10000次)，申请修改请点击右侧“技术咨询”了解详情

接口形式

await uniPush.cidsBindCustomTag(OBJECT)

入参说明

名称	类型	是否必须	默认值	说明
cids	String Array	是	无	要修改标签属性的cid列表，数组长度不大于1000
custom_tag	String	是	无	客户端标签，标签中不能包含空格，单个标签最大长度为32字符，如果含有中文字符需要编码(UrlEncode)

• 参数示例

{
	"cids": [
	    "xxx"
	],
    "custom_tag": "xxx"
}

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

一批设备解绑一个标签

解绑设备的某个标签属性，不影响其它标签

此接口有频次控制(每分钟最多100次，每天最多10000次)，申请修改请点击右侧“技术咨询”了解详情

接口形式

await uniPush.cidsUnboundCustomTag(OBJECT)

入参说明

名称	类型	是否必须	默认值	说明
cids	String Array	是	无	要修改标签属性的cid列表，数组长度不大于1000
custom_tag	String	是	无	客户端标签，标签中不能包含空格，单个标签最大长度为32字符，如果含有中文字符需要编码(UrlEncode)

• 参数示例

{
    "cids": [
        "xxx"
    ],
	"custom_tag":"xxx"
}

响应体说明

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": "true"
    }
}

返回结构说明请参考公共返回结构

查询客户端标签

根据cid查询客户端标签列表

此接口有频次控制(每分钟最多100次，每天最多10000次)，申请修改请点击右侧“技术咨询”了解详情

接口形式

await uniPush.searchCustomTagByCid(cid)

入参说明

名称	类型	是否必须	默认值	说明
cid	Array	是	无	设备标识

响应体说明

• 返回值示例

{
    "errMsg": "success",
    "errCode": 0,
    "data": {
        "$cid": [
            "custom_tag1","custom_tag2"
        ]
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$cid	Object	key: cid，value: 标签列表，列表中只会有一个元素，多个以空格隔开

黑名单设备

黑名单设备无法收到推送消息。当使用群发全推时，有时需要调节某些设备不发，此时需要按push_clientid进行黑名单控制。

添加黑名单设备

将单个或多个设备加入黑名单，对于黑名单设备在推送过程中会被过滤掉。

接口形式

await uniPush.addCidToBlacklist(push_clientid)

入参说明

名称	类型	是否必须	默认值	说明
push_clientid	String	是	无	设备标识，多个以英文逗号隔开，一次最多传200个

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

移除黑名单设备

将单个push_clientid或多个push_clientid设备移出黑名单，对于黑名单设备在推送过程中会被过滤掉的，不会给黑名单设备推送消息

接口形式

await uniPush.removeCidInBlacklist(push_clientid)

入参说明

名称	类型	是否必须	默认值	说明
getui_	String	是	无	设备标识，多个以英文逗号隔开，一次最多传200个

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success"
}

返回结构说明请参考公共返回结构

设备信息

设备在线状态

查询你的应用在线状态

注意：该状态为：offline离线时，消息可通过：同设备下其他集成个推SDK的在线应用通道完成推送（iOS不支持，Android受限于手机rom的节点设置策略）

接口形式

await uniPush.getClientStatusByCid(push_clientid)

入参说明

名称	类型	是否必须	默认值	说明
push_clientid	String	是	无	设备标识，多个以英文逗号隔开，一次最多传1000个

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": {
            "last_login_time":"1484018265935",
            "status":"offline"
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$cid	Object	key: cid，value: 设备状态信息
last_login_time	String	毫秒时间戳
status	String	状态，online在线 offline离线

推送通道状态

查询与你的应用同设备（手机）下的所有集成了个推SDK的应用在线状态

注意：

1. 该接口返回设备在线时，仅表示存在集成了个推SDK的应用在线
2. 该接口返回设备不在线时，仅表示不存在集成了个推SDK的应用在线
3. 该接口需要开通权限，如需开通，请联系右侧技术咨询

接口形式

await uniPush.getDeviceStatusByCid(cid)

入参说明

名称	类型	是否必须	默认值	说明
cid	String	是	无	设备标识，多个以英文逗号隔开，一次最多传100个

响应体说明

• 返回值示例

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": {
            "errMsg":"success",
            "errCode": 0,
            "data": {
                "cid_status":"offline",
                "device_status":"online"
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$cid	Object	key: cid，value: 设备状态信息
cid_status	String	cid在线状态，online在线 offline离线
device_status	String	设备在线状态，online在线 offline离线

设备详细信息

查询设备的信息

接口形式

await uniPush.getClientDetailByCid(String|Array)

入参说明

名称	类型	是否必须	默认值	说明
cid	String	是	无	设备标识，多个以英文逗号隔开，一次最多传1000个

响应体说明

• 返回值示例

{
    "errCode":0,
    "errMsg":"success",
    "data":{
        "invalidCids":[
            "invalidCid1",
            "invalidCid2",
            "invalidCid3"
        ],
        "validCids":{
            "${cid1}":{
                "client_app_id":"client_app_id",
                "package_name":"com.getui.demo",
                "device_token":"device_token",
                "phone_type":1,
                "phoneModel":"vv",
                "notificationSwitch":true,
                "createTime":"2021-06-30 00:00:00",
                "loginFreq":10
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
validCids	Object Array	设备信息列表
invalidCids	String Array	无效cid列表

validCids中的${cid}

名称	类型	描述
client_app_id	String	应用id
package_name	String	包名
device_token	String	厂商token
phone_type	Number	手机系统 1-安卓 2-ios
phoneModel	String	机型
notificationSwitch	Boolean	系统通知栏开关
createTime	String	首次登录时间
loginFreq	Number	登录频次

查询设备总量

通过指定查询条件来查询满足条件的设备数量

接口形式

await uniPush.getClientCount(OBJECT)

入参说明

• 参数示例

{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"and"
        },
        {
            "key":"region",
            "values": [
                "11000000"
            ],
            "opt_type":"not"
        },
         {
            "key":"custom_tag",
            "values": [
                "tag1",
                "tag2"
            ],
            "opt_type":"or"
        }
    ]
}

• 请求参数说明

名称	类型	是否必须	默认值	描述
key	String	是	无	查询条件(phone_type 手机类型,region 省市,custom_tag 客户端标签，设置标签请见接口)
values	String Array	是	无	查询条件值列表，其中 手机型号使用如下参数android和ios； 省市使用编号，点击下载文件region_code.data；
opt_type	String	是	无	or(或),and(与),not(非)，values间的交并补操作

• 不同key之间是交集，同一个key之间是根据opt_type操作
• 需要发送给城市在A,B,C里面，没有设置tagtest标签，手机型号为android的设备，用条件交并补功能可以实现，city(A|B|C) && !tag(tagtest) && phonetype(android)

响应体说明

返回值示例

{
    "errCode": 0,
    "errMsg": "success",
    "data":{
        "user_count": 0
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
user_count	Number	符合条件的设备数量

设置应用角标(仅支持IOS)

通过cid通知个推服务器当前iOS设备的角标情况。

接口形式

await uniPush.setBadgeByCid(OBJECT)

入参说明

名称	类型	是否必须	默认值	说明
cid	String	是	无	设备标识，多个以英文逗号隔开，一次最多传200个
badge	String	是	无	设备应用icon上显示的数字 +N: 在原有badge上+N -N: 在原有badge上-N N: 直接设置badge(数字，会覆盖原有的badge值)

• 参数示例

{
	"cid":"xxx",
    "badge": "-8"
}

响应体说明

统计API

获取推送结果

查询推送数据，可查询消息可下发数、下发数，接收数、展示数、点击数等结果。支持单个taskId查询和多个taskId查询。

此接口调用，仅可以查询toList或toApp的推送结果数据；不能查询toSingle的推送结果数据。

接口形式

await uniPush.getReport(OBJECT)

入参说明

名称	类型	是否必须	默认值	说明
taskid	String	是	无	任务id，推送时返回，多个taskId以英文逗号隔开，一次最多传200个
actionIdList	String	否	无

响应体说明

• content-type:application/json;charset=utf-8

• 返回值示例

 {
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$taskid": {
            "total": {
                "msg_num":4,
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
            "actionCntMap": {
                "$actionId":2
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$taskid	Object	key: 任务编号，value: 统计数据
total	Object	总的统计数据
gt	Object	key表示厂商通道，value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。
msg_num	Number	消息可下发数
target_num	Number	消息下发数
receive_num	Number	消息接收数
display_num	Number	消息展示数
click_num	Number	消息点击数
actionCntMap	Object	自定义事件统计数据
$actionId	Number	$actionId为自定义事件id，对应的值表示对应的统计数据(由开发者打点统计)

任务组名查报表

根据任务组名查询推送结果，返回结果包括消息可下发数、下发数，接收数、展示数、点击数。

此接口调用，仅可以查询toList或toApp的推送结果数据；不能查询toSingle的推送结果数据。

接口形式

await uniPush.getReportByGroupName(group_name)

入参说明

名称	类型	是否必须	默认值	说明
group_name	String	是	无	任务组名

响应体说明

• 返回值示例

 {
    "errCode":"0",
    "errMsg":"success",
    "data": {
        "$group_name": {
            "total": {
                "msg_num":4,
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
            "ios": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$group_name	Object	key任务编号，value: 统计数据
total	Object	总的统计数据
gt	Object	key表示厂商通道，value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。
msg_num	Number	消息可下发数
target_num	Number	消息下发数
receive_num	Number	消息接收数
display_num	Number	消息展示数
click_num	Number	消息点击数

获取推送实时结果

获取推送实时结果，可查询消息下发数，接收数、展示数、点击数和消息折损详情等结果。支持单个taskId查询和多个taskId查询。

注意：该接口需要开通权限，如需开通，请联系对应的商务同学开通

接口形式

await uniPush.getReportDetailByTaskid(taskid)

入参说明

名称	类型	是否必须	默认值	说明
taskid	String	是	无	任务id，推送时返回，多个taskId以英文逗号隔开，一次最多传200个

响应体说明

• 返回值示例

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "$taskid":{
            "total":{
                "msg_num":320,
                "target_num":14,
                "receive_num":3,
                "display_num":3,
                "click_num":0
            },
            "gt":{
                "target_num":3,
                "receive_num":2,
                "display_num":2,
                "click_num":0
            },
            "apn":{
                "target_num":11,
                "receive_num":1,
                "display_num":1,
                "click_num":0
            },
            "failed_detail":{
                "rs":{
                    "gt":{
                        "12":{
                            "total":231
                        }
                    },
                    "apn":{
                        "11":{
                            "11999":1,
                            "total":1
                        }
                    }
                },
                "ts":{
                    "gt":{
                        "13":{
                            "13001":608,
                            "total":608
                        },
                        "14":{
                            "14001":3,
                            "total":3
                        }
                    }
                }
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$taskid	Object	key: 任务编号，value: 统计数据
total	Object	总的统计数据
gt	Object	key表示厂商通道，value表示该通道的统计数据。其中 gt: 个推通道; apn: APNs通道; key还可以是hw、xm、vv、mz、op。
msg_num	Number	消息可下发数
target_num	Number	消息下发数
receive_num	Number	消息接收数
display_num	Number	消息展示数
click_num	Number	消息点击数
failed_detail	Object	消息折损详情
ts	Object	请求-可下发阶段折损数据
rs	Object	可下发-下发成功阶段折损数据
sf	Object	下发成功-到达阶段折损数据
fd	Object	到达-展示阶段折损数据

• ts/rs/sf/fd 里面的各个通道下面的数据含义

折损详情分类如下，2-14是折损大类说明，大类说明下面的7001-8999是细分的折损原因，total代表各细分原因总和

名称	描述
2	参数无效
3	app鉴权信息错误
4	敏感词过滤
5	设备/应用无效（卸载）
6	推送数量超限
7	参数超限
8	无相关权限
10	关闭通知
11	其他厂商原因
12	消息有效期内离线
13	无效设备
14	其它
7001	title通知标题过长
7002	content通知内容过长
7003	url网页地址过长
7005	extraData透传内容过长
7006	payload附加消息过长
2001	参数错误
2002	title/content为空,或url非https协议
2003	无标题
2004	点击跳转目标页无效(intent)
2005	该厂商不支持纯透传模板
2999	其他原因
8001	无API推送权限/未获取到authToken
8002	系统消息开关未打开
8003	不在厂商规定时间
8999	其他原因

获取单日推送数据

调用此接口可以获取某个应用单日的推送数据(推送数据包括：下发数，接收数、展示数、点击数)(目前只支持查询非当天的数据)

接口形式

await uniPush.getReportByDate(date)

入参说明

名称	类型	是否必须	默认值	说明
date	String	是	无	日期，格式: yyyy-MM-dd

响应体说明

• 返回值示例

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$date": {
            "total": {
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
             "hw": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$date	Object	key: 日期，格式: yyyy-MM-dd，value: 统计数据
total	Object	总的统计数据
gt	Object	key表示厂商通道，value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。
target_num	Number	消息下发数
receive_num	Number	消息接收数
display_num	Number	消息展示数
click_num	Number	消息点击数

查询推送量

查询应用当日可推送量和推送余量

注意：

1. 部分厂商消息不限制推送量，所以此接口不做返回，例如 hw/xmg厂商，op的私信消息，xm的重要级别消息等等 2.vv返回的是请求量push_num，总限额total_num返回的总的到达量，所以会有请求量push_num超过总限额total_num的情况 3.该接口做了频控限制，请不要频繁调用

接口形式

await uniPush.getTodayReport()

入参说明

无

响应体说明

• 返回值示例

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "vv":{
            "special":{
                "push_num":0,
                "total_num":"10000",
                "limit":false
            },
            "general":{
                "push_num":0,
                "total_num":"10000",
                "limit":false
            },
            "grouppush":{
                "push_num":0,
                "total_num":"1000",
                "limit":false
            }
        },
        "op":{
            "general":{
                "total_num":"100000",
                "limit":false,
                "remain_num":"100000"
            }
        },
        "xm":{
            "general":{
                "total_num":20000,
                "limit":false,
                "remain_num":20000
            }
        },
        "gt":{
            "app":{
                "total_num":3000,
                "limit":false,
                "remain_num":3000
            },
            "app_with_tag":{
                "total_num":1000,
                "limit":false,
                "remain_num":1000
            },
            "list":{
                "total_num":2000000,
                "limit":false,
                "remain_num":2000000
            }
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

为了接口返回统一，所以用special和general返回表示特殊消息和普通消息

名称	类型	描述
gt	Object	个推通道
gt/app	Object	个推群推接口推送限制
gt/list	Object	个推创建消息接口限制
gt/app_with_tag	Object	个推 根据条件筛选设备推送接口推送限制
xm	Object	xm通道
xm/general	Object	xm通道 普通消息限制，channel是普通级别消息时推送量限制
op	Object	op通道
op/general	Object	op通道 公信消息限制，不带channel或公信channel时推送量限制
vv	Object	vv通道
vv/special	Object	vv通道系统类消息限制，即classification=1时推送量限制
vv/general	Object	vv通道运营类消息限制，即classification=0时推送量限制
vv/grouppush	Object	vv群推消息体配置量
total_num	long	单日可推送总量
remain_num	long	单日可推送剩余量
push_num	long	单日可推送请求量，仅vv返回该字段
limit	boolean	是否被限量,当日可推送总量使用完时，该字段更新true

获取单日设备数据接口

调用此接口可以获取某个应用单日的设备数据(设备数据包括：新增设备数，累计注册设备总数，在线峰值，日联网设备数)(目前只支持查询非当天的数据)

接口形式

await uniPush.getClientReportByDate(date)

入参说明

名称	类型	是否必须	默认值	说明
date	String	是	无	日期，格式: yyyy-MM-dd

响应体说明

• 返回值示例

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$date": {
            "accumulative_num":9,
            "register_num":2,
            "active_num":5,
            "online_num":2
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
$date	Object	key: 日期，格式: yyyy-MM-dd，value: 统计数据
accumulative_num	Number	累计注册设备数
register_num	Number	注册设备数
active_num	Number	活跃设备数
online_num	Number	在线设备数

获取24个小时在线设备数

查询当前时间一天内的在线设备数(10分钟一个点，1个小时六个点)

接口形式

await uniPush.getTodayOnlineClientReport()

入参说明

无

响应体说明

成功响应数据格式:

• content-type:application/json;charset=utf-8

• 返回值示例

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "online_statics":{
            "$date":4,
            "$date":5
        }
    }
}

返回结构说明请参考公共返回结构

• 返回参数data说明

名称	类型	描述
online_statics	Object	在线设备统计数据
$date	Number	key: 毫秒时间戳，value: 在线设备数

公共返回结构

以下参数格式为每个接口返回的数据的通用格式。

名称	类型	描述
errCode	Number	成功或失败errCode码，详细含义见返回码说明
errMsg	String	失败时返回此说明
data	Object	详见接口说明

返回码说明

HTTP errCode码说明

uni-cloud-push 扩展库的errCode码以uni-cloud-push-error-开头，如：uni-cloud-push-error-10005，以下省略为10005

errCode	错误描述	解决措施
0	成功	不涉及
1	失败	接口入参要求是 Object 格式，非 Object 格式会无法识别导致报错，建议检查一下代码
2	服务正在启动	请等待
200	成功	查看基础返回码
301	域名错误	请检查域名是否与appid机房匹配
400	参数错误	具体异常信息请参考业务返回码
401	权限相关	具体异常信息请参考业务返回码
403	套餐相关	具体异常信息请参考业务返回码
404	url错误	请检查Http路径是否正确
405	方法不支持	该接口不支持该方法请求，请查看文档确认请求方式

10000 - 权限相关

errCode	错误描述	解决措施	对应http errCode
10001	token错误/失效	调用接口重新获取token	401
10002	appId或ip在黑名单中		401
10003	每分钟鉴权频率超限	接口调用过于频繁	401
10004	没有查询消息明细的权限	可以申请权限，若有需要，请点击右侧“技术咨询”了解详情	401
10005	每分钟调用频率超限		401

20000 - 参数相关

errCode	错误描述	解决措施	对应http errCode
20001	参数不合法	请检查参数	400
22001	定时任务已经执行，无法删除		400
22002	任务无效或定时任务时间不合法		400
23001	操作tag失败		400

30000 - 套餐相关，关于套餐相关的返回码，可以针对应用特殊配置，若有需要，请点击右侧“技术咨询”了解详情。

errCode	错误描述	对应http errCode
30000	没有推送fast_custom_tag的权限	403
30001	没有修改和删除custom_tag的权限	403
30002	没有推送定时任务的权限	403
30003	app/tag 接口无权限，或tag无效	403
30004	tag每日推送总数超限(VIP用户可根据应用特殊配置)	403
30005	tag长度超限(tag长度<32)	403
30006	fast_custom_tag次数超过每日推送总数限制(VIP用户可根据应用特殊配置)	403
30007	app/all推送，推送次数超过每日推送总数限制，每日最多推送100次	403
30008	list推送次数超过每日推送总数限制，每日最多推送2000000次	403
30009	推送次数超过每日推送总数限制	403
30010	app/tag 推送次数超过每日推送总数限制，每日最多推送100次，和接口app/all共享限制	403
30011	设置tag次数超过每日次数限制	403
30012	修改和删除tag 超过每分钟频率限制，每分钟最多操作5次	403
30013	推送fast_custom_tag频率超过每分钟频率限制(VIP用户可根据应用特殊配置)	403
30014	app 推送 频率超过每分钟频率限制，每分钟最多操作5次	403
30015	list推送 频率超过每分钟频率限制	403
30016	push/tag tag个数超过限制	403
30017	没有查询单推实时报表的权限	403
30018	查询单推实时报表 频率超过每分钟频率限制	403
30019	系统繁忙，请稍后重试	403

联系
个推

微信扫一扫
随时联系个推技术支持