帮助与文档

> >

一、概述

MobPush不仅提供完善的SDK API供开发者APP调用,且提供完全遵循Rest规范的HTTP接口,适用各开发语言环境调用。

1.1、约束规范

  • 前置条件:
  • 需要有接入APPKEY信息(申请MobSDK的appkey流程),开通MobPush产品;
  • 官网MobPush->推送设置填写服务器IP地址绑定,仅绑定的ip才有调用权限;
  • 接口使用RestAPI规范,所有请求接口新增、修改使用POST方法;所有查询接口使用GET方法;
  • 请求Header信息需要增加key和sign两个参数,请求内容参数使用JSON格式,并且使用UTF-8编码。

1.2、接口频率限制

MobPush 接口频率主要针对每个appkey 在每分钟的访问请求次数限制。

主要有两层请求控制频率限制,推送接口(发送+查询)的接口频率限制,默认500次/分钟;全部接口的请求频率限制,默认800次/分钟。

1.3、鉴权

MobPush Rest Api 采用MD5参数签名认证的方式。

  • 避免AppSecret的直接传输;
  • 可对请求参数进行完整性校验,保障数据不可篡改。

基本步骤:

  • 获取Mob官网提供的appkey、App Secret
  • 将请求参数JSON内容生成一个字符串
  • 将上面生成的字符串尾部拼接App Secret值得到新字符串(如果请求参数为空则此步骤得到字符串就是App Seret)
  • 将拼接后的字符串MD5得到签名sign
  • 发送请求的HTTP Header加如下两个键参数:key、 sign。key的值appkey, sign值为如上步骤获取的sign值。

1.4、资源列表

接口类型 资源名称 资源路径 描述 请求方式 版本
推送接口 发送推送 /push 创建、修改推送消息,API仅支持非定时推送 POST V1.0.0
查询推送 /push/id/{batchId} 根据创建id查询推送消息详情 GET V1.0.0
查询推送 /push/workno/{workno} 根据自定义编号查询消息详情 GET V1.0.0
推送统计 查询推送统计

/stats/id/{batchId}
根据创建id查询推送统计 GET V1.0.0
查询推送统计 /stats/workno/{workno} 根据自定义编号查询推送统计 GET V1.0.0
设备别名 查询别名 /alias/{registrationId} 根据设备registrationId查询设备别名信息 GET V1.0.0
设置修改别名 /alias 设置、修改、清除设备别名 POST V1.0.0
设备标签 查询标签 /tags/{registrationId} 根据设备registrationId查询标签信息 GET V1.0.0
设置修改标签 /tags 设置、修改、清除设备标签 POST V1.0.0
其他 地理位置信息 /area/{parentId} 获取下属地理行政信息 GET V1.0.0

 

二、推送接口

2.1、发送推送

 

接口地址: http://api.push.mob.com/push

请求方式: POST

请求参数格式: JSON

接口访问频率限制:受限,参照 接口频率限制

请求参数
参数名 参数类型 必选 说明
appkey String 应用KEY
workno String 调用方提供的唯一编号,需要在当前appkey下唯一不可重复
plats Integer[] 可使用平台,

1、android ; 2、ios ;如包含ios和android则为[1,2]

iosProduction int plat = 2下,0测试环境,1生产环境,默认1
target int 推送范围:1广播;2别名;3标签;4regid;5地理位置;6用户分群
tags String[] 设置推送标签集合[“tag1″,”tag2”],target=2则必选
alias String[] 设置推送别名集合[“alias1″,”alias2”],target=3则必选
registrationIds String[] 设置推送Registration Id集合[“Id1″,”id2”],target=4则必选
city String 推送地理位置(城市),target=5则必选
block String 用户分群ID,target=6则必选
content String 推送内容
unlineTime Integer 离线时间为0,或者在1~10天以内,单位天, 默认1天
type Integer 推送类型:1通知;2自定义
extras String 附加字段键值对的方式,扩展数据 json
自定义消息
customType String 自定义消息类型:text 文本消息
customTitle String 自定义类型标题
android通知类型消息 设置
androidTitle String Android显示标题
androidstyle Int Android显示样式标识

normal(0,”普通通知”),
bigtext(1,”BigTextStyle通知,点击后显示大段文字内容”),
bigpicture(2,”BigPictureStyle,大图模式”),
hangup(3,”横幅(收件箱)通知”);

androidContent String[] androidstyle样式具体内容:

0、默认通知无;

1、长内容则为内容数据;

2、大图则为图片地址;

3、横幅则为多行内容

