api.md 52.4 KB
Newer Older
DCloud_JSON's avatar
DCloud_JSON 已提交
1
# 开发文档
DCloud_JSON's avatar
DCloud_JSON 已提交
2

DCloud_JSON's avatar
DCloud_JSON 已提交
3
`uni-push`有服务器API和客户端API。
DCloud_JSON's avatar
DCloud_JSON 已提交
4

DCloud_JSON's avatar
DCloud_JSON 已提交
5
## 客户端API
DCloud_JSON's avatar
DCloud_JSON 已提交
6

DCloud_JSON's avatar
DCloud_JSON 已提交
7 8 9 10 11 12 13 14 15 16 17 18 19
### getPushClientId()
获取客户端唯一的推送标识,注意这是一个异步的方法
示例代码:
```js 
	uni.getPushClientId({
		success: (res) => {
			console.log(res.cid);
		},
		fail(err) {
			console.log(err)
		}
	})
```
DCloud_JSON's avatar
DCloud_JSON 已提交
20

DCloud_JSON's avatar
DCloud_JSON 已提交
21 22 23
### onPushMessage([callback,eventName])
启动监听推送消息事件
代码示例:
DCloud_JSON's avatar
DCloud_JSON 已提交
24 25
```js 
uni.onPushMessage((res)=>{
DCloud_JSON's avatar
DCloud_JSON 已提交
26
	console.log(res)
DCloud_JSON's avatar
DCloud_JSON 已提交
27 28
})
```
DCloud_JSON's avatar
DCloud_JSON 已提交
29 30 31 32 33
#### 回调参数说明
|名称	|类型	|描述	|
|--		|--		|--		|
|type	|String	| 事件类型,"click"-从系统推送服务点击消息启动应用事件;"receive"-应用从推送服务器接收到推送消息事件。|
|data	|String、Object|消息内容|
DCloud_JSON's avatar
DCloud_JSON 已提交
34

DCloud_JSON's avatar
DCloud_JSON 已提交
35 36 37
### offPushMessage([eventName])
关闭推送消息监听事件
示例代码:
38
```js
DCloud_JSON's avatar
DCloud_JSON 已提交
39 40
let eventName = (res)=>{
	console.log(res)
DCloud_JSON's avatar
DCloud_JSON 已提交
41
}
DCloud_JSON's avatar
DCloud_JSON 已提交
42 43 44 45
//启动推送事件监听
uni.onPushMessage(eventName);
//关闭推送事件监听
uni.offPushMessage(eventName);
DCloud_JSON's avatar
DCloud_JSON 已提交
46
```
DCloud_JSON's avatar
DCloud_JSON 已提交
47 48 49
#### Tips
- 如果uni.offPushMessage没有传入参数,则移除App级别的所有事件监听器;
- 如果只提供了事件名(eventName),则移除该事件名对应的所有监听器;
DCloud_JSON's avatar
DCloud_JSON 已提交
50

DCloud_JSON's avatar
DCloud_JSON 已提交
51
## 服务端Api @uni-cloud-push
DCloud_JSON's avatar
DCloud_JSON 已提交
52

DCloud_JSON's avatar
DCloud_JSON 已提交
53 54 55 56 57
### 推送目标选择
发送push可以基于如下维度选择目标设备:
- 不指定,所有启动过应用的设备
- user_id,指定的用户id,基于uni-id账户体系
- user_tag,指定标签的用户,基于uni-id账户体系
DCloud_JSON's avatar
DCloud_JSON 已提交
58
- device_id,指定的设备id,基于opendb表的device设备(未开通uni统计的应用,必须登录后才可使用)
DCloud_JSON's avatar
DCloud_JSON 已提交
59 60 61 62 63
- push_clientid,个推客户端id。其实也会存在opendb表中。
- getui_custom_tag,个推自定义客户端标签。由用户自定义
- getui_big_data_tag,个推大数据标签。使用此功能,需开通个推·用户画像产品,请联系个推商务咨询
- getui_alias,个推自定义客户端别名。使用此功能,需开通个推·用户画像产品,请联系个推商务咨询

DCloud_JSON's avatar
DCloud_JSON 已提交
64
**注意**`user_id``user_tag``device_id``push_clientid``getui_custom_tag``getui_big_data_tag``getui_alias`不可多选。全为空表示向所有启动过应用的设备推送。
65

