用户API
简述
开发者可对用户设定别名与标签,推送时可直接根据别名、标签进行推送,方便对用户的管理。
别名:
别名是开发者根据自身需求为每个用户设定的标识,建议对不同用户设定不同别名,保证可通过别名来唯一确认某特定用户。
例子:可将用户的邮箱、昵称、手机号等设为别名,即可通过邮箱、昵称、手机号指定目标用户下发推送。
标签:
标签是用户的一种属性,每个用户(通过CID来标识 )可以打上100个标签。
例子:“喜爱足球”,“喜爱动漫”
短信:
开发者绑定用户cid与手机号,在推送消息无法及时下发时,自动使用短信触达用户。
黑名单用户
黑名单用户无法收到推送消息
【别名】为用户绑定别名
功能描述
一个clientid只能绑定一个别名,若已绑定过别名的clientid再次绑定新别名,则认为与前一个别名自动解绑,绑定新别名。
接口名称
bindAlias(APPID,ALIAS,CID)
限制说明
- 有效的别名组成:字母(区分大小写)、数字、下划线、汉字
- 任务别名长度限制为 40 字节。( UTF-8 )
- 一个别名最多允许绑定10个clientid。
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$alias |
String |
是 |
无 |
用户别名 |
$cid |
String |
是 |
无 |
用户id |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
error_code |
String |
错误标识 |
error_msg |
String |
错误信息 |
返回示例
{
"result":"true",
"error_code":"xxx",
"error_msg":"xx"
}
【别名】批量绑定别名
功能描述
批量绑定多个cid和别名
接口名称
bindAliasBatch(APPID,$targetList)
限制说明
- 有效的别名组成:字母(区分大小写)、数字、下划线、汉字
- 任务别名长度限制为 40 字节。( UTF-8 )
- 一个别名最多允许绑定10个clientid。
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$targetList |
Array |
是 |
无 |
Target对象,别名绑定目标 |
Target
名称 |
类型 |
是否必需 |
默认值 |
描述 |
$appId |
String |
否 |
无 |
应用唯一ID |
$clientId |
String |
是 |
无 |
客户端身份ID |
$alias |
String |
是 |
无 |
用户别名 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
error_code |
String |
错误标识 |
error_msg |
String |
错误信息 |
返回示例
{
"result":"true",
"error_code":"xxx",
"error_msg":"xx"
}
【别名】根据别名查询cid
功能描述
根据别名获取clientid信息
接口名称
queryClientId(APPID,ALIAS)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$alias |
String |
是 |
无 |
用户别名 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果 |
cidlist |
Array |
cid列表 |
返回示例
{
"result":"ok",
"cidlist":["xxx"]
}
【别名】根据cid查询别名
功能描述
通过clientid获取别名信息
接口名称
queryAlias(APPID,CID)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$cid |
String |
是 |
无 |
用户id |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
alias |
String |
别名 |
返回示例
{
"result":"ok",
"alias":"xxx"
}
【别名】解绑别名
功能描述
单个clientid和别名解绑
接口名称
unBindAlias(APPID,ALIAS,CID)
请求参数:
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$alias |
String |
是 |
无 |
用户别名 |
$cid |
String |
是 |
无 |
用户id(clientid) |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
error_code |
String |
错误标识 |
error_msg |
String |
错误信息 |
返回示例
{
"result":"true",
"error_code":"xxx",
"error_msg":"xx"
}
【别名】全量解绑别名
功能描述
绑定别名的所有clientid解绑
接口名称
unBindAliasAll(APPID,ALIAS)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$alias |
String |
是 |
无 |
用户别名 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
error_code |
String |
错误标识 |
error_msg |
String |
错误信息 |
返回示例
{
"result":"true",
"error_code":"xxx",
"error_msg":"xx"
}
【标签】为用户绑定标签
功能描述
对指定用户设置tag属性。此接口为覆盖效果,调用接口后原标签会失效。
限制说明
注:此接口有频次控制,tag的长度、个数、总长度也有限制,申请修改请联系邮箱:lieg@getui.com 。
接口名称
setClientTag(APPID,CID,$tagList)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$cid |
String |
是 |
无 |
目标用户id(clientid) |
$tagList |
Array |
是 |
无 |
用户tag列表 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
返回示例
{
"result":"Success"
}
【标签】查询用户标签
功能描述
获取指定用户的tag属性
限制说明
注:此接口有频次控制,tag的长度、个数、总长度也有限制,申请修改请联系邮箱:lieg@getui.com 。
接口名称
getUserTags(appId, cid)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
用户所属应用id |
$cid |
String |
是 |
无 |
目标用户id(clientid) |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
clientId |
String |
客户端身份ID |
tags |
String |
用户设置的标签 |
返回示例
{
"result":"ok",
"clientId":"xxx",
"tags":"xxx"
}
【标签】通过标签获取用户总数
描述
调用此接口可以获取该标签下的用户总数
接口名称
getUserCountByTags(APPID, $tagList)
接口参数
字段 |
类型 |
说明 |
$appId |
String |
应用ID |
$tagList |
Array |
标签列表 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
appId |
String |
应用ID |
tagCount |
String |
标签数量 |
返回示例
{
"result":"Success",
"appId":"xxx",
"tagCount":"xxx"
}
【短信】为用户绑定手机号
功能描述
对指定用户绑定手机号。
接口名称
bindCidPn(appId,$params);
限制说明
1)一个cid只能绑定一个pn,后续绑定的关系会覆盖以前的绑定关系。
2)目前接口最多支持一次绑定50个cid与pn的对应关系。绑定后会返回每个cid的绑定结果。
请求参数
参数 |
类型 |
是否必填 |
最大长度 |
描述 |
$appId |
String |
是 |
32 |
个推分配给开发者的ID |
$cidAndPn |
Array |
是 |
50 |
key是cid value是pnmd5【32位小写】 |
返回值
参数 |
类型 |
是否必填 |
描述 |
示例值 |
其他 |
result |
String |
是 |
响应码 |
0 |
详细code码含义。参考pn与cid操作的相关状态码 |
batchRet |
String |
否 |
返回每个cid的绑定结果 |
[{"code":"0","cid":"xxxx"}] |
返回每个cid的绑定结果 |
【短信】根据cid查询手机号
功能描述
用户通过接口传递cid列表, 可以查询与之相对的pn,接口会批量返回绑定关系。
接口名称
queryCidPn(APPID,$cidList)
请求参数
参数 |
类型 |
是否必填 |
最大长度 |
描述 |
$appId |
String |
是 |
32 |
开发者ID |
$cidList |
Array |
是 |
50 |
客户端身份ID列表,条目限制为50以内 |
返回值
参数 |
类型 |
是否必填 |
描述 |
示例值 |
其他 |
result |
String |
是 |
响应码 |
0 |
详细code码含义。参考pn与cid操作的相关状态码 |
batchRet |
String |
否 |
返回每个cid的绑定结果 |
[{"code":"0","cid":"xxxx"}] |
返回每个cid的绑定结果 |
【短信】解绑手机号
功能描述
用户通过接口传递cid列表, 可以批量解绑与之相对应的pn的关系。
接口名称
unbindCidPn(APPID,$cids)
请求参数
参数 |
类型 |
是否必填 |
最大长度 |
描述 |
$appId |
String |
是 |
32 |
开发者ID |
$cidList |
Array |
是 |
50 |
客户端身份ID列表,条目限制为50以内 |
返回值
参数 |
类型 |
是否必填 |
描述 |
示例值 |
其他 |
result |
String |
是 |
响应码 |
0 |
详细code码含义。参考pn与cid操作的相关状态码 |
batchRet |
String |
否 |
返回每个cid的绑定结果 |
[{"code":"0","cid":"xxxx"}] |
返回每个cid的绑定结果 |
pn与cid操作的相关状态码
状态码 |
含义 |
0 |
成功 |
1 |
cid不存在 |
2 |
cid与appid不匹配 |
3 |
不能覆写低级别的PN绑定 |
4 |
应用下该PN已经绑定更活跃的cid |
5 |
cid为空 |
6 |
pn为空 |
7 |
该cid没有绑定PN值 |
8 |
其他原因导致的失败 |
【用户】获取用户状态
功能描述
调用此接口可获取用户状态,如在线不在线,cid和appid是否对应,appkey是否正确等。
接口名称
getClientIdStatus(APPID,CID)
请求参数
参数 |
类型 |
说明 |
$appId |
String |
设置推送的appid |
$cid |
String |
用户唯一标识符 |
返回参数
名称 |
类型 |
描述 |
result |
String |
在离线情况,可选值有online 和offline |
isblack |
boolean |
是否是黑名单 |
lastLogin |
String |
上次登录情况 |
返回示例
{
"result":"Offline",
"lastLogin":timestatmp,
"isblack":false
}
【用户】添加黑名单用户
功能描述
将指定cid列表中的用户加入黑名单
接口名称
addCidListToBlk($appId,$cidList);
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
appId |
$cidList |
Array |
是 |
无 |
该appId下的用户cid列表 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
返回示例
{
"result":"success"
}
【用户】移除黑名单用户
功能描述
将指定cid列表中的用户移除黑名单
接口名称
restoreCidListFromBlk($appId,$cidList)
请求参数
参数名 |
类型 |
必需 |
默认值 |
参数描述 |
$appId |
String |
是 |
无 |
appId |
$cidList |
Array |
是 |
无 |
该appId下的用户cid列表 |
返回参数
名称 |
类型 |
描述 |
result |
String |
请求结果,其他返回结果详见错误返回值 |
返回示例
{
"result":"success"
}