androidVoice Boolean 提示音,默认true
androidShake Boolean 震动,默认true
androidLight Boolean 指示灯,默认true
ios 通知类型消息设置
iosTitle String 如果不设置,则默认的通知标题为应用的名称。
iosSubtitle String 副标题
iosSound String APNs通知,通过这个字段指定声音。默认为default,即系统默认声音。 如果设置为空值,则为静音。

如果设置为特殊的名称,则需要你的App里配置了该声音才可以正常。

iosBadge int 可直接指定 APNs 推送通知的 badge,直接展示在桌面应用图标的右上角,含义是应用未读的消息数。默认值为 1。
iosCategory String 只有IOS8及以上系统才支持此参数推送
iosSlientPush int 如果只携带content-available: 1,不携带任何badge,sound 和消息内容等参数,

则可以不打扰用户的情况下进行内容更新等操作即为“Silent Remote Notifications”。

iosContentAvailable int
iosMutableContent int 需要在附加字段中配置相应参数
请求示例

 

返回结果

参数 类型 是否必须 说明
status Int 返回状态码
errror String 错误信息
res JSON 返回结果数据
batchId String 批次编号

返回示例

 

2.2、推送详情(根据batchId查询

 

batchId 为MobPush平台分配唯一编号

接口地址: http://api.push.mob.com/push/id/{batchId}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数

请求示例 

返回结果
参数名 参数类型 必选 说明
status Int 结果状态码
error String 错误信息
res JSON 返回结果信息(内容如下)
appkey String 应用KEY
plats Integer[] 可使用平台,

1、android ; 2、ios ;如包含ios和android则为[1,2]

iosProduction int plat = 2下,0测试环境,1生产环境,默认1
target int 推送范围:1广播;2别名;3标签;4regid;5地理位置;6用户分群
tags String[] 设置推送标签集合[“tag1″,”tag2”],target=2则必选
alias String[] 设置推送别名集合[“alias1″,”alias2”],target=3则必选
registrationIds String[] 设置推送Registration Id集合[“Id1″,”id2”],target=4则必选
city String 推送地理位置(城市),target=5则必选
block String 用户分群ID,target=6则必选
content String 推送内容
unlineTime Integer 离线时间为0,或者在1~10天以内,单位天, 默认1天
type Integer 推送类型:1通知;2自定义
extras String 附加字段键值对的方式,扩展数据 json
自定义消息
customType String 自定义消息类型:text 文本消息
customTitle String 自定义类型标题
android通知类型消息 设置
androidTitle String Android显示标题
androidstyle Int Android显示样式标识

normal(0,”普通通知”),
bigtext(1,”BigTextStyle通知,点击后显示大段文字内容”),
bigpicture(2,”BigPictureStyle,大图模式”),
hangup(3,”横幅(收件箱)通知”);

androidContent String[] androidstyle样式具体内容:

0、默认通知无;

1、长内容则为内容数据;

2、大图则为图片地址;

3、横幅则为多行内容

androidVoice Boolean 提示音,默认true
androidShake Boolean 震动,默认true
androidLight Boolean 指示灯,默认true
ios 通知类型消息设置
iosTitle String 如果不设置,则默认的通知标题为应用的名称。
iosSubtitle String 副标题
iosSound String APNs通知,通过这个字段指定声音。默认为default,即系统默认声音。 如果设置为空值,则为静音。

如果设置为特殊的名称,则需要你的App里配置了该声音才可以正常。

iosBadge int 可直接指定 APNs 推送通知的 badge,直接展示在桌面应用图标的右上角,含义是应用未读的消息数。默认值为 1。
iosCategory String 只有IOS8及以上系统才支持此参数推送
iosSlientPush int 如果只携带content-available: 1,不携带任何badge,sound 和消息内容等参数,

则可以不打扰用户的情况下进行内容更新等操作即为“Silent Remote Notifications”。

iosContentAvailable int
iosMutableContent int 需要在附加字段中配置相应参数

 

返回示例

 

2.3、推送详情(根据workno查询

workno为创建时调用方提供的唯一编号

接口地址: http://api.push.mob.com/push/workno/{workno}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数

请求示例

返回结果

同 推送详情(batchId查询)

返回示例

 

同 推送详情(batchId查询)

 

三、推送统计接口

3.1、获取统计数据(根据batchId查询)

 

batchId 为MobPush平台分配唯一编号

接口地址: http://api.push.mob.com/stats/id/{batchId}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数

请求示例

返回结果

 

参数 类型 必选 说明
status Int 返回状态码
error String 错误内容
res JOSN 正确数据内容
appkey String 应用KEY
id String 任务ID
workno String 自定义任务编号
androidDeviceNum Long 设备数 – android
iosDeviceNum Long 设备数 – ios
androidSuccessNum Long 成功数- android
iosSuccessNum Long 成功数- ios
androidCancelNum Long 取消数 – android
iosCancelNum Long 取消数- ios
androidClickNum Long 点击数 – android
iosClickNum Long 点击数 -ios

 

返回示例

 

 

3.2、获取统计数据(根据workno查询)

workno为创建时调用方提供的唯一编号

接口地址: http://api.push.mob.com/stats/workno/{workno}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数

请求示例

返回结果

 

参数 类型 必选 说明
status Int 返回状态码
error String 错误内容
res JOSN 正确数据内容
appkey String 应用KEY
id String 任务ID
workno String 自定义任务编号
androidDeviceNum Long 设备数 – android
iosDeviceNum Long 设备数 – ios
androidSuccessNum Long 成功数- android
iosSuccessNum Long 成功数- ios
androidCancelNum Long 取消数 – android
iosCancelNum Long 取消数- ios
androidClickNum Long 点击数 – android
iosClickNum Long 点击数 -ios

 

返回示例

 

 

四、设备别名

4.1、查询别名

 

registrationId是由使用sdkapi获取到再上报给调用方服务端。

接口地址: http://api.push.mob.com/alias/{registrationId}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数 

请求示例

返回结果
参数 类型 是否必须 说明
status Int 返回状态码
error String 错误信息
res Json  否 正确信息
alias String 设备别名

 

返回示例

 

 

4.2、设置别名

 

接口地址: http://api.push.mob.com/alias

请求方式: POST

接口访问频率限制:受限,参照 接口频率限制

请求参数 

参数名 参数类型 是否必须 说明
alias String 设置别名,如果清除则设置为空字符串即可
registrationId String registrationId是由使用sdkapi获取到再上报给调用方服务端。

 

请求示例

 

返回结果

参数 类型 是否必须 说明
status Int 返回状态码
error String 错误信息

返回示例

 

五、设备标签

5.1、查询标签

 

registrationId是由使用sdkapi获取到再上报给调用方服务端。

接口地址: http://api.push.mob.com/tags/{registrationId}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

请求参数 

请求示例

返回结果
参数 类型 是否必须 说明
status Int 返回状态码
error String 错误信息
res Json  否 正确信息
tags String[] 标签列表,无则null

 

返回示例

 

5.2、设置标签

 

接口地址: http://api.push.mob.com/tags

请求方式: POST

接口访问频率限制:受限,参照 接口频率限制

请求参数 
参数名 参数类型 是否必须 说明
registrationId String 设备Id
opType int 操作类型:1新增标签;2删除标签;3清除所有标签
tags String[] 操作标签集合; opType= 1 or opType =2 则必填

 

请求示例

 

返回结果
参数 类型 是否必须 说明
status Int 返回状态码
error String 错误信息

 

返回示例

 

六、其他(基础接口)

6.1、地理位置查询接口

 

查询当前参数级别下属行政地理名称划分,parentId默认0为中国下属省级列表。

接口地址: http://api.push.mob.com/area/{parentId}

请求方式: GET

接口访问频率限制:受限,参照 接口频率限制

 

请求参数 

请求示例

返回结果
参数 类型 是否必须 说明
status Int 返回状态码
error String 错误信息
res Json  否 正确信息
Id String 信息ID
parentId String 父级ID
country String 国家
province String 省份
city String 城市

 

返回示例

 

七、错误码

 

错误码 解释 HTTP Response Code 备注
200 成功 200
4800 请求头信息缺少key字段 400
4801 请求IP不匹配或者未设置 400 服务端IP未设置或者和当前访问来源不符
4802 应用未开启MobPush产品或者被禁用 400  未在MOB官网添加MobPush产品或者appkey已经被加入黑名单
4803 别名字数超过限制 400 · 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
4804 别名格式不正确 400 · 字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|。
4805 单个标签长度超过限制 400 · 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
4806 标签格式不正确 400 · 字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
4807 未筛选到发送对象 400
4808 当前推送任务不能修改 400
4809 请求缺少必要参数 400
4810 请求过于频繁 400  超过频率限制
4811 推送任务长度超限 400 utf-8不超过500字节
4812 缺少推送内容 400
4813 缺少目标平台 400
4814 缺少目标人群 400
4815 缺少推送类型 400
4816 超过最大离线时间 400 离线时间为0,或者在1~10天以内,单位天
4817 大段文本设置内容超过限制 400 最多100字符
4818 收件箱内容超过限制 400 每条最多20字符
4819 收件箱条数超过限制 400 最多5条
4820 标题设置超过限制 400 最多20字符
5800 未知异常 500
5801 sign验证失败 500
5802 workno已经存在 500
5803 无推送目标设备 500
1 0

相关文档