DCloud_JSON's avatar
DCloud_JSON 已提交
66
#### 接口形式
DCloud_JSON's avatar
DCloud_JSON 已提交
67
可以向设定的(单个、群组、全体)用户,即时或定时推送消息。支持设置:通知栏消息内容、控制响铃,震动,浮动,闪灯;手机桌面应用右上角的角标等。
DCloud_JSON's avatar
DCloud_JSON 已提交
68 69 70
```js 
await uniPush.sendMessage(OBJECT)
```
DCloud_JSON's avatar
DCloud_JSON 已提交
71
#### sendMessage参数说明    
DCloud_JSON's avatar
DCloud_JSON 已提交
72 73 74
|名称|类型|必填|默认值|描述|平台特性|
|--|--|--|--|--|--|
|user_id|String、Array|否|无|基于uni-id的_id,指定消息接收者。支持多个以数组的形式列举,长度不超过100。| |
DCloud_JSON's avatar
DCloud_JSON 已提交
75 76
|user_tag|String、Array|否|无|指定标签的用户,基于uni-id账户体系| |
|device_id|String、Array|否|无|指定的设备id,基于opendb表的device设备(未开通uni统计的应用,必须登录后才可使用)| |
DCloud_JSON's avatar
DCloud_JSON 已提交
77
|push_clientid|String、Array|否|无|基于uni.getPushCid获取的客户端推送标识,指定消息接收者。</br>支持多个以数组的形式指定多个设备,如["cid-1","cid-2"],数组长度不大于1000| |
DCloud_JSON's avatar
DCloud_JSON 已提交
78 79
|getui_custom_tag|String|否|无|基于个推`getui_custom_tag`,指定消息接收者;</br>注:该功能需要申请相关套餐,请点击右侧“技术咨询”了解详情 。| |
|getui_big_data_tag|Object Array|否|无|对指定应用的符合筛选条件的用户群发推送消息。支持定时、定速功能。详见下方getui_big_data_tag说明| |
DCloud_JSON's avatar
DCloud_JSON 已提交
80
|getui_alias|String、Array|否|无|基于用户别名,指定消息接收者。</br>支持多个以数组的形式指定多个设备,如["getui_alias-1","getui_alias-2"],数组长度不大于1000| |
DCloud_JSON's avatar
DCloud_JSON 已提交
81 82
|platform|String、Array|否|"ALL"|指定接收消息的平台,"ALL"表示所有平台。支持用数组枚举支持的平台,如:["app"、"h5"、"mp_weixin"]</br>使用`push_clientid``getui_custom_tag`时无效|
|check_token|Boolean|否|true|校验客户端登陆状态是否有效(含token过期)</br>仅用user_id指定消息接收者时有效| |
DCloud_JSON's avatar
DCloud_JSON 已提交
83 84 85
|title|String|是|无|通知栏标题,长度小于20|APP|
|content|String|是|无|通知栏内容,长度小于50|APP|
|payload|String、Objcet|是|无|推送透传数据,app程序接受的数据,长度小于800| |
DCloud_JSON's avatar
DCloud_JSON 已提交
86
|badge|Number、String|否|无|设置应用右上角数字,用于提醒用户未阅读消息数量,支持在原有数字上的+、-操作;</br>例如:badge=+1,表示当前角标+1;</br>badge=-1,(仅iOS支持)表示当前角标-1(角标>=0);</br>badge=1,(仅iOS和华为EMUI版本10.0.0+支持)表示当前角标置成1。| ios、android-华为|
DCloud_JSON's avatar
DCloud_JSON 已提交
87
|channel|Object|否|无|消息渠道设置,避免被限量推送,需要在各家发邮件申请,详情下方[channel说明](#channel 说明)| android|
DCloud_JSON's avatar
DCloud_JSON 已提交
88
|request_id|String|是|无|请求唯一标识号,10-32位之间;如果`request_id`重复,会导致消息丢失||
DCloud_JSON's avatar
DCloud_JSON 已提交
89
|group_name|String|否|无|任务组名。多个消息任务可以用同一个任务组名,后续可根据任务组名查询推送情况(长度限制100字符,且不能含有特殊符号);</br>仅基于user_id、cid、tag指定消息接收者,或对应用的所有用户群发推送消息时有效。||
DCloud_JSON's avatar
DCloud_JSON 已提交
90 91
|sound|String|否|无|消息提醒铃声设置。android需要设置channel生效,详见下方[铃声设置注意](#铃声设置注意)</br>如果铃声文件未找到,响铃为系统默认铃声。</br>铃声文件需要使用uni原生插件[点此打开](https://ext.dcloud.net.cn/plugin?id=690)打包后生效。</br>建议iOS和Android铃声使用一致的文件名称。直接填写文件名,不含扩展名;如:pushsound.caf或pushsound.mp3,直接填写pushsound即可。|
|content_available|Number|否|0|0表示普通通知消息(默认为0);</br>1表示静默推送(无通知栏消息),静默推送时不需要填写其他参数。</br>苹果官方建议1小时最多推送3条静默消息|ios |
DCloud_JSON's avatar
DCloud_JSON 已提交
92
|open_url|string|否|无|填写该值将:强制push类型为“通知栏消息”,点击后系统浏览器将打开此链接。以http(s)://开头的有效可访问链接,华为通道必须使用https。长度小于300|android|
DCloud_JSON's avatar
DCloud_JSON 已提交
93 94
|settings|Object|否|无|推送条件设置,详细解释见下方settings说明||
|option|Object|否|无|其他配置,[更多关于option的说明](/uniCloud/uni-push/options)||
DCloud_JSON's avatar
DCloud_JSON 已提交
95 96 97

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

DCloud_JSON's avatar
DCloud_JSON 已提交
101 102 103
注意:调用一次sendMessage,最大推送设备数是500,超过将直接忽略。有超过500台以上设备接收消息的应用场景,应当调用内置在[uni-push-admin插件](https://ext.dcloud.net.cn/plugin?name=uni-push-admin) 中的云对象uni-push-co,调用参数与本api一致

##### getui_big_data_tag 说明
DCloud_JSON's avatar
DCloud_JSON 已提交
104 105
|名称|类型|是否必需|默认值|描述|
|--|--|--|--|--|
DCloud_JSON's avatar
DCloud_JSON 已提交
106
|key|String|是|无|查询条件(phone_type 手机类型; region 省市; getui_custom_tag 客户端标签; portrait,个推用户画像使用编码,[点击下载文件portrait.data](https://docs.getui.com/files/portrait.data)。|
DCloud_JSON's avatar
DCloud_JSON 已提交
107 108 109 110 111 112 113 114 115 116
|values|String Array| 是| 无|查询条件值列表,其中<br>**手机型号**使用如下参数`android``ios`<br>**省市**使用编号,[点击下载文件region_code.data](https://docs.getui.com/files/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)

##### settings 说明
|名称|类型|必填|默认值|描述|
|--|--|--|--|--|
|ttl|Number|否|1小时|消息离线时间设置,单位毫秒,-1表示不设离线,-1 ~ 3 * 24 * 3600 * 1000(3天)之间|
DCloud_JSON's avatar
DCloud_JSON 已提交
117
|strategy|Object|否|{"strategy":{"default":1}}|厂商通道策略,详细内容见strategy|
DCloud_JSON's avatar
DCloud_JSON 已提交
118 119 120 121 122 123 124 125 126 127 128
|speed|Number|否|0|定速推送,例如100,个推控制下发速度在100条/秒左右,0表示不限速|
|schedule_time|Number|否|无|定时推送时间,格式:毫秒时间戳|

##### strategy 厂商下发策略选择
|名称|类型|必填|默认值|描述|
|--|--|--|--|--|
|default|Number|否|1|默认所有通道的策略选择1-4 <br/>1: 表示该消息在用户在线时推送个推通道,用户离线时推送厂商通道;<br/>2: 表示该消息只通过厂商通道策略下发,不考虑用户是否在线;<br/>3: 表示该消息只通过个推通道下发,不考虑用户是否在线;<br/>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,表示含义同上|

DCloud_JSON's avatar
DCloud_JSON 已提交
129
##### channel 说明
DCloud_JSON's avatar
DCloud_JSON 已提交
130 131 132 133 134 135 136
|名称|类型|必填|默认值|描述|
|--|--|--|--|--|
|HW|string|否|无|需要先向华为侧发邮件申请权限参见[华为消息分类申请](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835)。|
|XM|string|否|无|小米推送的消息通道分为“普通消息”(默认)和“重要消息”两类,默认下发普通消息。普通消息单日可推送数量有限制,重要消息不限。重要消息申请具体请参考: [小米推送消息分类新规](https://dev.mi.com/console/doc/detail?pId=2422)|
|OP|string|否|无|需要联系客服开通;OPush平台上所有通道分为“公信”(默认)、“私信”两类,默认下发公信消息。公信消息单日可推送数量有限制,私信消息不限(仅限单个用户)。私信消息申请请参见(OPPO官方文档)[通道升级公测邀请](https://open.oppomobile.com/wiki/doc#id=11096)。|
|VO|string|否|无| 0代表运营消息,1代表系统消息;vivo消息分类功能将推送消息类型分为运营消息和系统消息,默认下发运营消息。运营消息单用户单应用单日接收条数上限为5条,系统消息不限。系统消息功能不用申请,可以直接使用,如特殊情况需额外提升系统消息量级,请参见(vivo官方文档)[推送消息分类功能说明](https://dev.vivo.com.cn/documentCenter/doc/359)。|

DCloud_JSON's avatar
DCloud_JSON 已提交
137 138 139
##### 铃声设置注意
1. 华为通道须 [申请自分类权益](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835#section3699155822013)
2. 小米通道需:申请重要级别消息Channel —— 申请其他个性化重要级别消息Channel,并设置自定义铃声前端路径格式:`android.resource://你的APP应用包名/raw/铃声文件名`,例如:`android.resource://io.dcloud.UniPush2/raw/pushsound`(路径不需要带音频后缀名)如图
DCloud_JSON's avatar
DCloud_JSON 已提交
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
![](https://docs.getui.com/img/img_getui_server_rest_v2_third_party_1.png)

#### 响应体说明
多个别名推送返回值示例:
```js
{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "$taskid":{
            "$alias1":{
                "$cid1":"$status",
                "$cid2":"$status"
            },
            "$alias2":{
                "$cid3":"$status",
                "$cid4":"$status"
            }
        }
    }
}
```
>返回结构说明请参考[公共返回结构](#公共返回结构)
* 返回参数`data`说明
DCloud_JSON's avatar
DCloud_JSON 已提交
164

DCloud_JSON's avatar
DCloud_JSON 已提交
165 166
| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
167
| $taskid | Object | 任务编号 |
DCloud_JSON's avatar
DCloud_JSON 已提交
168 169
| $alias | String |设备别名|
| $cid | String |App的用户唯一标识|
DCloud_JSON's avatar
DCloud_JSON 已提交
170
| $status | Object |推送结果 <br>successed_offline: 离线下发(包含厂商通道下发),<br>successed_online: 在线下发,<br>successed_ignore: 最近90天内不活跃用户不下发|
DCloud_JSON's avatar
DCloud_JSON 已提交
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198

群发返回值示例:
```js
{
	"errCode": 0,
	"errMsg": "",
	"data": {
		"$taskid": "RASA_123_12469008ac33dd02815014631c00000f"
	}
}
```


其他推送返回值示例:
```js
{
	"errCode": 0,
	"errMsg": "",
	"data": {
		"$taskid": {
			"$cid":"$status"
		}
	}
}
```

>返回结构说明请参考[公共返回结构](#公共返回结构)
* 返回参数`data`说明
DCloud_JSON's avatar
DCloud_JSON 已提交
199

DCloud_JSON's avatar
DCloud_JSON 已提交
200 201
| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
202
| $taskid | Object | 任务编号 |
DCloud_JSON's avatar
DCloud_JSON 已提交
203
| $cid | String |App的用户唯一标识|
DCloud_JSON's avatar
DCloud_JSON 已提交
204
| $status | Object |推送结果 <br>successed_offline: 离线下发(包含厂商通道下发),<br>successed_online: 在线下发,<br>successed_ignore: 最近90天内不活跃用户不下发|
DCloud_JSON's avatar
DCloud_JSON 已提交
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259

### 消息任务
#### 停止任务
对正处于推送状态,或者未接收的消息停止下发(只支持批量推和群推任务)
##### 接口形式
```js 
await push.stopTaskByTaskid(taskId)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| taskId | String | 是 | 无 | 任务id (格式RASL-MMdd_XXXXXX或RASA-MMdd_XXXXXX)|

##### 响应体说明
```js
 {
    "errCode":0, 
    "errMsg":"success"
}
```
> 返回结构说明请参考[公共返回结构](#公共返回结构)


#### 查询定时任务
该接口支持在推送完定时任务之后,查看定时任务状态,定时任务是否发送成功。
##### 接口形式
```js 
await push.getTaskScheduleByTaskid(taskId)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| taskId | String | 是 | 无 | 任务id|

##### 响应体说明
* 返回值示例

```js
 {
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$taskid": {
            "create_time":"",
            "status":"success",
            "transmission_content":"",
            "push_time":""
        }
    }
}
```
* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
260
|$taskid|Object|key: 任务编号,value: 任务数据|
DCloud_JSON's avatar
DCloud_JSON 已提交
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
|create_time|String|定时任务创建时间,毫秒时间戳|
|status|String|定时任务状态:success/failed|
|transmission_content|String|透传内容|
|push_time|String|定时任务推送时间,毫秒时间戳|


#### 删除定时任务
用来删除还未下发的任务,删除后定时任务不再触发(距离下发还有一分钟的任务,将无法删除,后续可以调用停止任务接口。)
##### 接口形式
```js 
await push.deleteTaskScheduleByTaskid(taskId)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| taskId | String | 是 | 无 | 任务id|

##### 响应体说明
* 返回值示例

```js
 {
    "errCode":0,
    "errMsg":"success"
}
```
> 返回结构说明请参考[公共返回结构](#公共返回结构)


#### 查询消息明细
调用此接口可以查询某任务下某cid的具体实时推送路径情况
>使用该接口需要申请权限,若有需要,请点击右侧“技术咨询”了解详情
##### 接口形式
```js 
await push.getTaskDetail(OBJECT)
```
##### 入参说明
| 名称         |  类型   |是否必须      |    默认值|说明      |  
| ------------ | ----------- |-----------|---|--------|
|taskId         |string | true      |      无|任务id  |         
|cid         |string |   true      |      无|cid   |

##### 响应体说明
* 返回值示例

```js
{
    "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再次绑定新别名,则前一个别名会自动解绑,并绑定新别名。
##### 接口形式
```js 
await push.cidBindAlias(OBJECT)
```
##### 入参说明
* 参数示例

```js
[
	{
		"cid":"",
DCloud_JSON's avatar
DCloud_JSON 已提交
353
		"alias":""
DCloud_JSON's avatar
DCloud_JSON 已提交
354 355 356
	},
	{
		"cid":"",
DCloud_JSON's avatar
DCloud_JSON 已提交
357
		"alias":""
DCloud_JSON's avatar
DCloud_JSON 已提交
358 359 360 361 362 363
	}
]
```

* 请求参数说明
数据列表,数组长度不大于1000
DCloud_JSON's avatar
DCloud_JSON 已提交
364

DCloud_JSON's avatar
DCloud_JSON 已提交
365 366 367
| 名称        | 类型          | 是否必须   | 默认值  | 描述  |
| ---------  | ------------- | ---- | ---- | -------- |
| cid |String|是|无| cid,用户标识|
DCloud_JSON's avatar
DCloud_JSON 已提交
368
| alias |String|是|无|别名,有效的别名组成:<br>字母(区分大小写)、数字、下划线、汉字;<br>长度<40;<br>一个别名最多允许绑定10个cid。|
DCloud_JSON's avatar
DCloud_JSON 已提交
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400

##### 响应体说明
* 返回值示例

```js
{
    "errCode": 0,
    "errMsg": "success"
}
```
> 返回结构说明请参考[公共返回结构](#公共返回结构)


#### 根据cid查询别名
通过传入的cid查询对应的别名信息
##### 接口形式
```js 
await push.getAliasByCid(cid)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | String | 是 | 无 | 用户唯一标识 |

##### 响应体说明
* 返回值示例

```js
{
    "errCode": 0,
    "errMsg": "success",
    "data": {
DCloud_JSON's avatar
DCloud_JSON 已提交
401
        "alias": "xxx"
DCloud_JSON's avatar
DCloud_JSON 已提交
402 403 404 405 406 407 408 409 410 411
    }
}
```

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
412
| alias | String | 别名 |
DCloud_JSON's avatar
DCloud_JSON 已提交
413 414 415 416 417 418


#### 根据别名查询cid
通过传入的别名查询对应的cid信息
##### 接口形式
```js 
DCloud_JSON's avatar
DCloud_JSON 已提交
419
await push.getCidByAlias(alias)
DCloud_JSON's avatar
DCloud_JSON 已提交
420 421 422 423
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
DCloud_JSON's avatar
DCloud_JSON 已提交
424
| alias | String | 是 | 无 | 别名 |
DCloud_JSON's avatar
DCloud_JSON 已提交
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458

##### 响应体说明
```js
{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "cid": ["xxx","xxx"]
    }
}
```

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

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


#### 批量解绑别名
批量解除别名与cid的关系
##### 接口形式
```js 
await push.unboundAlias(Array)
```
##### 入参说明
* 参数示例

```js
	[
        {
            "cid":"",
DCloud_JSON's avatar
DCloud_JSON 已提交
459
            "alias":""
DCloud_JSON's avatar
DCloud_JSON 已提交
460 461 462
        },
        {
            "cid":"",
DCloud_JSON's avatar
DCloud_JSON 已提交
463
            "alias":""
DCloud_JSON's avatar
DCloud_JSON 已提交
464 465 466 467 468
        }
    ]
```

* 请求参数说明
DCloud_JSON's avatar
DCloud_JSON 已提交
469

DCloud_JSON's avatar
DCloud_JSON 已提交
470 471 472
| 名称        | 类型          | 是否必须   | 默认值  | 描述  |
| ---------  | ------------- | ---- | ---- | -------- |
| cid |String|是|无| 客户端标识|
DCloud_JSON's avatar
DCloud_JSON 已提交
473
| alias |String|是|无|别名|
DCloud_JSON's avatar
DCloud_JSON 已提交
474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)


#### 解绑所有别名
解绑所有与该别名绑定的cid
##### 接口形式
```js 
DCloud_JSON's avatar
DCloud_JSON 已提交
492
await push.unboundAllAlias(alias)
DCloud_JSON's avatar
DCloud_JSON 已提交
493 494 495 496
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
DCloud_JSON's avatar
DCloud_JSON 已提交
497
| alias | String | 是 | 无 | 用户别名 |
DCloud_JSON's avatar
DCloud_JSON 已提交
498 499 500 501 502 503 504 505 506 507 508 509 510 511

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)


DCloud_JSON's avatar
DCloud_JSON 已提交
512
### 客户端标签
DCloud_JSON's avatar
DCloud_JSON 已提交
513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
开发者可对用户设定别名与标签,推送时可直接根据别名、标签进行推送,方便对用户的管理。
标签是用户的一种属性,每个用户(通过CID来标识 )可以打上100个标签。
例子:“喜爱足球”,“喜爱动漫”
#### 一个用户绑定一批标签
一个用户绑定一批标签,此操作为覆盖操作,会删除历史绑定的标签;
> 此接口对单个cid有频控限制,每天只能修改一次,最多设置100个标签;单个标签长度最大为32字符,标签总长度最大为512个字符,申请修改请点击右侧“技术咨询”了解详情 。
##### 接口形式
```js 
await push.cidBindCustomTags(OBJECT)
```
##### 入参说明
* 参数示例

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

* 请求参数说明
DCloud_JSON's avatar
DCloud_JSON 已提交
537

DCloud_JSON's avatar
DCloud_JSON 已提交
538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | String | 是 | 无 | 用户标识 |
| custom_tag |String Array|是|无|标签列表,标签中不能包含空格|

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)



#### 一批用户绑定一个标签
一批用户绑定一个标签,此接口为增量
> 此接口有频次控制(每分钟最多100次,每天最多10000次),申请修改请点击右侧“技术咨询”了解详情
##### 接口形式
```js 
await push.cidsBindCustomTag(OBJECT)
```

##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | String Array | 是      | 无    | 要修改标签属性的cid列表,数组长度不大于1000 |
DCloud_JSON's avatar
DCloud_JSON 已提交
569
| custom_tag | String | 是 | 无 | 客户端标签,标签中不能包含空格,单个标签最大长度为32字符,如果含有中文字符需要编码(UrlEncode) |
DCloud_JSON's avatar
DCloud_JSON 已提交
570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604

* 参数示例

```js
{
	"cid": [
	    "xxx"
	],
    "custom_tag": "xxx"
}
```

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

#### 一批用户解绑一个标签
解绑用户的某个标签属性,不影响其它标签
>此接口有频次控制(每分钟最多100次,每天最多10000次),申请修改请点击右侧“技术咨询”了解详情
##### 接口形式
```js 
await push.cidsUnboundCustomTag(OBJECT)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | String Array | 是      | 无    | 要修改标签属性的cid列表,数组长度不大于1000 |
DCloud_JSON's avatar
DCloud_JSON 已提交
605
| custom_tag | String | 是 | 无 | 客户端标签,标签中不能包含空格,单个标签最大长度为32字符,如果含有中文字符需要编码(UrlEncode) |
DCloud_JSON's avatar
DCloud_JSON 已提交
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629

* 参数示例
```js
{
    "cid": [
        "xxx"
    ],
	"custom_tag":"xxx"
}
```

##### 响应体说明
```js
{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": "true"
    }
}
```

> 返回结构说明请参考[公共返回结构](#公共返回结构)

DCloud_JSON's avatar
DCloud_JSON 已提交
630 631
#### 查询客户端标签
根据cid查询客户端标签列表
DCloud_JSON's avatar
DCloud_JSON 已提交
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662
>此接口有频次控制(每分钟最多100次,每天最多10000次),申请修改请点击右侧“技术咨询”了解详情
##### 接口形式
```js 
await push.searchCustomTagByCid(cid)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | Array | 是 | 无 | 用户标识 |

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
663
|$cid|Object|key: cid,value: 标签列表,列表中只会有一个元素,多个以空格隔开|
DCloud_JSON's avatar
DCloud_JSON 已提交
664 665 666


### 黑名单用户
DCloud_JSON's avatar
DCloud_JSON 已提交
667 668
黑名单用户无法收到推送消息。当使用群发全推时,有时需要调节某些设备不发,此时需要按push_clientid进行黑名单控制。

DCloud_JSON's avatar
DCloud_JSON 已提交
669 670
#### 添加黑名单用户
将单个或多个用户加入黑名单,对于黑名单用户在推送过程中会被过滤掉。
DCloud_JSON's avatar
DCloud_JSON 已提交
671

DCloud_JSON's avatar
DCloud_JSON 已提交
672 673
##### 接口形式
```js 
DCloud_JSON's avatar
DCloud_JSON 已提交
674
await push.addCidToBlacklist(push_clientid)
DCloud_JSON's avatar
DCloud_JSON 已提交
675 676 677 678
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
DCloud_JSON's avatar
DCloud_JSON 已提交
679
| push_clientid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
DCloud_JSON's avatar
DCloud_JSON 已提交
680 681 682 683 684 685 686 687 688 689 690 691 692 693 694

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)


#### 移除黑名单用户
DCloud_JSON's avatar
DCloud_JSON 已提交
695
将单个push_clientid或多个push_clientid用户移出黑名单,对于黑名单用户在推送过程中会被过滤掉的,不会给黑名单用户推送消息
DCloud_JSON's avatar
DCloud_JSON 已提交
696 697
##### 接口形式
```js 
DCloud_JSON's avatar
DCloud_JSON 已提交
698
await push.removeCidInBlacklist(push_clientid)
DCloud_JSON's avatar
DCloud_JSON 已提交
699 700 701 702
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
DCloud_JSON's avatar
DCloud_JSON 已提交
703
| getui_ | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
DCloud_JSON's avatar
DCloud_JSON 已提交
704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)


### 设备信息
#### 设备在线状态
DCloud_JSON's avatar
DCloud_JSON 已提交
720
查询你的应用在线状态
DCloud_JSON's avatar
DCloud_JSON 已提交
721

DCloud_JSON's avatar
DCloud_JSON 已提交
722
注意:该状态为:`offline`离线时,消息可通过:同设备下其他集成个推SDK的在线应用通道完成推送(iOS不支持,Android受限于手机rom的节点设置策略)
DCloud_JSON's avatar
DCloud_JSON 已提交
723 724 725

##### 接口形式
```js 
DCloud_JSON's avatar
DCloud_JSON 已提交
726
await push.getClientStatusByCid(push_clientid)
DCloud_JSON's avatar
DCloud_JSON 已提交
727 728 729 730
```
##### 入参说明
| 名称 | 类型    | 是否必须 | 默认值 | 说明                                    |
|:----|:-------|:--------|:------|:---------------------------------------|
DCloud_JSON's avatar
DCloud_JSON 已提交
731
| push_clientid | String | 是      | 无    | 用户标识,多个以英文逗号隔开,一次最多传1000个 |
DCloud_JSON's avatar
DCloud_JSON 已提交
732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)
* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
754
| $cid | Object | key: cid,value: 用户状态信息 |
DCloud_JSON's avatar
DCloud_JSON 已提交
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799
| last_login_time | String | 毫秒时间戳 |
| status | String | 状态,online在线 offline离线 |

#### 推送通道状态
查询与你的应用同设备(手机)下的所有集成了个推SDK的应用在线状态

注意:
1. 该接口返回设备在线时,仅表示存在集成了个推SDK的应用在线
2. 该接口返回设备不在线时,仅表示不存在集成了个推SDK的应用在线
3. 该接口需要开通权限,如需开通,请联系右侧技术咨询
##### 接口形式
```js 
await push.getDeviceStatusByCid(cid)
```
##### 入参说明
| 名称 | 类型    | 是否必须 | 默认值 | 说明                                    |
|:----|:-------|:--------|:------|:---------------------------------------|
| cid | String | 是      | 无    | 用户标识,多个以英文逗号隔开,一次最多传100个  |

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
800
| $cid | Object | key: cid,value: 用户状态信息 |
DCloud_JSON's avatar
DCloud_JSON 已提交
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850
| cid_status | String | cid在线状态,online在线 offline离线 |
| device_status | String | 设备在线状态,online在线 offline离线 |


#### 设备详细信息
查询用户的信息
##### 接口形式
```js 
await push.getClientDetailByCid(String|Array)
```
##### 入参说明
| 名称 | 类型    | 是否必须 | 默认值 | 说明                                    |
|:----|:-------|:--------|:------|:---------------------------------------|
| cid | String | 是      | 无    | 用户标识,多个以英文逗号隔开,一次最多传1000个 |

##### 响应体说明
* 返回值示例

```js
{
    "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`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
851
| validCids | Object Array | 用户信息列表 |
DCloud_JSON's avatar
DCloud_JSON 已提交
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909
| 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| 登录频次|


#### 查询设备总量
通过指定查询条件来查询满足条件的用户数量
##### 接口形式
```js 
await push.getClientCount(OBJECT)
```
##### 入参说明
* 参数示例

```js
{
    "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"
        }
    ]
}
```

* 请求参数说明

| 名称       | 类型           | 是否必须   | 默认值  | 描述  |
|---- |----|---| ----|
DCloud_JSON's avatar
DCloud_JSON 已提交
910
| key | String 			| 是 | 无      |查询条件(phone_type 手机类型,region 省市,custom_tag 客户端标签,设置标签请见[接口](#客户端标签))|
DCloud_JSON's avatar
DCloud_JSON 已提交
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
| values | String Array | 是 | 无      |查询条件值列表,其中<br>**手机型号**使用如下参数`android``ios`<br>**省市**使用编号,[点击下载文件region_code.data](https://docs.getui.com/files/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)

##### 响应体说明
 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
| user_count | Number | 符合条件的用户数量 |


#### 设置应用角标(仅支持IOS)
通过cid通知个推服务器当前iOS设备的角标情况。
##### 接口形式
```js 
await push.setBadgeByCid(OBJECT)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
| badge |String|是|无|用户应用icon上显示的数字<br>`+N`: 在原有badge上+N<br>`-N`: 在原有badge上-N<br>`N`: 直接设置badge(数字,会覆盖原有的badge值) |
* 参数示例

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

##### 响应体说明

### 统计API
#### 获取推送结果
查询推送数据,可查询消息可下发数、下发数,接收数、展示数、点击数等结果。支持单个taskId查询和多个taskId查询。
>此接口调用,仅可以查询toList或toApp的推送结果数据;不能查询toSingle的推送结果数据。
##### 接口形式
```js 
await push.getReport(OBJECT)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| taskid | String | 是 | 无 | 任务id,推送时返回,多个taskId以英文逗号隔开,一次最多传200个|
| actionIdList | String | 否 | 无 |  

##### 响应体说明
* content-type:`application/json;charset=utf-8`

* 返回值示例

```js
 {
    "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`说明

| 名称 | 类型 | 描述 |                 
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1013 1014 1015
|$taskid|Object|key: 任务编号,value: 统计数据|
|total|Object|总的统计数据|
|gt|Object|key表示厂商通道,value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。|
DCloud_JSON's avatar
DCloud_JSON 已提交
1016 1017 1018 1019 1020
|msg_num|Number|消息可下发数|
|target_num|Number|消息下发数|
|receive_num|Number|消息接收数|
|display_num|Number|消息展示数|
|click_num|Number|消息点击数|
DCloud_JSON's avatar
DCloud_JSON 已提交
1021
|actionCntMap|Object|自定义事件统计数据|
DCloud_JSON's avatar
DCloud_JSON 已提交
1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075
|$actionId|Number|$actionId为自定义事件id,对应的值表示对应的统计数据(由开发者打点统计)|


#### 任务组名查报表
根据任务组名查询推送结果,返回结果包括消息可下发数、下发数,接收数、展示数、点击数。
>此接口调用,仅可以查询toList或toApp的推送结果数据;不能查询toSingle的推送结果数据。
##### 接口形式
```js 
await push.getReportByGroupName(group_name)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| group_name | String | 是 | 无 | 任务组名|

##### 响应体说明
* 返回值示例

```js
 {
    "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`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1076 1077 1078
|$group_name|Object|key任务编号,value: 统计数据|
|total|Object|总的统计数据|
|gt|Object|key表示厂商通道,value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。|
DCloud_JSON's avatar
DCloud_JSON 已提交
1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163
|msg_num|Number|消息可下发数|
|target_num|Number|消息下发数|
|receive_num|Number|消息接收数|
|display_num|Number|消息展示数|
|click_num|Number|消息点击数|


#### 获取推送实时结果
获取推送实时结果,可查询消息下发数,接收数、展示数、点击数和消息折损详情等结果。支持单个taskId查询和多个taskId查询。
>注意:该接口需要开通权限,如需开通,请联系对应的商务同学开通
##### 接口形式
```js 
await push.getReportDetailByTaskid(taskid)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| taskid | String | 是 | 无 | 任务id,推送时返回,多个taskId以英文逗号隔开,一次最多传200个|

##### 响应体说明
* 返回值示例

```js
{
    "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`说明

| 名称 | 类型 | 描述 |                 
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1164 1165 1166
|$taskid|Object|key: 任务编号,value: 统计数据|
|total|Object|总的统计数据|
|gt|Object|key表示厂商通道,value表示该通道的统计数据。其中 gt: 个推通道; apn: APNs通道; key还可以是hw、xm、vv、mz、op。|
DCloud_JSON's avatar
DCloud_JSON 已提交
1167 1168 1169 1170 1171
|msg_num|Number|消息可下发数|
|target_num|Number|消息下发数|
|receive_num|Number|消息接收数|
|display_num|Number|消息展示数|
|click_num|Number|消息点击数|
DCloud_JSON's avatar
DCloud_JSON 已提交
1172 1173 1174 1175 1176
|failed_detail|Object|消息折损详情|
|ts|Object|请求-可下发阶段折损数据|
|rs|Object|可下发-下发成功阶段折损数据|
|sf|Object|下发成功-到达阶段折损数据|
|fd|Object|到达-展示阶段折损数据|
DCloud_JSON's avatar
DCloud_JSON 已提交
1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261


* `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|其他原因|

#### 获取单日推送数据
调用此接口可以获取某个应用单日的推送数据(推送数据包括:下发数,接收数、展示数、点击数)(目前只支持查询非当天的数据)
##### 接口形式
```js 
await push.getReportByDate(date)
```
##### 入参说明
| 名称 | 类型 | 是否必须 | 默认值| 说明 |
| ------ | ------ | ------ | ------ | ------ |
| date | String | 是 | 无 | 日期,格式: yyyy-MM-dd|

##### 响应体说明
* 返回值示例

```js
{
    "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`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1262 1263 1264
|$date|Object|key: 日期,格式: yyyy-MM-dd,value: 统计数据|
|total|Object|总的统计数据|
|gt|Object|key表示厂商通道,value表示该通道的统计数据。其中 gt: 个推通道; ios: APN;st: 坚果; key还可以是hw、xm、vv、mz、op。|
DCloud_JSON's avatar
DCloud_JSON 已提交
1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406
|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.该接口做了频控限制,请不要频繁调用
##### 接口形式
```js 
await push.getTodayReport()
```
##### 入参说明


##### 响应体说明
* 返回值示例

```js
{
    "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|  


#### 获取单日用户数据接口
调用此接口可以获取某个应用单日的用户数据(用户数据包括:新增用户数,累计注册用户总数,在线峰值,日联网用户数)(目前只支持查询非当天的数据)
##### 接口形式
```js 
await push.getClientReportByDate(date)
```
##### 入参说明

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

##### 响应体说明
* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1407
|$date|Object|key: 日期,格式: yyyy-MM-dd,value: 统计数据|
DCloud_JSON's avatar
DCloud_JSON 已提交
1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447
|accumulative_num|Number|累计注册用户数|
|register_num|Number|注册用户数|
|active_num|Number|活跃用户数|
|online_num|Number|在线用户数|

#### 获取24个小时在线用户数
查询当前时间一天内的在线用户数(10分钟一个点,1个小时六个点)
##### 接口形式
```js
await push.getTodayOnlineClientReport()
```
##### 入参说明


##### 响应体说明
##### 成功响应数据格式:

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

* 返回值示例

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

> 返回结构说明请参考[公共返回结构](#公共返回结构)

* 返回参数`data`说明

| 名称 | 类型 | 描述 |
| ------ | ---- | -------- |
DCloud_JSON's avatar
DCloud_JSON 已提交
1448
|online_statics|Object|在线用户统计数据|
DCloud_JSON's avatar
DCloud_JSON 已提交
1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459
|$date|Number|key: 毫秒时间戳,value: 在线用户数|


### 公共返回结构

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

| 名称 | 类型 |  描述 |
| ------ | ------ | ---- |
| errCode | Number | 成功或失败errCode码,详细含义见[返回码说明](#返回码说明)|
| errMsg | String | 失败时返回此说明|
DCloud_JSON's avatar
DCloud_JSON 已提交
1460
| data | Object | 详见接口说明|
DCloud_JSON's avatar
DCloud_JSON 已提交
1461 1462 1463 1464

### 返回码说明


DCloud_JSON's avatar
DCloud_JSON 已提交
1465
> HTTP errCode码说明
DCloud_JSON's avatar
DCloud_JSON 已提交
1466

DCloud_JSON's avatar
DCloud_JSON 已提交
1467
uni-cloud-push 扩展库的errCode码以uni-cloud-push-error-开头,如:uni-cloud-push-error-10005,以下省略为10005
DCloud_JSON's avatar
DCloud_JSON 已提交
1468

DCloud_JSON's avatar
DCloud_JSON 已提交
1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480
| errCode	| 错误描述		|  解决措施																|
| ------	| ------		| ----																	|
| 0			| 成功			| 不涉及																	|
| 1			| 失败			| 接口入参要求是 Object 格式,非 Object 格式会无法识别导致报错,建议检查一下代码		|
| 2			| 服务正在启动	| 请等待																	|
| 200		| 成功			| 查看基础返回码															|
| 301		| 域名错误		| 请检查域名是否与appid机房匹配												|
| 400		| 参数错误		| 具体异常信息请参考业务返回码												|
| 401		| 权限相关		| 具体异常信息请参考业务返回码												|
| 403		| 套餐相关		| 具体异常信息请参考业务返回码												|
| 404		| url错误		| 请检查Http路径是否正确													|
| 405		| 方法不支持		| 该接口不支持该方法请求,请查看文档确认请求方式								|
DCloud_JSON's avatar
DCloud_JSON 已提交
1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525

#### 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 |

DCloud_JSON's avatar
DCloud_JSON 已提交
1526 1527
查询客户端标签
根据cid查询客户端标签列表
DCloud_JSON's avatar
DCloud_JSON 已提交
1528 1529


DCloud_JSON's avatar
DCloud_JSON 已提交
1530
## 注意:
DCloud_JSON's avatar
DCloud_JSON 已提交
1531 1532 1533 1534 1535
`push_clientid`如果3个月未登陆会失效,所以uni-id的token过期时间不能超过3个月,否则push模块会有意想不到的故障。

<div class="weixin-support">
    <div class="weixin-support-focus">
        <img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/628c90e2-c04f-4f92-8564-85d54b467e4f.png" alt="" class="weixin-support-icon">
DCloud_JSON's avatar
DCloud_JSON 已提交
1536
        联系
DCloud_JSON's avatar
DCloud_JSON 已提交
1537
        <br>
DCloud_JSON's avatar
DCloud_JSON 已提交
1538
        个推
DCloud_JSON's avatar
DCloud_JSON 已提交
1539 1540 1541 1542 1543
    </div>
    <div class="weixin-support-content">
		<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/f91f57ca-ea30-47ee-a740-954153977e88.jpg" alt="" class="weixin-support-icon">
       微信扫一扫
		<br>
DCloud_JSON's avatar
DCloud_JSON 已提交
1544
        随时联系个推技术支持
DCloud_JSON's avatar
DCloud_JSON 已提交
1545 1546 1547 1548 1549 1550 1551 1552
    </div>
</div>

<style>
.weixin-support {
  position: fixed;
  z-index: 10;
  bottom: calc(10% + 265px);
1553 1554
  right: 230px;
}
1555
@media screen and (max-width: 1499px) {
1556 1557 1558
	.weixin-support {
	  right: 10px;
	}
DCloud_JSON's avatar
DCloud_JSON 已提交
1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596
}
.weixin-support img{
	background: #0591F0;
}
.weixin-support-focus {
  padding: 10px 8px;
  color: #fff;
  font-size: 12px;
  line-height: 14px;
  text-align: center;
  background: #0591F0;
  box-shadow: 0px 4px 8px rgba(0, 105, 202, 0.24);
  border-radius: 2px;
}
.weixin-support-focus .iconfont{
  display: block;
  font-size: 16px;
  text-align: center;
}
.weixin-support-icon{
  width: 30px;
  display: block;
  margin-bottom: 2px;
  margin-top: -4px;
}
.weixin-support-content {
  z-index: 10;
  display: none;
  position: absolute;
  right: 50px;
  top: -100px;
  background-color: #fff;
  padding: 20px;
  margin-right: 10px;
  text-align: center;
  box-shadow: 0 0 20px rgba(0, 0, 0, 0.5);
  width: 230px;
  font-size: 14px;
1597
  box-shadow: 0 0 10px #ccc;
DCloud_JSON's avatar
DCloud_JSON 已提交
1598 1599 1600 1601 1602 1603 1604 1605 1606 1607
}
.weixin-support:hover .weixin-support-content{
  display: block;
}
.weixin-support-content img{
  display: block;
  height: 200px;
  width: 200px;
}
</style>