推送 API
这是 Push API 最近的版本。
相比于 API v2 版本,v3 版本的改进为:
- 完全基于 https 且支持 http2,不再提供 http 访问;
- 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成,比如:curl,浏览器插件等;
- 推送内容完全使用 JSON 的格式;
- 支持的功能有所改进:支持多 tag 的与或操作;可单独发送通知或者自定义消息,也可同时推送通知与自定义消息;windows phone 目前只有通知。
推送概述
功能说明
向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。
调用地址
请求示例
curl --insecure -X POST -v https://api.jpush.cn/v3/push -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '{"platform":"all","audience":"all","notification":{"alert":"Hi,JPush !","android":{"extras":{"android-key1":"android-value1"}},"ios":{"sound":"sound.caf","badge":"+1","extras":{"ios-key1":"ios-value1"}}}}'
> POST /v3/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
返回示例
< HTTP/1.1 200 OK
< Content-Type: application/json
{"sendno":"18","msg_id":"1828256757"}
调用验证
HTTP Header(头)里加一个字段(Key/Value 对):
Authorization: Basic base64_auth_string
其中 base64_auth_string 的生成算法为:base64(appKey:masterSecret)
即,对 appKey 加上冒号,加上 masterSecret 拼装起来的字符串,再做 base64 转换。
推送对象
一个推送对象,以 JSON 格式表达,表示一条推送相关的所有信息。
关键字 | 选项 | 含义 |
---|---|---|
platform | 必填 | 推送平台设置 |
audience | 必填 | 推送设备指定 |
notification | 可选 | |
message | 可选 | |
notification_3rd | 可选 | |
sms_message | 可选 | 短信渠道补充送达内容体 |
options | 可选 | 推送参数 |
callback | 可选 | 回调参数 |
cid | 可选 | 用于防止 api 调用端重试造成服务端的重复推送而定义的一个标识符。 |
示例与说明
{
"cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
"platform": "all",
"audience": {
"tag": [
"深圳",
"北京"
]
},
"notification": {
"android": {
"alert": "Hi, JPush!",
"title": "Send to Android",
"builder_id": 1,
"large_icon": "http://www.jiguang.cn/largeIcon.jpg",
"intent": {"url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",},
"extras": {"newsid": 321}
},
"ios": {
"alert": "Hi, JPush!",
"sound": "default",
"badge": "+1",
"thread-id": "default",
"extras": {"newsid": 321}
},
"voip": { // 此功能需要 JPush iOS SDK v3.3.2 及以上版本支持
"key": "value" // 任意自定义 key/value 对,api 透传下去
},
"quickapp": {
"alert": "Hi, JPush!",
"title": "Send to QuickApp",
"page": "/page1"
}
},
"message": {
"msg_content": "Hi,JPush",
"content_type": "text",
"title": "msg",
"extras": {"key": "value"}
},
"sms_message":{
"temp_id":1250,
"temp_para":{"code":"123456"},
"delay_time":3600,
"active_filter":false
},
"options": {
"time_to_live": 60,
"apns_production": false,
"apns_collapse_id":"jiguang_test_201706011100"
},
"callback": {
"url":"http://www.bilibili.com",
"params":{
"name":"joe",
"age":26
},
"type":3
}
}
platform:推送平台
JPush 当前支持 Android, iOS, QuickApp,Windows Phone 四个平台的推送。其关键字分别为:"android", "ios", "quickapp","winphone"。
如果目标平台为 iOS 平台,推送 Notification 时需要在 options 中通过 apns_production 字段来设定推送环境。True 表示推送生产环境,False 表示要推送开发环境; 如果不指定则为推送生产环境;一次只能推送给一个环境。
推送到所有平台:
{"platform" : "all"}
指定特定推送平台:
{"platform" : ["android", "ios","quickapp"] }
audience:推送目标
推送设备对象,表示一条推送可以被推送到哪些设备列表。确认推送设备对象,JPush 提供了多种方式,比如:别名、标签、注册 ID、分群、广播等。
all
如果要发广播(全部设备),则直接填写 “all”。
基于业务优化的需求,极光将于 3 月 10 日对「广播推送」的频率进行限制,调整为 10 次每天,超过调用限制时将返回报错码 2008,官网控制台将与 Push API 同步调整。
注意:本次调整仅限制广播,对广播外的推送不影响。如广播推送需更高频率,请 联系商务,详情请阅读 公告。
推送目标
广播外的设备选择方式,有如下几种:
关键字 | 类型 | 含义 | 说明 | 备注 |
---|---|---|---|---|
tag | JSON Array | 标签 OR | 数组。多个标签之间是 OR 的关系,即取并集。 | |
tag_and | JSON Array | 标签 AND | 数组。多个标签之间是 AND 关系,即取交集。 | |
tag_not | JSON Array | 标签 NOT | 数组。多个标签之间,先取多标签的并集,再对该结果取补集。 | |
alias | JSON Array | 别名 | 数组。多个别名之间是 OR 关系,即取并集。 | |
registration_id | JSON Array | 注册 ID | 数组。多个注册 ID 之间是 OR 关系,即取并集。 | |
segment | JSON Array | 用户分群 ID | 在页面创建的用户分群的 ID。定义为数组,但目前限制一次只能推送一个。 | 目前限制是一次只能推送一个。 |
abtest | JSON Array | A/B Test ID | 在页面创建的 A/B 测试的 ID。定义为数组,但目前限制是一次只能推送一个。 | 目前限制一次只能推送一个。 |
以上几种类型至少需要有其一。如果值数组长度为 0,表示该类型不存在。
这几种类型可以并存,多项的隐含关系是 AND,即取几种类型结果的交集。
例如:
"audience" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }
先计算 "tag" 字段的结果 tag1 或 tag2=A
;
再计算 "tag_and" 字段的结果 tag3 且 tag4=B
;
再计算 "tag_not" 字段的结果 非 (tag5 或 tag6)=C
;
"audience" 的最终结果为 A 且 B 且 C
。
示例
- 推送给全部(广播):
{
"platform": "all",
"audience" : "all",
"notification" : {
"alert" : "Hi, JPush!",
"android" : {},
"ios" : {"extras" : { "newsid" : 321}
}
}
}
- 推送给多个标签(只要在任何一个标签范围内都满足):在深圳、广州、或者北京
{
"audience" : {"tag" : [ "深圳", "广州", "北京"]
}
}
- 推送给多个标签(需要同时在多个标签范围内):在深圳并且是“女”
{
"audience" : {"tag_and" : [ "深圳", "女"]
}
}
- 推送给多个别名:
{
"audience" : {"alias" : [ "4314", "892", "4531"]
}
}
- 推送给多个注册 ID:
{
"audience" : {"registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31"]
}
}
- 可同时推送指定多类推送目标:在深圳或者广州,并且是 “女” “会员”
{
"audience" : {"tag" : [ "深圳", "广州"],
"tag_and" : ["女", "会员"]
}
}
notification:通知
“通知”对象,是一条推送的实体内容对象之一(另一个是“消息”),是会作为“通知”推送到客户端的。
其下属属性包含 4 种,3 个平台属性,以及一个 "alert" 属性。
alert
通知的内容在各个平台上,都可能只有这一个最基本的属性 "alert"。
这个位置的 "alert" 属性(直接在 notification 对象下),是一个快捷定义,各平台的 alert 信息如果都一样,则可不定义。如果各平台有定义,则覆盖这里的定义。
{
"notification" : {"alert" : "Hello, JPush!"}
}
上面定义的 notification 对象,将被推送到 "platform" 指定的多个平台,并且其通知 alert 信息都一样。
android
Android 平台上的通知,JPush SDK 按照一定的通知栏样式展示。
支持的字段有:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | string | 必填 | 通知内容 | |
title | string | 可选 | 通知标题 | |
builder_id | int | 可选 | 通知栏样式 ID | |
channel_id | String | 可选 | android 通知 channel_id | |
priority | int | 可选 | 通知栏展示优先级 | 默认为 0,范围为 -2~2。 |
category | string | 可选 | 通知栏条目过滤或排序 | 完全依赖 rom 厂商对 category 的处理策略。 |
style | int | 可选 | 通知栏样式类型 | 用来指定通知栏样式类型,默认为 0。 |
alert_type | int | 可选 | 通知提醒方式 | 可选范围为 -1~7 ,默认按照 -1 处理。 即0111二进制,左数第二位代表 light,第三位代表 vibrate,第四位代表 sound。 0:不生效,1:生效。如: Notification.DEFAULT_ALL = -1 ,Notification.DEFAULT_SOUND = 1, Notification.DEFAULT_VIBRATE = 2, Notification.DEFAULT_LIGHTS = 4 的任意 “or” 组合。 |
big_text | string | 可选 | 大文本通知栏样式 | |
inbox | JSONObject | 可选 | 文本条目通知栏样式 | |
big_pic_path | string | 可选 | 大图片通知栏样式 | |
extras | JSON Object | 可选 | 扩展字段 | |
large_icon | string | 可选 | 通知栏大图标 | |
small_icon_uri | string | 可选 | 通知栏小图标 | |
intent | JSON Object | 可选 | 指定跳转页面 | 使用 intent 里的 url 指定点击通知栏后跳转的目标页面;SDK<422 的版本此字段值仅对走华硕通道和极光自有通道下发生效,不影响请求走其它厂商通道。SDK≥422 的版本,API 推送时建议填写 intent 字段,否则点击通知可能无跳转动作。此字段支持以下三种类型: 1. 跳转到目标页: intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end (OPPO 和 FCM 通道必须传 "action 路径", 其他厂商必须传 "Activity 全名", 否则将出现对应厂商无法跳转问题) 2. 跳转到 deeplink 地址: scheme://test?key1=val1&key2=val2 3. 应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址) |
uri_activity | string | 可选 | 指定跳转页面 | |
uri_action | string | 可选 | 指定跳转页面 | |
badge_add_num | int | 可选 | 角标数字,取值范围 1-99 | |
badge_class | string | 可选 | 桌面图标对应的应用入口 Activity 类, 比如“com.test.badge.MainActivity” |
|
sound | string | 可选 | 填写 Android 工程中 /res/raw/ 路径下铃声文件名称,无需文件名后缀 | 注意:针对 Android 8.0 以上,当传递了 channel_id 时,此属性不生效。 |
show_begin_time | string | 可选 | 定时展示开始时间(yyyy-MM-dd HH:mm:ss) | |
show_end_time | string | 可选 | 定时展示结束时间(yyyy-MM-dd HH:mm:ss) | |
display_foreground | string | 可选 | APP 在前台,通知是否展示 | |
{
"notification" : {
"android" : {
"alert" : "hello, JPush!",
"title" : "JPush test",
"builder_id" : 3,
"style":1 // 1,2,3
"alert_type":1 // -1 ~ 7
"big_text":"big text content",
"inbox":JSONObject,
"big_pic_path":"picture url",
"priority":0, // -2~2
"category":"category str",
"large_icon": "http://www.jiguang.cn/largeIcon.jpg",
"intent": {"url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",},
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
}
iOS
iOS 平台上 APNs 通知结构。
该通知内容会由 JPush 代理发往 Apple APNs 服务器,并在 iOS 设备上在系统通知的方式呈现。
该通知内容满足 APNs 的规范,支持的字段如下:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | string 或 JSON Object | 必填 | 通知内容 | |
sound | string 或 JSON Object | 可选 | 通知提示声音或警告通知 | |
badge | string | 可选 | 应用角标 | |
content-available | boolean | 可选 | 推送唤醒 | 推送的时候携带 "content-available":true,说明是 Background Remote Notification,如果不携带此字段则是普通的 Remote Notification,详情参考:Background Remote Notification。 |
mutable-content | boolean | 可选 | 通知扩展 | 推送的时候携带 ”mutable-content":true 说明是支持 iOS10 的 UNNotificationServiceExtension,如果不携带此字段则是普通的 Remote Notification,详情参考:UNNotificationServiceExtension。 |
category | string | 可选 | iOS 8 开始支持,设置 APNs payload 中的 "category" 字段值。 | |
extras | JSON Object | 可选 | 附加字段 | 这里自定义 Key / value 信息,以供业务使用,详情参考 如何设置右侧图标/大图片 和 iOS 通知点击跳转。 |
thread-id | string | 可选 | 通知分组 | ios 的远程通知通过该属性来对通知进行分组,同一个 thread-id 的通知归为一组。 |
interruption-level | string | 可选 | 通知优先级和交付时间的中断级别 | ios 15 的通知级别,取值只能是 active,critical,passive,timeSensitive 中的一个,详情参考:UNNotificationInterruptionLevel。 |
iOS 通知 JPush 要转发给 APNs 服务器。APNs HTTP/2 的推送协议支持传递 4096 字节。
JPush 因为需要重新组包,并且考虑一点安全冗余,要求 "iOS":{ } 及大括号内的总体长度不超过:3584 个字节。JPush 使用 utf-8 编码,所以一个汉字占用 3 个字节长度。
服务端发送消息串
{
"notification" : {
"ios" : {
"alert" : "hello, JPush!",
"sound" : "sound.caf",
"badge" : 1,
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
}
客户端收到 apns
{
"_j_msgid" = 813843507;
aps = {
alert = "hello,JPush!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}
Quick App
快应用平台上通知结构。 该通知内容满足快应用平台的规范,支持的字段如下:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
title | string | 必填 | 通知标题 | 必填字段,快应用推送通知的标题。 |
alert | string | 必填 | 通知内容 | 这里指定了,则会覆盖上级统一指定的 alert 信息。 |
page | string | 必填 | 跳转页面 | 快应用通知跳转地址。 |
extras | JSON Object | 可选 | 附加字段 | 这里自定义 Key / value 信息,以供业务使用。 |
服务端发送消息串
{
"notification" : {
"quickapp": {
"alert": "Hi, JPush!",
"title": "Send to QuickApp",
"page": "/page1",
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
winphone
Windows Phone 平台上的通知。
该通知由 JPush 服务器代理向微软的 MPNs 服务器发送,并在 Windows Phone 客户端的系统通知栏上展示。
该通知满足 MPNs 的相关规范。当前 JPush 仅支持 toast 类型:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
alert | string | 必填 | 通知内容 | 会填充到 toast 类型 text2 字段上。这里指定了,将会覆盖上级统一指定的 alert 信息;内容为空则不展示到通知栏。 |
title | string | 可选 | 通知标题 | 会填充到 toast 类型 text1 字段上。 |
_open_page | string | 可选 | 点击打开的页面名称 | 点击打开的页面。会填充到推送信息的 param 字段上,表示由哪个 App 页面打开该通知。可不填,则由默认的首页打开。 |
extras | JSON Object | 可选 | 扩展字段 | 作为参数附加到上述打开页面的后边。 |
{
"notification" : {
"winphone" : {
"alert" : "hello, JPush!",
"title" : "Push Test",
"_open_page" : "/friends.xaml",
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
}
VOIP
iOS VOIP 功能。
该类型推送支持和 iOS 的 Notification 通知并存,请求参数结构参考:
{
"notification": {
"ios" : {
"alert" : "hello, JPush!",
"sound" : "sound.caf"
},
"voip": {"key": "value" // 任意自定义 key/value 对,会透传给 APP}
}
}
message:自定义消息
应用内消息,又称作:自定义消息,透传消息。
- 此部分内容不会展示到通知栏上,JPush SDK 收到消息内容后透传给 App,需要 App 自行处理。
- iOS 在推送应用内消息通道(非 APNS)获取此部分内容,需 App 处于前台。
- Windows Phone 暂时不支持应用内消息。
消息包含如下字段:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
msg_content | string | 必填 | 消息内容本身 |
title | string | 可选 | 消息标题 |
content_type | string | 可选 | 消息内容类型,开发者可根据自身业务定义具体类型。 |
extras | JSON Object | 可选 | JSON 格式的可选参数 |
Android 1.6.2 及以下版本 接收 notification 与 message 并存(即本次 api 调用同时推送通知和消息)的离线推送, 只能收到通知部分,message 部分没有透传给 App。
Android 1.6.3 及以上 SDK 版本已做相应调整,能正常接收同时推送通知和消息的离线记录。
iOS 1.7.3 及以上的版本才能正确解析 v3 的 message,但是无法解析 v2 推送通知同时下发的应用内消息。
inapp_message:应用内提醒
inapp_message 此功能生效需 Android push SDK≥V3.9.0、iOS push SDK≥V3.4.0,若低于此版本按照原流程执行。
inapp_message 面向于通知栏消息类型,对于通知权限关闭的用户可设置启用此功能。此功能启用后,当用户前台运行 APP 时,会通过应用内消息的方式展示通知栏消息内容。
- inapp_message: 面向通知栏消息,Boolean 类型;
- 值为 true 表示启用应用内提醒功能;
- 值为 false 表示禁用应用内提醒功能。
示例如下:
{
"cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909335e",
"platform": "all",
"audience": {
"tag": [
"深圳",
"北京"
]
},
"notification": {
"android": {
"alert": "Hi, JPush!",
"title": "Send to Android"
},
"ios": {
"alert": "Hi, JPush!",
"sound": "default",
"badge": "+1",
"thread-id": "default",
"extras": {"newsid": 321}
}
},
"inapp_message": {"inapp_message": true}
}
sms_message:短信补充
温馨提示:
1. 使用短信业务,会产生额外的运营商费用,具体请咨询商务,联系电话:400-612-5955,商务 QQ:800024881
2. 短信由签名和正文内容两部分组成。应运营商规定,签名和正文内容需审核,参考 名词解释 。
3. 签名设置参考 《控制台操作指南》之签名设置 和 短信签名 API 。
4. 自 2018 年 3 月起,短信补充的开发者必须提交正文内容模板,审核通过后即可使用。因此推送时需要填写 temp_id(如果模版有设置参数则需要填写 temp_para),参考 《控制台操作指南》之模板设置 和 短信模板 API 。
sms_message 用于设置短信推送内容以及短信发送的延迟时间。
开发者需要先把用户的手机号码与设备的 registrationID 匹配。绑定方法: 服务端-Device-更新设备 ; Android API-设置手机号码 ; iOS API-设置手机号码 ;
与原有 JSON 业务协议相匹配,消息有如下字段信息:
关键字 | 类型 | 选项 | 说明 |
---|---|---|---|
delay_time | int | 必填 | |
signid | int | 选填 | 签名 ID,该字段为空则使用应用默认签名。 |
temp_id | long | 必填 | 短信补充的内容模板 ID,没有填写该字段即表示不使用短信补充功能。 |
temp_para | JSON | 可选 | 短信模板中的参数。 |
active_filter | boolean | 可选 | active_filter 字段用来控制是否对补发短信的用户进行活跃过滤。 |
options:可选参数
推送可选项。
当前包含如下几个可选项:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
sendno | int | 可选 | 推送序号 | |
time_to_live | int | 可选 | 离线消息保留时长 (秒) | |
override_msg_id | long | 可选 | 要覆盖的消息 ID | 如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即: |
apns_production | boolean | 可选 | APNs 是否生产环境 | 该字段仅对 iOS 的 Notification 有效,如果不指定则为推送生产环境。注意:JPush 服务端 SDK 默认设置为推送 “开发环境”。 |
apns_collapse_id | string | 可选 | 更新 iOS 通知的标识符 | |
big_push_duration | int | 可选 | 定速推送时长 (分钟) | |
third_party_channel | JSON Object | 可选 | 推送请求下发通道 | 仅针对配置了厂商用户使用有效,详情参考 third_party_channel 说明 。 |
third_party_channel 说明
options.third_party_channel: key 只支持 xiaomi、huawei、honor、meizu、oppo、vivo、fcm 类型用户。 key 可以为上述 7 个类型中的其中一个或者多个同时存在,未传递的 key 其对应的厂商下发走默认下发逻辑。
默认下发逻辑
- 免费用户:distribution 默认值为 secondary_push,distribution_fcm 默认值为 secondary_fcm_push。
- VIP 用户:distribution 默认值为 first_ospush,distribution_fcm 默认值为 fcm。
厂商类型的 KEY 对应的 3 个策略参数如下:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
distribution | string | 可选 | 通知栏消息下发逻辑 | 取值不能为空字符串。 |
distribution_fcm | string | 可选 | 通知栏消息 fcm+ 国内厂商组合类型下发逻辑 | 取值不能为空字符串。 |
distribution_customize | string | 可选 | 自定义消息国内厂商类型下发逻辑 | 定义国内厂商类型用户(当前仅对 xiaomi、huawei、honor 生效)下发自定义消息的逻辑,此功能生效需 Android push SDK≥V3.9.0。 |
不同厂商类型的 KEY 可以存在以下属性参数:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
channel_id | string | 可选 | 通知栏消息分类 | 为了适配小米、oppo 手机厂商通知栏消息分类,由开发者自行向手机厂商申请,具体申请规则参考: 小米 ,oppo 。 |
skip_quota | boolean | 可选 | 配额判断及扣除 | 是否跳过配额判断及扣除,目前仅对小米和 oppo 有效,默认为 false。 |
classification | int | 可选 | 通知栏消息分类 | vivo 手机厂商通知栏消息分类,不填默认为 0。 目前 vivo 对系统消息分类较为严格,具体规则参考:vivo。 |
push_mode | int | 可选 | 通知栏消息类型 | 对应 vivo 的 pushMode 字段,不填默认为 0。详情参考:vivo pushMode。 |
importance | string | 可选 | 华为通知栏消息智能分类 | 为了适配华为手机厂商的通知栏消息智能分类,对应华为的 importance 字段,不填充默认为 "NORMAL",参考: 华为通知消息智能分类 。 |
urgency | string | 可选 | 华为厂商自定义消息优先级 | 为了适配华为手机厂商自定义消息的优先级。 设置“HIGH”需要向华为申请特殊权限,参考: 特殊权限如何申请 。 |
category | string | 可选 | 华为厂商自定义消息场景标识 | 为了适配华为手机厂商自定义消息,标识高优先级透传消息的特殊场景,或用于标识消息类型以对特定类型消息加快发送;对应值及其说明参考:category 值说明 。 |
large_icon | string | 可选 | 厂商消息大图标样式 | |
small_icon_uri | string | 可选 | 厂商消息小图标样式 | |
small_icon_color | string | 可选 | 小米厂商小图标样式颜色 | |
style | int | 可选 | 厂商消息大文本 /inbox/ 大图片样式 | 用来指定厂商的通知栏样式类型,JPush Android SDK v3.9.0 版本以上才支持该字段,默认为 0。 |
big_text | string | 可选 | 厂商消息大文本样式 | |
inbox | JSONObject | 可选 | 厂商消息 inbox 样式 | |
big_pic_path | string | 可选 | 厂商 big_pic_path | |
only_use_vendor_style | boolean | 可选 | 是否使用自身通道设置样式 | 是否只使用自身通道设置的样式,不使用 android 里面设置的样式,默认为 false,JPush Android SDK v3.9.0 版本以上才支持该字段。 |
示例:
"third_party_channel":{
"xiaomi":{
"distribution":"jpush",
"channel_id":"*******",
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
"small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
"small_icon_color":"#ABCDEF",
"big_text":"testbigtext", // 可选,最多支持 128 个字符,配合小米 style 使用
"style":1,
"distribution_fcm":"fcm",
"distribution_customize":"first_ospush",
"skip_quota": true
},
"huawei":{
"distribution":"secondary_push",
"distribution_fcm":"jpush",
"distribution_customize":"first_ospush",
"importance":"HIGH",
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
"small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
"inbox": JSONObject, //可选,配合华为 style 使用
"style":2,
"only_use_vendor_style":true
},
"honor":{
"distribution":"secondary_push",
"distribution_fcm":"jpush",
"distribution_customize":"first_ospush",
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
"small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
"style":1
},
"meizu":{
"distribution":"jpush",
"distribution_fcm":"pns"
},
"fcm":{ // 这个参数不支持 distribution_fcm 字段
"distribution":"jpush"
},
"oppo":{
"distribution":"ospush",
"channel_id":"*******",
"distribution_fcm":"secondary_fcm_push",
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
"big_pic_path":"jgmedia-1-14b23451-0001-41ce-89d9-987b465122da",
"style":1,
"skip_quota": true
},
"vivo":{
"distribution":"jpush",
"classification": 0,
"distribution_fcm":"secondary_pns_push",
"push_mode":0
}
}
callback:回调参数
Push API 发起请求时,可以指定 callback 参数,方便用户临时变更回调 URL 或者回调带上其自定义参数,满足其日常业务需求。
此功能仅针对极光 VIP 用户提供,主要提供消息送达、点击回执数据。
如需要开通此功能,请联系:商务客服
示例:
{
"platform":"all",
"audience":"all",
"notification":{"alert":"Hi, JPush",},
....
"callback": {
"url":"https://***", // 可选字段;
"params":{ // 可选
"name":"joe",
"age":26
},
"type":3 // 可选,1: 送达回执, 2: 点击回执, 3: 送达和点击回执, 8: 推送成功回执, 9: 成功和送达回执, 10: 成功和点击回执, 11: 成功和送达以及点击回执
}
}
callback 包含如下字段:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
url | string | 可选 | 数据临时回调地址。 |
params | JSON Object | 可选 | 需要回调给用户的自定义参数 |
type | int | 可选 | 回调数据类型。 |
notification_3rd:自定义消息转厂商通知
Push API 发起自定义消息类型的推送请求时,针对 Android 设备,如果 APP 长连接不在线,则消息没法及时的下发;针对这种情况,极光推出了“自定义消息转厂商通知”的功能。
也就是说,针对用户一些重要的自定义消息,可以申请开通极光 VIP 厂商通道功能,开通后,通过 APP 长连接不在线时没法及时下发的消息,可以通过厂商通道下发以厂商通知形式展示,及时提醒到用户。极光内部会有去重处理,您不用担心消息重复下发问题。
如需要开通此功能,请联系:商务客服
示例:
{
"platform":"all",
"audience":"all",
"message":{"msg_content": "Hi,JPush",},
"notification_3rd": {
"content": "Hi,JPush",
"title": "msg",
"channel_id": "channel001",
"uri_activity": "cn.jpush.android.ui.OpenClickActivity",
"uri_action": "cn.jpush.android.intent.CONNECTION",
"badge_add_num": 1,
"badge_class": "com.test.badge.MainActivity",
"sound": "sound",
"extras":{
"news_id" : 134,
"my_key" : "a value"
}
}
}
- notification_3rd 包含如下字段:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
title | string | 可选 | 补发通知标题,如果为空则默认为应用名称。 |
content | string | 必填 | 补发通知的内容,如果存在 notification_3rd 这个 key,content 字段不能为空,且值不能为空字符串。 |
intent | JSON Object | 可选 | 使用 intent 里的 url 指定点击通知栏后跳转的目标页面;SDK<422 的版本此字段值仅对走华硕通道和极光自有通道下发生效,不影响请求走其它厂商通道。SDK≥422 的版本,API 推送时建议填写 intent 字段,否则点击通知可能无跳转动作。此字段支持以下三种类型: 1. 跳转到目标页: intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end (OPPO 和 FCM 通道必须传 "action 路径", 其他厂商必须传 "Activity 全名", 否则将出现对应厂商无法跳转问题) 2. 跳转到 deeplink 地址: scheme://test?key1=val1&key2=val2 3. 应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址) |
uri_activity | string | 可选 | |
uri_action | string | 可选 | |
badge_add_num | int | 可选 | |
badge_class | string | 可选 |
|
sound | string | 可选 | |
channel_id | string | 可选 | |
extras | JSON Object | 可选 | 扩展字段;这里自定义 JSON 格式的 Key / Value 信息,以供业务使用。 |
- 使用说明
- notification_3rd 只针对开通了厂商通道的用户生效;
- notification 和 notification_3rd 不能同时有内容,如果这两块同时有内容,则会返回错误提示;
- notification_3rd 的内容对 iOS 和 WinPhone 平台无效,只针对 Android 平台生效;
- notification_3rd 是用作补发厂商通知的内容,只有当 message 部分有内容,才允许传递此字段,且要两者都不为空时,才会对离线的厂商设备转发厂商通道的通知。
cid:推送唯一标识符
调用地址
GET https://api.jpush.cn/v3/push/cid[?count=n[&type=xx]]
功能说明
cid 是用于防止 api 调用端重试造成服务端的重复推送而定义的一个推送参数。
用户使用一个 cid 推送后,再次使用相同的 cid 进行推送,则会直接返回第一次成功推送的结果,不会再次进行推送。
CID 的有效期为 1 天。CID 的格式为:{appkey}-{uuid}
在使用 cid 之前,必须通过接口获取你的 cid 池。获取时 type=push 或者不传递 type 值。
调用示例
Request Header
curl --insecure -X GET -v https://api.jpush.cn/v3/push/cid?count=3 -H "Content-Type: application/json" -u "2743204aad6fe2572aa2d8de:e674a3d0fd42a53b9a58121c"
GET /v3/push/cid?count=3
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json
Request Params
count
可选参数。数值类型,不传则默认为 1。范围为 [1, 1000]
type
可选参数。CID 类型。取值:push(默认),schedule
Response Header
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Response Data
{
"cidlist":[
"8103a4c628a0b98994ec1949-128eeb45-471c-49f3-b442-a05c20c9ed56",
"8103a4c628a0b98994ec1949-6e44d7f1-89f5-48a8-bec4-e359c15b13e5",
"8103a4c628a0b98994ec1949-47e0a960-ce67-4e71-94ce-b4b9e8813af0"
]
}
Response Params
cidlist
cid 列表
推送校验 API
调用地址
POST https://api.jpush.cn/v3/push/validate
功能说明
该 API 只用于验证推送调用是否能够成功,与推送 API 的区别在于:不向用户发送任何消息。 其他字段说明:同推送 API。
批量单推(VIP 专属接口)
调用地址
POST https://api.jpush.cn/v3/push/batch/regid/single
POST https://api.jpush.cn/v3/push/batch/alias/single
注:/v3/push/batch/regid/single 针对的是 RegID 方式批量单推,/v3/push/batch/alias/single 针对的是 Alias 方式批量单推
功能说明
如果您在给每个用户的推送内容都不同的情况下,可以使用此接口。
如需要开通此接口,请联系:商务客服
调用说明
使用此接口前,您需要配合使用 cid: 推送唯一标识符 接口提前获取到 cid 池,获取时 type=push 或者不传递 type 值;获取到 cid 值后,传递参数格式如下:
{"pushlist":{
"cid 值 1":{...},
"cid 值 2":{...},
...
}}
调用示例
Request Header
> POST /v3/push/batch/regid/single HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
或者
> POST /v3/push/batch/alias/single HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Request Params
pushlist
必填参数。JSON 类型
cid 值
必填参数。JSON 类型,取值:push(默认),JSON Value 部分具体字段参考下面表格说明
关键字 | 选项 | 含义 |
---|---|---|
platform | 必填 | 推送平台设置 |
target | 必填 | 推送设备指定。 |
notification | 可选 | |
message | 可选 | |
sms_message | 可选 | 短信渠道补充送达内容体 |
options | 可选 | 推送参数 |
完整参数示例:
{"pushlist":{
"cid1":{
"platform": "all",
"target": "aliasvalue1", // 此处填写的是 regid 值或者 alias 值
"notification": {... // 省略参数同 push api 部分},
"message": {... // 省略参数同 push api 部分},
"sms_message":{... // 省略参数同 push api 部分},
"options": {... // 省略参数同 push api 部分}
},
"cid2":{
"platform": "all",
"target": "aliasvalue2", // 此处填写的是 regid 值或者 alias 值
"notification": {...},
"message": {...},
"sms_message":{...},
"options": {...}
},
...
}}
Response
成功返回:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Success Response Data
{
"cid1":{"msg_id":134123478},
"cid1":{
"msg_id":134123478,
"error":{
"code":1011,
"message":"****"
}
},
"cid3":{
"error":{
"code":1009,
"message":"****"
}
},
...
}
失败返回:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
Failed Response Data
{
"error":{
"message":"Authen failed",
"code":1004
}
}
推送撤销
调用地址
DELETE https://api.jpush.cn/v3/push/{msgid}
功能说明
撤销操作首先会从服务端尝试撤销(Android 消息,排队中 / 发送中状态可以服务端撤销;iOS 消息,排队中状态可以服务端撤销);其次,针对 Push SDK(JPush Android SDK v3.5.0 及以上和 JPush iOS SDK v3.2.8 及以上),会尝试从设备端撤销已展示但未被点击的消息。
Example Request
DELETE /v3/push/{msgid}
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json
Example Response
Success Response
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
Failed Response
HTTP/1.0 400
Content-Type: application/json
Content-Length: 0
{
"error":{
"code":1003,
"message":"msgid doesn't exist"
}
}
文件推送
文件立即推送调用地址
POST https://api.jpush.cn/v3/push/file
文件定时推送调用地址
POST https://api.jpush.cn/v3/schedules
功能说明
支持指定文件唯一标识(file_id)进行推送,文件唯一标识(file_id)可以参考 File API v3 的 文件上传接口 获得。
调用说明
推送支持的参数和普通 Push API v3 参数一致,仅仅只是 audience 参数和 Push API v3 接口有区别,此接口支持的 audience 参数仅仅支持传递 file。
文件立即推送调用参数示例
{
"platform":"all",
"audience":{
"file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"}
},
"notification":{"alert":"Hello, JPush!"},
"message":{"msg_content":"Hello, JPush!"},
"options":{
"time_to_live":600,
"apns_production":false
}
}
文件定时推送调用参数示例
{
"cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
"name":"Schedule_Name",
"enabled":true,
"trigger":{
"periodical":{
"start":"2021-02-19 12:00:00",
"end":"2021-03-19 18:30:00",
"time":"18:05:00",
"time_unit":"day",
"frequency":1
}
},
"push":{
"platform":"all",
"audience":{
"file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"}
},
"notification":{"alert":"Hello, JPush!"},
"message":{"msg_content":"Hello, JPush!"},
"options":{
"time_to_live":600,
"apns_production":false
}
}
}
注意
- 文件推送(文件立即推送 / 文件定时推送) API 接口频率规则和 File API v3 频率规则一样 20 次 /min,且各个文件相关接口频率会互相消耗。
- 对于即时推送,建议创建推送任务 5 分钟后再执行文件删除操作,否则推送任务可能会失败。
- 对于文件定时推送,创建定时任务成功后,若任务被执行前文件被删除,则任务执行时推送动作将会失败。
Group Push API:应用分组推送
调用地址
POST https://api.jpush.cn/v3/grouppush
功能说明
该 API 用于为开发者在 portal 端创建的应用分组创建推送。
groupkey 可以在创建的分组信息中获取,使用起来同 appkey 类似,但在使用的时候前面要加上 “group-” 前缀。
注 1:暂不支持 option 中 override_msg_id 的属性;分组推送仅在官网支持设置定时,调 Schedule API 时不支持。
注 2: 2020.08.11 此接口新增返回 group_msgid 字段,用于唯一标识本次分组推送请求,后续可用于分组推送统计。
调用示例
curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{"platform":["android"],"audience":"all","notification":{"android":{"alert":"notification content","title":"notification title"}},"message":{"msg_content":"message content"}}'
返回示例
{"004f2b2c3d8fc649fa60ad2c":{"msg_id":"38280675634520813","sendno":"0"},"4bb78a2d6404fa239906db70":{"error":{"code":1011,"message":"cannot find user by this audience"},"dad9619c708ae3663647d01e":{"msg_id":"9007276705113721","sendno":"0"},"group_msgid":"bspkjbi81sipokgfvmu0"}
应用分组文件推送(VIP 专属接口)
调用地址
POST https://api.jpush.cn/v3/grouppush/file
功能说明
该 API 用于为开发者在 portal 端创建的应用分组进行文件推送,推送参数和格式跟文件推送一样。
需要注意对是,此接口鉴权使用的是 base64(groupkey:group_secret)
groupkey 可以在创建的分组信息中获取,使用起来同 appkey 类似,但在使用的时候前面要加上 “group-” 前缀,group_secret 对应分组信息中的 Group Master Secret。
注:此接口只对已经开通权限对客户支持,未开通权限客户使用将会返回错误返回码 2007。
调用示例
curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush/file -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{"platform":["android"],"audience":{"file": {"file_id":"9516d30d2c128dd2000e35b6-e4b030ed-6f89-468c-8f3a-41302f88fe44"}},"notification":{"android":{"alert":"notification content","title":"notification title"}},"message":{"msg_content":"message content"}}'
调用返回
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
1000 | 系统内部错误 | 服务器端内部逻辑错误,请稍后重试。 | 500 |
1001 | 只支持 HTTP Post 方法 | 不支持 Get 方法。 | 405 |
1002 | 缺少了必须的参数 | 必须改正,检查要求必填的参数是否未写 | 400 |
1003 | 参数值不合法 | 必须改正,参数不合法的情况如: |
400 |
1004 | 验证失败 | 必须改正。检查 Appkey 与 MasterSecret,详情请看:调用验证 | 401 |
1005 | 消息体太大 | 必须改正。
|
400 |
1008 | app_key 参数非法 | 必须改正,请仔细对比你所传的 Appkey 是否与应用信息中的一致,是否多了空格。 | 400 |
1009 | 推送对象中有不支持的 key | 必须改正,提示:是否将 content-available 错误地写为 content_available,builder_id 错误地写为 build_id;除文档中指定的字段外,还需传递自定义的 key 请在 extras 中填写。 | 400 |
1011 | 没有满足条件的推送目标 | 400 | |
1012 | 符合当前条件的推送已超过限制 | 400 | |
1016 | 参数非法 | 400 | |
1017 | 参数非法 | 一般是因为传递了互斥的多个系统通道参数属性导致。 | 400 |
1018 | 参数非法 | 请检查 callback 回调参数指定的 URL 是否在极光官网配置。 | 400 |
1019 | 参数非法 | 请检查 options.third_party_channel 中的策略字段 distribution/distribution_custom/distribution_fcm 与消息类型(通知 / 自定义)是否匹配。 | 400 |
1020 | 只支持 HTTPS 请求 | 必须改正 | 404 |
1030 | 内部服务超时 | 稍后重试,若多次重试无法成功,请联系 support@jiguang.cn | 503 |
2002 | API 调用频率超出该应用的限制 | 注意 API 频率控制 ,可联系极光商务或技术支持开通更高的 API 调用频率。 | 429 |
2003 | 该应用 appkey 已被限制调用 API | 联系技术支持查明限制原因和寻求帮助。 | 403 |
2004 | 无权限执行当前操作 | 必须改正。当前调用 API 的源 ip 地址不在该应用的 ip 白名单中,请在官网应用设置中配置 IP 白名单。 | 403 |
2005 | 信息发送量超出合理范围。 | 检测到目标用户累计发送消息量过大,超过合理的使用范围,需要检查业务逻辑或者联系技术支持。 | 403 |
2006 | 非 VIP 用户。 | 接口只针对 VIP 用户开放。 | 403 |
2007 | 无权调用此接口。 | 请联系商务开通使用权限。 | 403 |
2008 | 广播推送超出频率限制 | 极光于 2020/03/10 对「广播推送」的频率进行限制,调整为 10 次每天,如需更高频率,请联系商务。 | 400 |
2009 | 推送请求被限制 | 推送方式被系统限制;或者如果是厂商推送,请确认是否在厂商允许推送时间范围;更详细可以联系技术支持查明限制原因和寻求帮助。 | 400 |
2010 | 推送请求被限制 | 推送内容包含黑词,或者推送总量超限。 | 400 |
相关参考
- HTTP 返回码:HTTP-Status-Code
- 获取推送送达 API:Report-API
- HTTP 规范参考:HTTP 基本认证
- Apple APNs 规范:Apple Push Notification Service
- Microsoft MPNs 规范:Push notifications for Windows Phone 8
- 各平台各通道推送内容限制
厂商通道 | 标题长度 | 内容长度 | 敏感词 | 其他说明 |
---|---|---|---|---|
极光通道 | 不限制,但限制消息体总大小 | 不限制,但限制消息体总大小 | 根据安全包功能所配置的黑词 | 暂无 |
华为通道 | < 40 个字符 | < 1024 字符 | 禁止携带政府,领导人名称、台独等相关内容 | 默认【营销通知】的权限为静默通知,静默推送没有声音、震动等提示。 |
荣耀通道 | 不限制,但消息体总大小 < 4096 字节 | 不限制,但消息体总大小 < 4096 字节 | 禁止携带政府,领导人名称、台独等相关内容 | - |
魅族通道 | < 32 个字符 | < 100 个字符 | 禁止特殊字符,如:# | |
小米通道 | < 50 个字符 | < 128 个字符 | 禁止特殊字符,如:#、>> | |
OPPO 通道 | < 32 个字符 | < 200 个字符 | 暂无说明 | |
vivo 通道 | < 40 个字符 | < 100 个字符 | ||
APNS 通道 | < 20 个字符(40 个英文字符) | 暂无 | 暂无 |