用户API

用户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 在离线情况,可选值有onlineoffline
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"
}
开发者中心 SDK 下载

文档中心搜索