本文档主要介绍个推开放平台公共请求参数和公共返回参数
以下参数是调用每个接口都需要使用的参数
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
token | String | 是 | 无 | 接口访问凭据,获取方式请参考获取鉴权token |
以下参数格式为每个接口返回的数据的通用格式。
名称 | 类型 | 描述 |
---|---|---|
code | Number | 成功或失败code码,详细含义见业务返回码说明 |
msg | String | 失败时返回此说明 |
data | Json | 详见接口说明 |
推送消息体示例(具体含义请见推送API):
{
"request_id":"请填写10到32位的id",
"audience":"all",
"settings":{
"ttl":3600000,
"strategy":{
"default":1,
"ios":4,
"st":4
}
},
"push_message":{
"notification":{
"title":"请填写标题",
"body":"请填写内容",
"click_type":"url",
"url":"https://www.json.cn/"
}
},
"push_channel":{
"android":{
"ups":{
"notification":{
"title":"请填写android标题",
"body":"请填写android内容",
"click_type":"url",
"url":"https://xxx"
}
}
},
"ios":{
"type":"notify",
"payload":"自定义消息",
"aps":{
"alert":{
"title":"请填写ios标题",
"body":"请填写ios内容"
},
"content-available":0
},
"auto_badge":"+1"
}
}
}
推送目标用户,表示一条推送将要被推送到哪些用户列表。设置目标用户的方式:cid、别名(alias),tag等等。
注意:audience
的参数选择根据请求url决定,与请求url不匹配时会报错,比如:选择接口为/push/single/cid,但audience选择alias,此时推送失败;
参数 | 类型 | 描述 |
---|---|---|
cid | String Array | 根据cid选择推送目标用户时使用 |
alias | String Array | 根据别名选择推送目标用户时使用,绑定别名请参考接口 |
fast_custom_tag | String | 为用户自定义标签,根据fast_custom_tag 选择推送用户时使用,绑定标签请参考接口 |
tag | Json Array | tag 指群推接口的用户筛选条件(包含多种类型条件:phone_type 手机类型; region 省市; custom_tag 用户标签),详细格式见接口中参数说明 |
all | String | 选择推送应用的所有用户 |
示例(非all
示例,以下参数只能选择一个):
{
"audience":{
"cid":[""],
"alias":[""],
"fast_custom_tag":"",
"tag":[{
"key":"phone_type",
"values":[
"android"
],
"opt_type":"and"
}]
}
}
示例(all
,推送所有用户):
{
"audience": "all"
}
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
ttl | Number | 否 | 1小时 | 消息离线时间设置,单位毫秒,-1表示不设离线,-1 ~ 3 * 24 * 3600 * 1000(3天)之间 |
strategy | Json | 否 | {"strategy":{"default":1}} |
厂商通道策略,详细内容见strategy |
speed | Number | 否 | 0 | 定速推送,例如100,个推控制下发速度在100条/秒左右,0表示不限速 |
schedule_time | Number | 否 | 无 | 定时推送时间,格式:毫秒时间戳,此功能需要开通VIP,如需开通请联系 lieg@getui.com |
示例:
{
"ttl": 3600,
"strategy": {
"default": 1,
"ios": 2
},
"speed": 100,
"schedule_time": 1591794372930
}
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
default | Number | 否 | 1 | 默认所有通道的策略选择1-4 1: 表示该消息在用户在线时推送个推通道,用户离线时推送厂商通道; 2: 表示该消息只通过厂商通道策略下发,不考虑用户是否在线; 3: 表示该消息只通过个推通道下发,不考虑用户是否在线; 4: 表示该消息优先从厂商通道下发,若消息内容在厂商通道代发失败后会从个推通道下发。 其中名称可填写: ios 、st 、hw 、xm 、vv 、mz 、op ,如有疑问可联系邮箱 lieg@getui.com。 |
ios | Number | 否 | 无 | ios通道策略1-4,表示含义同上,要推送ios通道,需要在个推开发者中心上传ios证书,建议填写2或4,否则可能会有消息不展示的问题 |
st | Number | 否 | 无 | 通道策略1-4,表示含义同上,需要开通st厂商使用该通道推送消息 |
... | Number | 否 | 无 | 通道策略1-4,表示含义同上 |
{
"strategy":{
"default":1,
"ios":4,
"st":1
}
}
通知消息(notification),仅支持安卓系统,iOS系统不展示个推通道下发的通知消息
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
duration | String | 否 | 无 | 手机端通知展示时间段,格式为毫秒时间戳段,两个时间的时间差必须大于10分钟,例如:"1590547347000-1590633747000" |
notification | Json | 否 | 无 | 通知消息内容,仅支持安卓系统,iOS系统不展示个推通知消息,与transmission 、revoke 三选一,都填写时报错 |
transmission | String | 否 | 无 | 纯透传消息内容,安卓和iOS均支持,与notification 、revoke 三选一,都填写时报错,长度 ≤ 3072 |
revoke | Json | 否 | 无 | 撤回消息时使用(仅支持撤回个推通道消息),与notification 、transmission 三选一,都填写时报错(消息撤回请勿填写策略参数) |
notification
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
title | String | 是 | 无 | 通知消息标题,长度 ≤ 50 |
body | String | 是 | 无 | 通知消息内容,长度 ≤ 256 |
big_text | String | 否 | 无 | 长文本消息内容,通知消息+长文本样式,与big_image 二选一,两个都填写时报错,长度 ≤ 512 |
big_image | String | 否 | 无 | 大图的URL地址,通知消息+大图样式, 与big_text 二选一,两个都填写时报错,长度 ≤ 1024 |
logo | String | 否 | 无 | 通知的图标名称,包含后缀名(需要在客户端开发时嵌入),如“push.png”,长度 ≤ 64 |
logo_url | String | 否 | 无 | 通知图标URL地址,长度 ≤ 256 |
channel_id | String | 否 | Default | 通知渠道id,长度 ≤ 64 |
channel_name | String | 否 | Default | 通知渠道名称,长度 ≤ 64 |
channel_level | Number | 否 | 3 | 设置通知渠道重要性(可以控制响铃,震动,浮动,闪灯等等) android8.0以下 0,1,2:无声音,无振动,不浮动 3:有声音,无振动,不浮动 4:有声音,有振动,有浮动 android8.0以上 0:无声音,无振动,不显示; 1:无声音,无振动,锁屏不显示,通知栏中被折叠显示,导航栏无logo; 2:无声音,无振动,锁屏和通知栏中都显示,通知不唤醒屏幕; 3:有声音,无振动,锁屏和通知栏中都显示,通知唤醒屏幕; 4:有声音,有振动,亮屏下通知悬浮展示,锁屏通知以默认形式展示且唤醒屏幕; |
click_type | String | 是 | 无 | 点击通知后续动作, 目前支持以下后续动作, intent :打开应用内特定页面,url :打开网页地址,payload :自定义消息内容启动应用,payload_custom :自定义消息内容不启动应用,startapp :打开应用首页,none :纯通知,无后续动作 |
intent | String | click_type 为intent时必填 |
无 | 点击通知打开应用特定页面,长度 ≤ 2048; 示例:intent:#Intent;component=你的包名/你要打开的 activity 全路径;S.parm1=value1;S.parm2=value2;end intent生成请参考 |
url | String | click_type 为url时必填 |
无 | 点击通知打开链接,长度 ≤ 1024 |
payload | String | click_type 为payload/payload_custom时必填 |
无 | 点击通知加自定义消息,长度 ≤ 3072 |
notify_id | Number | 否 | 无 | 覆盖任务时会使用到该字段,两条消息的notify_id 相同,新的消息会覆盖老的消息,范围:0-2147483647 |
ring_name | String | 否 | 无 | 自定义铃声,请填写文件名,不包含后缀名(需要在客户端开发时嵌入),个推通道下发有效 客户端SDK最低要求 2.14.0.0 |
badge_add_num | Number | 否 | 无 | 角标, 必须大于0, 个推通道下发有效 此属性目前仅针对华为 EMUI 4.1 及以上设备有效 角标数字数据会和之前角标数字进行叠加; 举例:角标数字配置1,应用之前角标数为2,发送此角标消息后,应用角标数显示为3。 客户端SDK最低要求 2.14.0.0 |
revoke
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
old_task_id | String | 是 | 无 | 需要撤回的taskId |
force | boolean | 否 | 无 | 在没有找到对应的taskId ,是否把对应appId 下所有的通知都撤回 |
示例:
通知消息:
{
"push_message":{
"duration":"1590547347000-1590633747000",
"notification":{
"title":"请填写你的通知标题",
"body":"请填写你的通知内容",
"big_text":"请填写你的通知长文本",
"logo":"logo.png",
"logo_url":"http://xxxx/a.png",
"channel_id":"请填写你的channel_id",
"channel_name":"请填写你的channel_name",
"channel_level":3,
"notify_id":1234,
"click_type":"intent",
"intent":"intent:#Intent;action=;end"
}
}
}
透传消息:
{
"push_message":{
"transmission":"请填写你的透传消息内容"
}
}
撤回消息:
{
"push_message":{
"revoke": {
"old_task_id": "xxx",
"force": false
}
}
}
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
ios | Json | 否 | 无 | ios通道推送消息内容 |
android | Json | 否 | 无 | android通道推送消息内容 |
具体参数含义详见苹果APNs文档
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
type | String | 否 | notify默认通知消息 | voip:voip语音推送,notify:apns通知消息 |
aps | Json | 否 | 无 | 推送通知消息内容 |
auto_badge | String | 否 | 无 | 用于计算icon上显示的数字,还可以实现显示数字的自动增减,如“+1”、 “-1”、 “1” 等,计算结果将覆盖badge |
payload | String | 否 | 无 | 增加自定义的数据 |
multimedia | Json Array | 否 | 无 | 多媒体设置 |
apns-collapse-id | String | 否 | 无 | 使用相同的apns-collapse-id 可以覆盖之前的消息 |
aps
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
alert | Json | 否 | 无 | 通知消息 |
content-available | Number | 否 | 0 | 0表示普通通知消息(默认为0); 1表示静默推送(无通知栏消息),静默推送时不需要填写其他参数。 苹果建议1小时最多推送3条静默消息 |
sound | String | 否 | 无 | 通知铃声文件名,如果铃声文件未找到,响铃为系统默认铃声。 无声设置为“com.gexin.ios.silence”或不填 |
category | String | 否 | 无 | 在客户端通知栏触发特定的action和button显示 |
thread-id | String | 否 | 无 | ios的远程通知通过该属性对通知进行分组,仅支持iOS 12.0以上版本 |
alert
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
title | String | 否 | 无 | 通知消息标题 |
body | String | 否 | 无 | 通知消息内容 |
action-loc-key | String | 否 | 无 | (用于多语言支持)指定执行按钮所使用的Localizable.strings |
loc-key | String | 否 | 无 | (用于多语言支持)指定Localizable.strings文件中相应的key |
loc-args | String Array | 否 | 无 | 如果loc-key中使用了占位符,则在loc-args中指定各参数 |
launch-image | String | 否 | 无 | 指定启动界面图片名 |
title-loc-key | String | 否 | 无 | (用于多语言支持)对于标题指定执行按钮所使用的Localizable.strings,仅支持iOS8.2以上版本 |
title-loc-args | String Array | 否 | 无 | 对于标题,如果loc-key中使用的占位符,则在loc-args中指定各参数,仅支持iOS8.2以上版本 |
subtitle | String | 否 | 无 | 通知子标题,仅支持iOS8.2以上版本 |
subtitle-loc-key | String | 否 | 无 | 当前本地化文件中的子标题字符串的关键字,仅支持iOS8.2以上版本 |
subtitle-loc-args | String Array | 否 | 无 | 当前本地化子标题内容中需要置换的变量参数 ,仅支持iOS8.2以上版本 |
multimedia说明:
该字段为Array类型,最多可设置3个子项,每个参数定义如下所示:
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
url | String | 是 | 无 | 多媒体资源地址 |
type | Number | 是 | 无 | 资源类型(1.图片,2.音频,3.视频) |
only_wifi | Boolean | 否 | false | 是否只在wifi环境下加载,如果设置成true,但未使用wifi时,会展示成普通通知 |
示例:
voip语音推送:
{
"ios":{
"type":"voip",
"payload":"自定义消息"
}
}
apns通知消息
{
"ios":{
"type":"notify",
"payload":"自定义消息",
"aps":{
"alert":{
"title":"通知标题",
"body":"通知内容"
},
"content-available":0,
"sound":"com.gexin.ios.silence",
"category":"ACTIONABLE"
},
"auto_badge":"+1",
"multimedia": [{
"url": "https://xxx",
"type": 1,
"only_wifi": false
}]
}
}
apn静默推送 可参考苹果APNs文档
{
"ios":{
"aps":{
"content-available":1
},
"payload": "自定义消息"
}
}
更多Android厂商参数,可以参考多厂商参数文档
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
ups | Json | 否 | 无 | android厂商通道推送消息内容 |
ups
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
notification | Json | 否 | 无 | 通知消息内容,与transmission 二选一,两个都填写时报错 |
transmission | String | 否 | 无 | 透传消息内容,与notification 二选一,两个都填写时报错,长度 ≤ 3072 |
options | Json | 否 | 无 | 第三方厂商扩展内容 |
notification
名称 | 类型 | 是否必需 | 默认值 | 描述 |
---|---|---|---|---|
title | String | 是 | 无 | 通知栏标题(长度建议取最小集) 小米:title长度限制为50字 华为:title长度限制40字 魅族:title长度限制32字 OPPO:title长度限制32字 VIVO:title长度限制40英文字符 |
body | String | 是 | 无 | 通知栏内容(长度建议取最小集) 小米:content长度限制128字 华为:content长度小于1024字 魅族:content长度限制100字 OPPO:content长度限制200字 VIVO:content长度限制100个英文字符 |
click_type | String | 是 | 无 | 点击通知后续动作, 目前支持以下后续动作, intent :打开应用内特定页面(厂商都支持),url :打开网页地址(厂商都支持,华为要求https协议),payload :自定义消息内容启动应用(华为和oppo不支持,其他厂商支持),startapp :打开应用首页(厂商都支持) |
intent | String | click_type 为intent时必填 |
无 | 点击通知打开应用特定页面,intent格式必须正确且不能为空,长度 ≤ 2048; 示例:intent:#Intent;component=你的包名/你要打开的 activity 全路径;S.parm1=value1;S.parm2=value2;end intent生成请参考 |
url | String | click_type 为url时必填 |
无 | 点击通知打开链接,长度 ≤ 1024 |
payload | String | click_type 为payload时必填 |
无 | 点击通知加自定义消息,长度 ≤ 3072 |
notify_id | Number | 否 | 无 | 消息覆盖使用,两条消息的notify_id 相同,新的消息会覆盖老的消息,范围:0-2147483647 |
options
{
"constraint":{"key": "value"}
}
名称 | 类型 | 描述 |
---|---|---|
constraint | String | 扩展内容对应厂商通道设置如:ALL,HW,XM,VV,OP,MZ,ST |
key | String | 厂商内容扩展字段 |
value | 具体数据类型 | value的设置根据key值决定 |
详细内容见多厂商参数
通知示例:
{
"android":{
"ups":{
"notification":{
"title":"厂商通知标题",
"body":"厂商通知内容",
"click_type":"url",
"url":"https://xxx",
"notify_id":1234
},
"options":{
"ALL":{
"channel":"default"
},
"HW":{
"badgeAddNum":1,
"badgeClass":"com.getui.demo.GetuiSdkDemoActivity",
"icon":"https://xxx"
},
"OP":{
"app_message_id":"xxx"
},
"VV":{
"classification":0
},
"XM":{
"sound_uri": "android.resource://com.pp.infonew/ring001"
}
}
}
}
}
透传示例:
{
"android":{
"ups":{
"transmission":"厂商透传消息",
"options":{
"HW":{
"/message/android/urgency":"HIGH",
"/message/android/category":"PLAY_VOICE"
}
}
}
}
}
以上文档对您是否有帮助?