MobPush 创建推送
功能说明
MobPush 提供遵循 REST 规范的 HTTP 接口,适用各开发语言环境调用。
IP 绑定
工作台可以绑定服务器 IP 地址,未绑定之前所有 IP 均可进行 REST API 的调用,绑定后进仅绑定的 IP 才有调用权限。
调用地址
请求头
字段名
类型
选项
含义
Content-Type
string
必填
必要参数,固定值 application/json
key
string
必填
MobTech 提供的 AppKey
sign
string
必填
加密参数,加密规则为: md5(请求参数+MobAppSecret)
推送对象
以 JSON 格式表达,表示一条推送相关的所有信息。
字段名
类型
选项
含义
workno
string
可选
自定义任务 id,默认由 MobTech 自动生成,无需传递(需保证唯一性)
source
string
必填
固定值 webapi
appkey
string
必填
MobTech 提供的 AppKey
pushTarget
object
必填
推送目标
pushNotify
object
必填
推送展示细节配置
pushOperator
object
可选
运营保障相关配置
pushForward
object
可选
link 相关打开配置
pushCallback
object
可选
推送回调配置
pushFactoryExtra
object
可选
厂商特殊配置
userExtra
object
可选
用于给客户提供一些用于解释推送任务的字段扩充
groupId
string
可选
AB 分组测试 ID
pushTarget:推送目标
字段名
类型
选项
含义
target
number
必填
推送目标类型
- 1:广播
- 2:别名(alias)
- 3:标签(tags)
- 4:rid
- 5:地理位置(city)
- 6:用户分群
- 9:复杂地理位置推送(pushAreas)
- 14:fileid 推送
alias
string []
target 等于 2 时必填
推送别名集合,集合元素限制 1000 个以内。
例:["alias1","alias2"]
tags
string []
target 等于 3 时必填
推送标签集合,集合元素限制 1000 个以内
例:["tag1","tag2"]
tagsType
number
target 等于 3 时必填
标签组合方式,target 等于 3 时可用
- 1:并集
- 2:交集
- 3:补集(暂未实现)
rids
string[]
target 等于 4 时必填
推送 rid 集合,集合元素限制 1000 个以内
例:["id1","id2"]
city
string
target 等于 5 时可选,且 city、province、country 必选一个不为空
推送地理位置的城市
例:上海市
province
string
target 等于 5 时可选,且 city、province、country 必选一个不为空
推送地理位置的省份
例:浙江省
country
string
target 等于 5 时可选,且 city、province、country 必选一个不为空
推送地理位置的国家
例:中国
block
string
target 等于 6 时必填
用户分群 ID
注:该功能暂未实现
pushAreas
object
target 等于 9 时必填
复杂地理位置
fileId
string
target 等于 14 时必填
fileid
appPackages
string []
可选
指定推送的包名列表,如不填则使用默认包名进行推送
pushAreas:复杂地理位置
字段名
类型
选项
含义
countries
object []
必填
国家列表
countries:国家列表
字段名
类型
选项
含义
country
string
必填
国家名称
provinces
object []
可选
指定需要推送的省份列表
provinces:省份列表
字段名
类型
选项
含义
province
string
必填
省份名称
cities
string []
可选
需要推送的城市列表
excludeCities
string []
可选
指定不需要推送的城市列表,当指定[cities]时,这个字段不起作用
excludeProvinces
string []
可选
指定不需要推送的省份列表,当设置[provinces]时,这个不起作用
pushNotify:推送展示细节配置
字段名
类型
选项
含义
plats
number []
必填
推送生效渠道
- 1:android
- 2:iOS
例:[1, 2]
iosProduction
number
plats 数组值含有 2 时可选
iOS 环境
- 0:测试环境
- 1:生产环境(默认)
offlineSeconds
number
可选
离线消息保存时间,单位:秒,默认值为 86400
注:魅族厂商的离线保留时间范围是 1~72 小时,设置的离线保留时间如超出该范围将会导致消息无法使用魅族厂商通道,其他厂商不受影响
content
string
必填
推送内容
注 1:内容长度超过厂商限制会被截断。
注 2:vivo 不支持纯表情。
title
string
可选
通知标题
注 1:默认通知标题为应用名称
注 2:标题长度超过厂商限制会被截断
注 3:vivo 不允许纯表情
type
number
必填
推送类型
- 1:通知
- 2:自定义
androidNotify
object
可选
Android 通知消息对象
iosNotify
object
可选
iOS 通知消息对象
taskCron
number
可选
是否是定时消息
- 0:否(默认)
- 1:是
taskTime
number
taskCron=1 时必填
定时消息发送时间,单位:毫秒时间戳
例:1594277916000
speed
number
可选
每秒推送速率的趋势,默认为 0(代表不开启)
skipOnline
number
可选
是否跳过在线设备
- 1:跳过
- 0:不跳过(默认)
skipFactory
number
可选
是否跳过厂商通道
- 1:跳过
- 0:不跳过(默认)
policy
number
可选
推送策略
- 1:先走 tcp,再走厂商
- 2:先走厂商,再走 tcp
- 3:只走厂商
- 4:只走 tcp
注:厂商透传只支持策略 3 或 4
extrasMapList
object []
可选
附加参数列表
例: [ { "key": "name", "value": "jason" }, { "key": "age", "value": 18 } ]
androidNotify:Android 通知消息对象
字段名
类型
选项
含义
content
string []
可选
推送内容,配合 style 参数使用
- style=0 不生效
- style=1 部分机型可以生效覆盖
- style=2 传入图片链接,部分低版本手机不支持
- style=3 对应传入文字内容默认: 0
customStyle
object
可选
自定义样式
warn
string
可选
提醒类型,可多选组合
- 1:提示音
- 2:震动
- 3:指示灯 例:12(提示音+震动)
style
integer
可选
显示样式标识- 0:默认
- 1:长内容
- 2:大图
- 3:横幅
- 4:自定义样式
sound
string
可选
自定义声音
icon
string
可选
附带小图标的推送
注 1:icon 和 image 只能二选一,同时传输则取 icon 中的数据
注 2:目前客户端版本暂不支持
image
string
可选
推送大图标的 url 地址
注 1:icon 和 image 只能二选一,同时传输则取 icon 中的数据
注 2:透传消息不支持
注 3:小米厂商对图片尺寸有严格要求,不符合要求则不会按照大图样式进行推送,具体要求为:宽高固定为 876*324px,格式需为 PNG/JPG/JPEG,大小小于 1M
注 4:OPPO 厂商大图需要申请权限,否则会报错导致客户端收不到推送消息
androidChannelId
string
可选
安卓通知渠道 ID
注:当输入该参数后,MobPush 通道和厂商通道都会使用该 channelId;当 androidChannelId 和 pushFactoryExtra 中的 channelId 同时使用填写时,那 MobPush 通道使用 androidChannelId,厂商通道使用 pushFactoryExtra 中设置的 channelId
androidBadgeType
number
可选
角标类型
- 1:角标数值取 androidBadge 值
- 2:角标数值为 androidBadge 当前值加 1
注:透传消息不支持
androidBadge
number
可选
角标数值
customStyle:安卓通知自定义样式
字段名
类型
选项
含义
styleNo
integer
可选
样式序号
- 1:样式 1
- 2:样式 2
- 3:样式 3
backgroundUrl
string
可选
背景图 Url
smallIcons
string
可选
小图标
buttonCopy
string
可选
按钮文案
buttonJumpUrl
string
可选
点击按钮跳转的链接
iosNotify:iOS 通知消息对象
字段名
类型
选项
含义
badge
number
可选
角标
badgeType
number
可选
badge 类型
- 1:绝对值 不能为负数
- 2 增减(正数增加,负数减少),减到 0 以下会设置为 0
category
string
可选
APNs 的 category 字段,只有 IOS8 及以上系统才支持此参数推送
sound
string
可选
APNs 通知,通过这个字段指定声音,默认为 default(系统默认声音),如设置为空值则为静音。如设置为其他字符,则需要您的应用中配置了该声音才可以正常发声。
subtitle
string
可选
副标题
slientPush
number
可选
如果只携带 content-available: 1,不携带任何 badge,sound 和消息内容等参数, 则可以不打扰用户的情况下进行内容更新等操作即为“Silent Remote Notifications”
contentAvailable
number
可选
将该键设为 1 则表示有新的可用内容。带上这个键值,意味着你的 App 在后台启动了或恢复运行了,application:didReceiveRemoteNotification:fetchCompletionHandler:被调用了
mutableContent
number
可选
- 1 使用富文本
- 0 不设置
注:默认为 0,配合 attachmentType 和 attachment 使用
attachmentType
number
可选
富文本类型
- 0:无
- 1:图片
- 2:视频
- 3:音频
attachment
string
可选
ios 富文本内容
pushOperator:运营保障相关配置
字段名
类型
选项
含义
dropType
number
可选
运营保障消息修改类型,推荐使用专用接口进行操作
- 1:取消
- 2:替换
- 3:撤回
dropId
string
必填
推送任务的唯一 ID
pushForward:Link 相关打开配置
字段名
类型
选项
含义
url
string
可选
link 跳转 moblink 功能的的 uri
scheme
string
必填
scheme moblink 功能的的 scheme
schemeDataList
object []
可选
scheme 参数
例: [ { "key": "name", "value": "jason" }, { "key": "age", "value": 18 } ]
nextType
integer
可选
后续动作
- 0:打开首页
- 1:link 跳转
- 2:scheme 跳转
- 3:Intent
intentUrl
string
可选
Intent 页面地址
pushCallback:推送回调配置
字段名
类型
选项
含义
url
string
可选
回调地址点击查看详情
params
object
可选
JSON 对象自定义参数
例: { "key": "value" }
pushFactoryExtra:厂商特殊配置
huaweiExtra:华为厂商特殊配置
字段名
类型
选项
含义
importance
string
可选
消息类型
- LOW:资讯营销类
- NORMAL:服务与通讯类
注:资讯营销类的消息提醒方式为静默通知,仅在下拉通知栏展示。 服务与通讯类的消息提醒方式为锁屏+铃声+震动
category
string
可选
作用一:完成自分类权益申请后,用于标识消息类型,确定消息提醒方式,对特定类型消息加快发送,取值如下:
IM:即时聊天
VOIP:音视频通话
SUBSCRIPTION:订阅
TRAVEL:出行
HEALTH:健康
WORK:工作事项提醒
ACCOUNT:帐号动态
EXPRESS:订单 &物流
FINANCE:财务
DEVICE_REMINDER:设备提醒
SYSTEM_REMINDER:系统提示
MAIL:邮件
PLAY_VOICE:语音播报(仅透传消息支持)
MARKETING:内容推荐、新闻、财经动态、生活资讯、社交动态、调研、产品促销、功能推荐、运营活动(仅对内容进行标识,不会加快消息发送)
作用二:申请特殊权限后,用于标识高优先级透传场景,取值如下:
VOIP:音视频通话
PLAY_VOICE:语音播报
xiaomiExtra:小米厂商特殊配置
字段名
类型
选项
含义
channelId
string
可选
小米渠道 Id 适配定制化渠道
oppoExtra:OPPO 厂商特殊配置
字段名
类型
选项
含义
channelId
string
可选
OPPO 渠道 Id 适配定制化渠道
vivoExtra:VIVO 厂商特殊配置
字段名
类型
选项
含义
classification
int
可选
VIVO 消息类型
- 0:运营类型消息
- 1:系统类型消息
category
string
可选
二级分类,传值参见[userExtra:用户补充信息
字段名
类型
选项
含义
pushWorkDesc
string
可选
推送任务的解释说明,由用户设置
activityTask
integer
可选
活动任务
- 0:不是活动任务(默认)
- 1:是活动任务
activityWorkId
string
activityTask 为 1 时必传
活动 ID,不能超过 20 个字符,且唯一不可重复
加密示例
参数
{"source":"webapi","appkey":"2f2d7a68f8a40","pushTarget":{"target":1},"pushNotify":{"plats":[1],"content":"推送的内容","type":1}}9abee316611dd24f607feb9f2c496338
计算结果
sign -> eb276f35cf6480169b2d3e2e509db680
请求示例
响应示例
请求成功
{"status": 200,"res": {"batchId": "4bp4tw9ttc06xgch6o","fetched": null,"uninstalls": null,"closes": null,"notFounds": null},"error": null}
请求失败
{"status": 5801,"res": null,"error": "数据校验失败"}
响应参数
key
description
status
返回码
res
消息体,可从中获取本次推送的任务 ID
error
返回码描述
调用示例
推送广播
推送广播并附加参数
推送标签
推送别名
推送 RegisterID
自定义消息(透传消息)
Android 通知大图模式
Android 通知横幅模式
Android 通知自定义声音
音频文件放到项目 res/raw 目录下,只需传音频文件的文件名
跳转首页并传递附加参数
跳转到指定界面并且传递携带 scheme 数据
打开网页
频率限制
API 频率控制
每个 AppKey 在每分钟的访问请求次数有如下限制:
推送接口的接口频率限制,默认 500 次/分钟;
查询接口的接口频率限制,默认 300 次/分钟;
注:如有更高需求,可联系商务或技术支持调整相关接口频率限制。
消息推送条数限制
单推(Rid 推送或者别名推送):没有限制; 群体推送(智能标签推送):没有限制; 全部人群(广播):100 次/天,每分钟 1 次; 注:如有更高需求,可联系商务或技术支持调整相关接口频率限制。
批量推送
](https://dev.vivo.com.cn/documentCenter/doc/359>二级分类标准</a>中 category 说明<br><br>1、填写 category 后,可以不填写 classification、messageSort,但若填写 classification、messageSort,请保证 category 与 messageSort 或 classification 是正确对应关系,否则返回错误码 10097;<br><br>2、赋值请按照消息分类规则填写,且必须大写;若传入错误无效的值,否则返回错误码 10096;</td></tr></tbody></table><h3 id=)
[MobPush 还额外提供了批量推送接口,可以设置推送不同的 regid 和别名对应不同的推送内容,](https://dev.vivo.com.cn/documentCenter/doc/359>二级分类标准</a>中 category 说明<br><br>1、填写 category 后,可以不填写 classification、messageSort,但若填写 classification、messageSort,请保证 category 与 messageSort 或 classification 是正确对应关系,否则返回错误码 10097;<br><br>2、赋值请按照消息分类规则填写,且必须大写;若传入错误无效的值,否则返回错误码 10096;</td></tr></tbody></table><h3 id=)详情点击查看
返回码
返回码
描述
200
"成功"
4001
"请求缺少必要参数"
4002
"请求参数错误"
4003
"请求参数不完整"
4004
"数据解密失败"
4005
"数据校验失败"
4006
"通信会话已经过期或者不存在"
4007
"非法请求"
4008
"秘钥失效"
4009
"文本
4010
"文本
4011
"加密接口只支持 POST"
4012
"解密失败"
4013
"web 请求异常"
4014
"手机号码格式错误"
4015
"不可保存相同短信模板"
4016
"此短信模板不存在"
4017
"此 appkey 无短信模板"
4018
"此 appkey 无短信签名"
4019
"此 appkey 下已有签名"
4101
"appkey 已经加入黑名单"
4102
"该设备已经加入黑名单"
4103
"请求过于频繁"
4104
"请先加入 MobPush 产品"
4105
"设备 Id 相关参数错误"
4201
"没有可用的 tcp 节点"
4301
"IOS 设备缺少 device token 信息"
4302
"未找到对应设备信息"
4303
"别名字数超过限制,最长 40,UTF-8 编码"
4304
"别名格式不正确"
4305
"单个标签长度超过限制,最长 40,UTF-8 编码"
4306
"标签格式不正确"
4307
"定时推送需要设置时间"
4314
"请填写模拟发送内容"
4308
"发送内容超过限制"
4309
"缺少 AES KEY 信息"
4310
"未找到应用信息"
4311
"应用已经被禁用"
4312
"appkey 无效"
4313
"缺少 token 信息"
4314
"请求过于频繁"
4315
"大段文本内容超过限制"
4316
"收件箱内容超过限制"
4317
"收件箱条数超过限制"
4318
"未找到要替换的消息"
4319
"未找到要撤回的消息"
4320
"请求缺少必要参数"
4320
"回执消息为空"
4321
"TCP 标志消息为空"
4322
"离线回执消息为空"
4501
"设置 IP 地址格式不正确"
4502
"设置的包名不正确"
4503
"证书密码格式不正确"
4504
"选择的鉴权方式和提交信息不匹配"
4505
"填写的鉴权信息已经存在"
4506
"未筛选到发送对象"
4507
"当前推送任务不能修改"
4508
"未找到匹配的推送任务"
4509
"发送内容超过限制"
4510
"只能设置一分钟后的定时任务"
4511
"大段文本内容超过限制"
4512
"收件箱内容超过限制"
4513
"收件箱条数超过限制"
4514
"标题设置超过限制"
4515
"只能设置一个月内的定时任务"
4516
"分群名称不能超过 32 字符"
4516
"缺少用户分群 ID"
4517
"分群设置日期格式错误"
4518
"任务不属于当前用户"
4518
"厂商配置信息缺失"
4519
"厂商选择错误,请确定厂商参数信息"
4520
"请先进入 推送设置配置 android 包名"
4521
"测试比例超过范围"
4522
"未开通智能标签权限"
4523
"批量别名最大数量超过 1000"
4524
"批量 RegistrationIds 最大数量超过 1000"
4525
"标签不能为空"
4525
"批量标签最大数量超过 100"
4525
"标签组合限制值{1
4526
"智能标签不能为空"
4527
"别名不能为空且长度限制[1
4528
"RegisterIds 不能为空且长度限制[1
4529
"分群 id 不能为空"
4531
"推送内容不能为空"
4532
"定时任务时间限制"
4533
"安卓样式内容不能为空"
4540
"定时任务时间不能为空"
4541
"地理位置推送,地理位置信息未设置"
4543
"短信补量数据不能为空"
4544
"智能标签异常"
4551
"短信补量别名不能为空且长度限制[1
4552
"短信补量标签不能为空"
4552
"短信补量 RegisterIds 不能为空且长度限制[1
4553
"角标设置错误"
4554
"FCM 配置异常"
4555
"替换或者撤回需要传递 workId"
4556
"ADPush 模板为空"
4557
"WebApi 未开放智能标签推送"
4558
"FCM 远程锁异常"
4559
"运营保障推送任务不存在"
4560
"ABTest 任务不存在"
4561
"未知的短信签名"
4562
"未知的短信模板"
4563
"短信模板和前面不匹配"
5001
"服务端未知异常"
5002
"数据获取失败"
5003
"数据存储失败"
5004
"服务端繁忙"
5005
"请求的服务不支持"
5006
"数据加密失败"
5101
"设备存储参数错误"
5301
"没有可分配连接节点"
5302
"包含无效的 MessageId
5403
"设备已经被禁用"
5404
"缺少设备绑定信息"
5405
"标签数量超限
5406
"初始化信息失败"
5408
"workno 已经存在"
5409
"无推送目标设备"
5411
"设备数量不足"
5412
"AppSecret 秘钥错误"
5488
"非法操作"
5499
"数据更新失败"
5501
"服务器压力大"
4800
"请求头信息缺少 key 字段"
4801
"请求 IP 不匹配或者未设置"
4802
"应用未开启 MobPush 产品或者被禁用"
4803
"别名字数超过限制,最长 40,UTF-8 编码"
4804
"别名格式不正确"
4805
"单个标签长度超过限制,最长 40,UTF-8 编码"
4806
"标签格式不正确"
4807
"当前推送任务不能修改"
4809
"请求缺少必要参数"
4810
"请求过于频繁"
4811
"推送任务内容长度超限"
4812
"缺少推送内容"
4813
"缺少目标平台"
4814
"缺少目标人群"
4815
"缺少推送类型"
4816
"超过最大离线时间"
4817
"大段文本内容超过限制"
4818
"收件箱内容超过限制"
4819
"收件箱最多 5 条"
4820
"标题设置超过限制"
4821
"缺少用户分群 ID"
4822
"extra 的 key 值包含关键字"
4823
"一次不能超过 100 条"
4824
"离线时间非法"
4825
"离线推送时间范围只能 8:00-22:00 点,推送时间为当前时间+离线时间"
4826
"一次不能超过 1000 条"
4827
"dropType 字段错误"
4828
"任务未找到或统计未出
4839
"推送 Appkey 错误"
4033
"回调参数 url 格式错误"
评论