开发者可对用户设定别名与标签,推送时可直接根据别名、标签进行推送,方便对用户的管理。
别名:
别名是开发者根据自身需求为每个用户设定的标识,建议对不同用户设定不同别名,保证可通过别名来唯一确认某特定用户。
例子:可将用户的邮箱、昵称、手机号等设为别名,即可通过邮箱、昵称、手机号指定目标用户下发推送。
标签:
标签是用户的一种属性,每个用户(通过CID来标识 )可以打上100个标签。
例子:“喜爱足球”,“喜爱动漫”
黑名单用户
黑名单用户无法收到推送消息
一个cid只能绑定一个别名,若已绑定过别名的cid再次绑定新别名,则前一个别名会自动解绑,并绑定新别名。
/user/alias
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"data_list":[
{
"cid":"",
"alias":""
},
{
"cid":"",
"alias":""
}
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
data_list | Json Array | 是 | 无 | 数据列表,数组长度不大于1000 |
data_list说明
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
cid | String | 是 | 无 | cid,用户标识 |
alias | String | 是 | 无 | 别名,有效的别名组成: 字母(区分大小写)、数字、下划线、汉字; 长度<40字; 一个别名最多允许绑定10个cid。 |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"data_list":[
{
"cid":"",
"alias":""
},
{
"cid":"",
"alias":""
}
]
}'
通过传入的cid查询对应的别名信息
/user/alias/cid/$cid
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户唯一标识 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data": {
"alias": ""
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
alias | String | 别名 |
curl $BaseUrl/user/alias/cid/$cid -H "token: xxx"
通过传入的别名查询对应的cid信息
/user/cid/alias/$alias
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
alias | String | 是 | 无 | 别名 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data": {
"cid": ["xxx","xxx"]
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
cid | String Array | 用户唯一标识 |
curl $BaseUrl/user/cid/alias/$alias -H "token: xxx"
批量解除别名与cid的关系
/user/alias
DELETE
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"data_list":[
{
"cid":"",
"alias":""
},
{
"cid":"",
"alias":""
}
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
data_list | Json Array | 是 | 无 | 数据列表,数组长度不大于1000 |
data_list
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识 |
alias | String | 是 | 无 | 别名 |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/alias -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"data_list":[
{
"cid":"",
"alias":""
},
{
"cid":"",
"alias":""
}
]
}'
解绑所有与该别名绑定的cid
/user/alias/$alias
DELETE
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
alias | String | 是 | 无 | 用户别名 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/alias/$alias -X DELETE -H "token: xxx"
一个用户绑定一批标签,此操作为覆盖操作,会删除历史绑定的标签;
此接口对单个cid有频控限制,每天只能修改一次,最多设置100个标签;单个标签长度最大为32字符,标签总长度最大为512个字符,申请修改请点击右侧“技术咨询”了解详情 。
/user/custom_tag/cid/$cid
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"custom_tag": [
"tag1",
"tag2"
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
custom_tag | String Array | 是 | 无 | 标签列表,标签中不能包含空格 |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/custom_tag/cid/$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"custom_tag": [
"tag1",
"tag2"
]
}'
一批用户绑定一个标签,此接口为增量
此接口有频次控制(每分钟最多100次,每天最多10000次),且频次和“【标签】一批用户解绑一个标签”接口共用,申请修改请点击右侧“技术咨询”了解详情
此接口是异步的,会有延迟
/user/custom_tag/batch/$custom_tag
PUT
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
custom_tag | String | 是 | 无 | 用户标签,标签中不能包含空格,单个标签最大长度为32字符,如果含有中文字符需要编码(UrlEncode) |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"cid": [
"xxx"
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
cid | String Array | 是 | 无 | 要修改标签属性的cid列表,数组长度不大于1000 |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data": {
"$cid": "true"
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
$cid | String | key为cid,value为结果,true表示成功,否则失败 |
curl $BaseUrl/user/custom_tag/batch/$custom_tag -X PUT -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"cid": [
"xxx"
]
}'
解绑用户的某个标签属性,不影响其它标签
此接口有频次控制(每分钟最多100次,每天最多10000次),且频次和“【标签】一批用户绑定一个标签”接口共用,申请修改请点击右侧“技术咨询”了解详情
/user/custom_tag/batch/$custom_tag
DELETE
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
custom_tag | String | 是 | 无 | 用户标签,标签中不能包含空格,如果含有中文字符需要编码(UrlEncode) |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"cid": [
"xxx"
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
cid | String Array | 是 | 无 | 要删除标签属性的cid列表,数组长度不大于1000 |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"msg": "success",
"code": 0,
"data": {
"$cid": "true"
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
$cid | String | key为cid,value为结果,true表示成功,否则失败 |
curl $BaseUrl/user/custom_tag/batch/$custom_tag -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"cid": [
"xxx"
]
}'
根据cid查询用户标签列表
/user/custom_tag/cid/$cid
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"msg": "success",
"code": 0,
"data": {
"$cid": [
"custom_tag1 custom_tag2"
]
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
$cid | Json | key: cid,value: 标签列表,列表中只会有一个元素,多个以空格隔开 |
curl $BaseUrl/user/custom_tag/cid/$cid -H "token: xxx"
将单个或多个用户加入黑名单,对于黑名单用户在推送过程中会被过滤掉。
/user/black/cid/$cid,$cid
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/black/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"
将单个cid或多个cid用户移出黑名单,对于黑名单用户在推送过程中会被过滤掉的,不会给黑名单用户推送消息
/user/black/cid/$cid,$cid
DELETE
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/black/cid/$cid,$cid -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"
查询用户的状态
/user/status/$cid,$cid
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传1000个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data": {
"$cid": {
"last_login_time":"1484018265935",
"status":"offline"
}
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
$cid | Json | key: cid,value: 用户状态信息 |
last_login_time | String | 毫秒时间戳 |
status | String | 状态,online在线 offline离线 |
curl $BaseUrl/user/status/$cid,$cid -H "token: xxx"
查询设备的状态
注意:
1.该接口返回设备在线时,仅表示存在集成了个推SDK的应用在线
2.该接口返回设备不在线时,仅表示不存在集成了个推SDK的应用在线
3.该接口需要开通权限,如需开通,请联系右侧技术咨询
/user/deviceStatus/$cid,$cid
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传100个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data": {
"$cid": {
"msg":"success",
"code": 0,
"data": {
"cid_status":"offline",
"device_status":"online"
}
}
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
$cid | Json | key: cid,value: 用户状态信息 |
cid_status | String | cid在线状态,online在线 offline离线 |
device_status | String | 设备在线状态,online在线 offline离线 |
curl $BaseUrl/user/deviceStatus/$cid,$cid -H "token: xxx"
查询用户的信息
/user/detail/$cid,$cid
GET
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传1000个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code":0,
"msg":"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,
"phone_model":"vv",
"notification_switch":true,
"create_time":"2021-06-30 00:00:00",
"login_freq":10,
"brand":"hw"
}
}
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
validCids | Json 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 |
phone_model | String | 机型 |
notification_switch | Boolean | 系统通知栏开关,true-打开,false-关闭 |
create_time | String | 首次登录时间 |
login_freq | Number | 登录频次为100天内的登陆次数,如果当天多次登陆,只算一次 |
brand | String | brand是返回的厂商devicetoken前缀,比如:华为-hw、小米-xm、魅族-mz、OPPO-op、VIVO-vv、苹果-iphone,没有token的就是unknown,可以用来区分厂商渠道 |
curl $BaseUrl/user/detail/$cid,$cid -H "token: xxx"
通过cid通知个推服务器当前iOS设备的角标情况。
/user/badge/cid/$cid,$cid
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
cid | String | 是 | 无 | 用户标识,多个以英文逗号隔开,一次最多传200个 |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"badge": "-8"
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
badge | String | 是 | 无 | 用户应用icon上显示的数字+N : 在原有badge上+N-N : 在原有badge上-NN : 直接设置badge(数字,会覆盖原有的badge值) |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success"
}
curl $BaseUrl/user/badge/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"badge": -8
}'
通过指定查询条件来查询满足条件的用户数量
/user/count
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"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 间的交并补操作 |
opt_type
操作content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"code": 0,
"msg": "success",
"data":{
"user_count": 0
}
}
返回结构说明请参考公共返回结构
返回参数data
说明
名称 | 类型 | 描述 |
---|---|---|
user_count | Number | 符合条件的用户数量 |
curl $BaseUrl/user/count -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"tag": [
{
"key":"phone_type",
"values": [
"android"
],
"opt_type":"or"
},
{
"key":"region",
"values": [
"11000000",
"12000000"
],
"opt_type":"or"
},
{
"key":"custom_tag",
"values": [
"aaa"
],
"opt_type":"not"
}
]
}'
批量绑定或解绑cid和deviceToken的关系;
默认仅支持小程序通道用户。若有其他厂商通道需要使用,请点击右侧“技术咨询”了解详情。
此接口有全局频控限制,每分钟最多调用1000次。
/user/bind_dt/$type
POST
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
type | String | 是 | 无 | 小程序通道:wx :微信小程序厂商通道(需联系技术支持开通): hw :华为;hwq :华为快应用;ho :荣耀;xm :小米;op :OPPO;opg :OPPO海外;vv :VIVO;mz :魅族;fcm :谷歌;st :坚果;sn :索尼;ios :苹果; |
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
content-type:application/json;charset=utf-8
参数示例
{
"dt_list": [
{
"cid": "cid1",
"device_token": "device_token1"
},
{
"cid": "cid2",
"device_token": "device_token2"
}
]
}
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
dt_list | Json Array | 是 | 无 | 数据列表,数组长度不大于1000 |
dt_list说明
名称 | 类型 | 是否必须 | 默认值 | 描述 |
---|---|---|---|---|
cid | String | 是 | 无 | cid,用户标识 |
device_token | String | 是 | 无 | deviceToken(传值表示绑定,不传或传空表示解绑):微信小程序 :对应微信小程序用户的openid |
content-type: application/json;charset=utf-8
http code: 200(http code码说明)
返回值示例
{
"msg": "success",
"code": 0,
"data": {
"errorList": [
{
"cid": "f5fc768b8f3d0ac24d6b7df65e0221b0",
"device_token": "WX_oX-Yr4ICsWkJaydB8mdRD3DMahkA",
"error_code": 24002
},
{
"cid": "9497869031e1fa74adaa84458f73cc62",
"device_token": "WX_oX-BfgICsWkJurdB3odRDcDjyskB",
"error_code": 24003
}
]
}
}
返回结构说明请参考公共返回结构
返回参数data
说明(如果全部操作成功将不返回data
)
名称 | 类型 | 描述 |
---|---|---|
errorList | Json Array | 操作失败的用户列表 |
errorList说明
名称 | 类型 | 描述 |
---|---|---|
cid | String | 操作失败的cid |
device_token | String | 操作失败的deviceToken |
error_code | Number | 操作失败的错误码 |
error_code说明
error_code | 错误描述 | 解决措施 |
---|---|---|
24001 | cid为空 | 请检查参数 |
24002 | cid不存在 | 请检查参数 |
24003 | cid和appId不匹配 | 请检查参数 |
24004 | cid对应的类型不是小程序 | 请检查参数 |
curl $BaseUrl/user/bind_dt/wx -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
"dt_list": [
{
"cid": "f5fc768b8f3d0ac24d6b7df65e0221b0",
"device_token": "oX-Yr4ICsWkJaydB8mdRD3DMahkA"
},
{
"cid": "9497869031e1fa74adaa84458f73cc62",
"device_token": "oX-BfgICsWkJurdB3odRDcDjyskB"
}
]
}'
以上文档对您是否有帮助?