Push API
Push API 概述
Push API 是所有推送接口的统称
Push API 有多种推送目标,推送目标如下:
全量推送
标签推送
单设备推送
设备列表推送
单账号推送
账号列表推送
所有推送目标都采用相同的 URL 发起请求,URL:
https://openapi.xg.qq.com/v3/push/app
所有请求参数通过 JSON 封装上传给后台,后台通过请求参数区分不同的推送目标
调用地址
Push API 必要参数
推送必要参数指一条推送消息必需携带的参数
参数名
类型
是否必需
描述
audience_type
string
是
推送目标 1)all:全量推送 2)tag:标签推送 3)token:单设备推送 4)token_list:设备列表推送 5)account:单账号推送 6)account_list:账号列表推送
platform
string
是
客户端平台类型 1)android:安卓 2)ios:苹果
message
object
是
message_type
string
是
消息类型 1)notify:通知 2)message:透传消息/静默消息
environment
string
是(仅iOS平台使用)
用户指定推送环境,仅限iOS平台推送使用(默认为product) 1)product: 推送生产环境 2)dev: 推送开发环境
audience_type:推送目标
推送目标,表示一条推送可以被推送到哪些设备
Push API 提供了多种推送目标的,比如:全量、标签、单设备、设备列表、单账号、账号列表
推送目标
描述
必需参数及使用说明
all
全量推送
无
tag
标签推送
tag_list
1)推送 tag1 和 tag2 的设备
{“tags”:[“tag1”,”tag2”],”op”:”AND”}
2)推送 tag1 或 tag 的设备
{“tags”:[“tag1”,“tag2”],”op”:“OR”}
3) 标签列表不能超过512个字符
token
单设备推送
token_list
1)如果该参数包含多个token 只会推送第一个token
2)格式eg:[“token1”]
3)token字符串长度不能超过64
token_list
设备列表群推
token_list
1)最多1000 个token
2)格式eg:[“token1”,”token2”]
3)token字符串长度不能超过64
push_id
1)第一次推送该值填0,系统会创建对应的推送任务,并且返回pushid:123
2)后续推送push_id 填123(同一个文案)表示使用与123 id 对应的文案进行推送
account
单账号推送
account_list
1)该参数有多个账号时,仅推送第一个账号
2)格式eg:[“account1”]
account_list
账号列表群推
account_list
1)最多1000 个account2. 格式eg:[“account1”,”account2”]
push_id
1)第一次推送该值填0,系统会创建对应的推送任务,并且返回pushid:123
2)后续推送push_id 填123(同一个文案)表示使用与123 id 对应的文案进行推送
全量推送:推送给全部设备
标签推送:推送给同时设置了"tag1"和”tag2“标签的设备
单设备推送:推送给token为"token1"的设备
设备列表推送,推送给token为"token1"和"token2"的设备
单账号推送:推送给账号为"account1"的设备
账号列表推送:推送账号为"account1"和"account2"的设备
platform:推送平台
当前支持 Android、iOS 两个平台的推送
其关键字分别为:"android", "ios"
推送到安卓平台:
推送到iOS平台:
message_type:消息体类型
针对不同平台,消息类型稍有不同,具体参照下表:
消息类型
描述
支持平台
特性说明
notify
通知栏消息
AndroidiOS
通知栏展示消息
message
透传消息/静默消息
Android(透传消息) iOS(静默消息)
通知栏不展示消息
message:消息体
消息体,即下发到客户端的消息
Push API 对 iOS 和 Android 两个平台的消息有不同处理,需要分开来实现对应平台的推送消息,推送的消息体是 JSON格式
Android普通消息
Android平台具体字段如下表:
字段名
类型
默认值
必需
参数描述
title
string
无
是
消息标题
content
string
无
是
消息内容
accept_time
array
无
否
消息将在哪些时间段允许推送给用户,建议小于10个,不能为空
xg_media_resources
string
无
否
富媒体元素地址,建议小于5个 (仅限SDK4.2.0及以上版本使用)
n_id
int
0
否
通知消息对象的唯一标识(只对信鸽通道生效) 1)大于0:会覆盖先前相同id的消息 2)等于0:展示本条通知且不影响其他消息 3)等于-1:将清除先前所有消息,仅展示本条消息
builder_id
int
0
否
本地通知样式标识
ring
int
1
否
是否有铃声 1)0:没有铃声 1)1:有铃声
ring_raw
string
无
否
指定Android工程里raw目录中的铃声文件名,不需要后缀名
vibrate
int
1
否
是否使用震动 1)0:没有震动 2)1:有震动
lights
int
1
否
是否使用呼吸灯 1)0:不使用呼吸灯 2)1:使用呼吸灯
clearable
int
1
否
通知栏是否可清除
icon_type
int
0
否
通知栏图标是应用内图标还是上传图标 1)0:应用内图标 2)1:上传图标
icon_res
string
无
否
应用内图标文件名或者下载图标的url地址
style_id
int
1
否
设置是否覆盖指定编号的通知样式
small_icon
string
无
否
消息在状态栏显示的图标,若不设置,则显示应用图标
action
JSON
有
否
设置点击通知栏之后的行为,默认为打开app
custom_content
JSON
无
否
用户自定义的键值对
完整的消息示例如下:
iOS普通消息
iOS平台具体字段如下表:
字段名
类型
默认值
必需
参数描述
aps
JSON
无
是
custom
string/JSON
无
否
自定义下发的参数
xg
string
无
否
系统保留key,应避免使用
完整的消息示例如下:
Android透传消息
透传消息,Android平台特有,即不显示在手机通知栏中的消息,可以用来实现让用户无感知的向App下发带有控制性质的消息
Android平台具体字段如下表:
字段名
类型
默认值
是否必需
参数描述
title
string
无
是
消息标题
content
string
无
是
消息内容
custom_content
JSON
无
否
自定义内容
accept_time
array
无
否
消息将在哪些时间段允许推送给用户,建议小于10个
具体完整示例:
iOS静默消息
静默消息,iOS平台特有,类似Android中的透传消息,消息不展示,当静默消息到达终端时,iOS会在后台唤醒App一段时间(小于30s),让App来处理消息逻辑
具体字段如下表:
字段名
类型
默认值
是否必要
参数描述
aps
JSON
无
是
custom
string/JSON
无
否
自定义下发的参数
xg
string
无
否
系统保留key,应避免使用
具体完整示例:
Push API 可选参数
Push API 可选参数是除了 audience_type
、platform
、message_type
、message
以外,可选的高级参数
参数名
类型
必需
默认值
描述
expire_time
int
否
259200(72小时)
消息离线存储时间(单位为秒),最长72小时 1)若expire_time=0,则表示实时消息 2)若expire_time大于0且小于800s,则系统会重置为800s 3)若expire_time>=800s,按实际设置时间存储,最长72小时 4)设置的最大值不得超过2147483647,否则会导致推送失败
send_time
string
否
当前系统时间
指定推送时间 1)格式为yyyy-MM-DD HH:MM:SS 2)若小于服务器当前时间,则会立即推送 3)仅全量推送和标签推送支持此字段
multi_pkg
bool
否
false
多包名推送 1)当app存在多个不同渠道包(例如应用宝、豌豆荚等),推送时如果是希望手机上安装任何一个渠道的app都能收到消息那么该值需要设置为true
loop_times
int
否
0
循环任务重复次数 1)仅支持全推、标签推 2)建议取值[1, 15]
loop_interval
int
否
0
循环执行消息下发的间隔 1)必须配合loop_times使用 2)以天为单位,取值[1, 14] 3)loop_times和loop_interval一起表示消息下发任务的循环规则
badge_type
int
否
-1
用户设置角标数字,仅限iOS 平台使用,放在aps字段内 1) -1:角标数字不变 2) -2:角标数字自动加1 3) >=0:设置「自定义」角标数字
stat_tag
string
否
无
统计标签,用于聚合统计 使用场景(示例):现在有一个活动id:active_picture_123,需要给10000个设备通过单推接口(或者列表推送等推送形式)下发消息,同时设置该字段为active_picture_123,推送完成之后可以使用v3统计查询接口,根据该标签active_picture_123 查询这10000个设备的实发、抵达、展示、点击数据
seq
int64_t
否
0
接口调用时,在应答包中信鸽会回射该字段,可用于异步请求 使用场景:异步服务中可以通过该字段找到server端返回的对应应答包
tag_list
object
仅标签推送必需
无
1)推送 tag1 和 tag2 的设备:{“tags”:[“tag1”,”tag2”],”op”:”AND”} 2)推送 tag1 或 tag2 的设备: {“tags”:[“tag1”,“tag2”],”op”:“OR”}
account_list
array
单账号推送、账号列表推送时必需
无
若单账号推送 1)要求 audience_type=account 2)参数格式:[“account1”] 若账号列表推送 1)参数格式:[“account1”,”account2”] 2)最多1000 个account
account_push_type
int
单账号推送时可选
0
1) 0: 往单个账号的最新的device上推送信息 2) 1: 往单个账号关联的所有device设备上推送信息
account_type
int
单账号推送时可选
0
1)账号类型,参考后面账号说明 2)必须与账号绑定时设定的账号类型一致
token_list
array
单设备推送、设备列表推送时必需
无
若单设备推送 1)要求 audience_type=token 2)参数格式:[“token1”] 若设备列表推送 1)参数格式:[“token1”,”token2”] 2)最多 1000 个 token
push_id
string
账号列表推送、设备列表推送时必需
无
账号列表推送和设备列表推送时,第一次推送该值填0,系统会创建对应的推送任务,并且返回对应的pushid:123,后续推送push_id填123(同一个文案)表示使用与123 id 对应的文案进行推送。(注:文案的有效时间由前面的expire_time 字段决定)
Push API应答参数
字段名
类型
是否必填
注释
seq
int64_t
是
与请求包一致(如果请求包是非法json该字段为0)
push_id
string
是
推送id
ret_code
int32_t
是
错误码,详细参照错误码对照表
environment
string
是
用户指定推送环境,仅支持iOS product: 生产环境 dev: 开发环境
err_msg
string
否
请求出错时的错误信息
result
string
否
请求正确时,若有额外数据要返回,则结果封装在该字段的json中,若无额外数据,则可能无此字段
Push API 请求完整示例
Android标签推送请求消息
标签推送应答消息
iOS单设备推送请求消息
单设备推送应答消息
账号类型
账号类型是客户端调用SDK接口绑定,类型如下表所示:
账号类型
含义
0
未知
1
手机号
2
邮箱
1000
微信openid
1001
qq openid
1002
新浪微博
1003
支付宝
1004
淘宝
1005
豆瓣
1006
1007
1008
1009
百度
1010
京东
1011
linkin
1999
其他
2000
游客登录
2001以上
用户自定义
错误码
信鸽REST API接口较多,开发者使用过程中不可避难会遇到各种问题,这里提供了常见的错误码释义,对应着是通用基础返回值中的ret_code字段的可能值
错误码
含义
10100
系统繁忙请稍后重试!
10101
系统繁忙请稍后重试!
10102
缺少参数请检查后重试
10103
参数值非法,请检查后重试
10104
鉴权未通过,请检查secret key!
10105
证书无效!
10106
当前推送类型不支持多平台推送!
10107
消息体是非法json 格式
10108
内部错误,请稍候重试!
10109
内部错误,请稍候重试!
10110
设备未注册!
10111
内部错误,请稍候重试!
10112
内部错误,请稍候重试!
10113
内部错误,请稍候重试!
10114
内部错误,请稍候重试!
10115
帐号不能为空,帐号为空!
10116
帐号不存在
10117
推送内容太大
10201
创建推送任务失败,请稍后重试!
10202
推送消息内容转换APNs 失败!
10203
创建推送任务失败,请稍后重试!
10204
推送失败,请稍后重试!
10205
推送任务过期,请检查!
10206
获取消息副本失败,请稍后重试!
10207
获取消息副本失败,请稍后重试!
10301
帐号列表推送失败,请稍后重试!
10302
帐号列表推送部分失败,请检查部分账号是否有绑定设备!
10303
帐号列表推送全部失败,请检查账号是否有绑定设备!
10304
token 列表推送部分失败,检查部分设备是否有正常注册!
10305
token 列表推送全部失败,请检查设备是否有正常注册!
10401
内部错误,请稍候重试!
10402
内部错误,请稍候重试!
10403
内部错误,请稍候重试!
10404
内部错误,请稍候重试!
10405
内部错误,请稍候重试!
10406
内部错误,请稍候重试!
10407
内部错误,请稍候重试!
10501
内部错误,请稍候重试!
10502
内部错误,请稍候重试!
10503
内部错误,请稍候重试!
10504
内部错误,请稍候重试!
10505
内部错误,请稍候重试!
10506
内部错误,请稍候重试!
10507
内部错误,请稍候重试!
10601
内部错误,请稍候重试!
10602
内部错误,请稍候重试!
10603
内部错误,请稍候重试!
10604
内部错误,请稍候重试!
10605
内部错误,请稍候重试!
10606
app 未注册,请注册后重试!
10701
内部错误,请稍候重试!
10702
内部错误,请稍候重试!
10707
内部错误,请稍候重试!
10708
内部错误,请稍候重试!
10709
内部错误,请稍候重试!
10710
内部错误,请稍候重试!
10711
内部错误,请稍候重试!
10712
内部错误,请稍候重试!
10713
内部错误,请稍候重试!
其他
未知错误,请稍后重试!
Last updated
Was this helpful?