Push API v3
这是 Push API 最近的版本。
相比于 API v2 版本,v3 版本的改进为:
- 完全基于 https 且支持 http2,不再提供 http 访问,;
- 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成,比如:curl,浏览器插件等;
- 推送内容完全使用 JSON 的格式;
- 支持的功能有所改进:支持多 tag 的与或操作;可单独发送通知或者自定义消息,也可同时推送通知与自定义消息;windows phone 目前只有通知。
推送概述
功能说明
向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。
调用地址
https://api.jpush.cn/v3/push
请求示例
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 一起二者必须有其一,可以二者并存 |
message | 可选 | 消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一,可以二者并存 |
notification_3rd | 可选 | 自定义消息转厂商通知内容体。与 message 一起使用 |
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 的关系,即取并集。 | 用标签来进行大规模的设备属性、用户属性分群。 一次推送最多 20 个。
|
tag_and | JSON Array | 标签AND | 数组。多个标签之间是 AND 关系,即取交集。 | 注意与 tag 区分。一次推送最多 20 个。 |
tag_not | JSON Array | 标签NOT | 数组。多个标签之间,先取多标签的并集,再对该结果取补集。 | 一次推送最多 20 个。 |
alias | JSON Array | 别名 | 数组。多个别名之间是 OR 关系,即取并集。 | 用别名来标识一个用户。一个设备只能绑定一个别名,但多个设备可以绑定同一个别名。一次推送最多 1000 个。
|
registration_id | JSON Array | 注册ID | 数组。多个注册 ID 之间是 OR 关系,即取并集。 | 设备标识。一次推送最多 1000 个。客户端集成 SDK 后可获取到该值。如果您一次推送的 registration_id 值超过 1000 个,可以直接使用 文件推送 功能。 |
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 | 必填 | 通知内容 | 这里指定了,则会覆盖上级统一指定的 alert 信息;内容可以为空字符串,则表示不展示到通知栏。 |
title | string | 可选 | 通知标题 | 如果指定了,则通知里原来展示 App 名称的地方,将展示成这个字段。 |
builder_id | int | 可选 | 通知栏样式 ID | Android SDK 可设置通知栏样式,这里根据样式 ID 来指定该使用哪套样式,android 8.0 开始建议采用NotificationChannel配置。 |
channel_id | String | 可选 | android通知channel_id | 不超过1000字节,Android 8.0开始可以进行NotificationChannel配置,这里根据channel ID 来指定通知栏展示效果。 |
priority | int | 可选 | 通知栏展示优先级 | 默认为 0,范围为 -2~2。 |
category | string | 可选 | 通知栏条目过滤或排序 | 完全依赖 rom 厂商对 category 的处理策略 |
style | int | 可选 | 通知栏样式类型 | 默认为 0,还有 1,2,3 可选,用来指定选择哪种通知栏样式,其他值无效。有三种可选分别为 bigText=1,Inbox=2,bigPicture=3。 |
alert_type | int | 可选 | 通知提醒方式 | 可选范围为 -1~7 ,对应 Notification.DEFAULT_ALL = -1 或者 Notification.DEFAULT_SOUND = 1, Notification.DEFAULT_VIBRATE = 2, Notification.DEFAULT_LIGHTS = 4 的任意 “or” 组合。默认按照 -1 处理。 |
big_text | string | 可选 | 大文本通知栏样式 | 当 style = 1 时可用,内容会被通知栏以大文本的形式展示出来,厂商没有填充big_text,则也默认使用该big_text字段展示。厂商big_text, 支持 api 16 以上的 rom。 |
inbox | JSONObject | 可选 | 文本条目通知栏样式 | 当 style = 2 时可用, json 的每个 key 对应的 value 会被当作文本条目逐条展示,厂商没有填充inbox,则也默认使用该inbox字段展示。厂商inbox,支持 api 16 以上的 rom。 |
big_pic_path | string | 可选 | 大图片通知栏样式 | 当 style = 3 时可用,可以是网络图片 url,或本地图片的 path,目前支持 .jpg 和 .png 后缀的图片,也可以是极光media_id。图片内容会被通知栏以大图片的形式展示出来。如果是 http/https 的 url,会自动下载;如果要指定开发者准备的本地图片就填 sdcard 的相对路径。厂商big_pic_path,支持 api 16 以上的 rom。 |
extras | JSON Object | 可选 | 扩展字段 | 这里自定义 JSON 格式的 Key / Value 信息,以供业务使用。针对部分厂商跳转地址异常,可通过 third_url_encode 兼容处理 "extras": { "third_url_encode": true //notification - android - extras ,true表示需要极光encode处理,值需要是布尔类型 } "extras": { "third_url_encode": false //notification - android - extras ,false,或者无此字段,表示不需要极光encode处理,值需要是布尔类型 } |
large_icon | string | 可选 | 通知栏大图标 | 图标路径可以是以http或https开头的网络图片,如:http:jiguang.cn/logo.png ,图标大小不超过 30 k(注:从JPush Android SDK v4.0.0版本开始,图片大小限制提升至 300 k); 也可以是位于drawable资源文件夹的图标路径,如:R.drawable.lg_icon; 也可以是通过极光图片上传接口得到的media_id值,如:jgmedia-2-14b23451-0001-41ce-89d9-987b465122da。 若是极光media_id,则对其它厂商通道也会使用这个media_id下发,若非media_id,则对走华硕通道下发和极光自有通道下发生效,不影响请求走其它厂商通道。厂商large_icon |
small_icon_uri | string | 可选 | 通知栏小图标 | 图标路径可以是以http或https开头的网络图片,如:http:jiguang.cn/logo.png,图标大小不超过 30 k (注:从JPush Android SDK v4.0.0版本开始,图片大小限制提升至 300 k); 也可以是通过极光图片上传接口得到的media_id值,如:jgmedia-2-14b23451-0001-41ce-89d9-987b465122da。 此字段值,若是极光media_id,则对其它厂商通道也会使用这个media_id下发,若非media_id,则对走华硕通道下发和极光自有通道下发生效,不影响请求走其它厂商通道。厂商small_icon_uri |
intent | JSON Object | 可选 | 指定跳转页面 | 使用 intent 里的 url 指定点击通知栏后跳转的目标页面; 此字段值,则仅对走华硕通道和极光自有通道下发生效,不影响请求走其它厂商通道。 |
uri_activity | string | 可选 | 指定跳转页面 | 该字段用于指定开发者想要打开的 activity,值为 activity 节点的 “android:name”属性值; 适配华为、小米、vivo厂商通道跳转; |
uri_action | string | 可选 | 指定跳转页面 | 该字段用于指定开发者想要打开的 activity,值为 "activity"-"intent-filter"-"action" 节点的 "android:name" 属性值; 适配 oppo、fcm跳转; |
badge_add_num | int | 可选 | 角标数字,取值范围1-99 | 此属性目前仅针对华为 EMUI 8.0 及以上、小米 MIUI 6 及以上设备生效; 此字段如果不填,表示不改变角标数字(小米设备由于系统控制,不论推送走极光通道下发还是厂商通道下发,即使不传递依旧是默认+1的效果。); 否则下一条通知栏消息配置的badge_add_num数据会和之前角标数量进行增加; 建议badge_add_num配置为1; 举例:badge_add_num配置1,应用之前角标数为2,发送此角标消息后,应用角标数显示为3。 |
badge_class | string | 可选 | 桌面图标对应的应用入口Activity类, 比如“com.test.badge.MainActivity” | 配合badge_add_num使用,二者需要共存,缺少其一不可; 针对华为设备推送时生效(此值如果填写非主Activity类,走厂商推送以华为厂商限制逻辑为准;走极光通道下发,默认以APP的主Activity为准) |
sound | string | 可选 | 填写Android工程中/res/raw/路径下铃声文件名称,无需文件名后缀 | 注意:针对Android 8.0以上,当传递了channel_id 时,此属性不生效。 |
show_begin_time | string | 可选 | 定时展示开始时间(yyyy-MM-dd HH:mm:ss) | 此属性不填写,SDK默认立即展示;此属性填写,则以填写时间点为准才开始展示。 JPush Android SDK v3.5.0 版本开始支持。 |
show_end_time | string | 可选 | 定时展示结束时间(yyyy-MM-dd HH:mm:ss) | 此属性不填写,SDK会一直展示;此属性填写,则以填写时间点为准,到达时间点后取消展示。 JPush Android SDK v3.5.0 版本开始支持。 |
display_foreground | string | 可选 | APP在前台,通知是否展示 | 值为 "1" 时,APP 在前台会弹出通知栏消息; 值为 "0" 时,APP 在前台不会弹出通知栏消息。 注:默认情况下 APP 在前台会弹出通知栏消息。 JPush Android SDK v3.5.8 版本开始支持。 |
{
"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 | 必填 | 通知内容 | 这里指定内容将会覆盖上级统一指定的 alert 信息;内容为空则不展示到通知栏。支持字符串形式也支持官方定义的 alert payload 结构,在该结构中包含 title 和 subtitle 等官方支持的 key |
sound | string 或 JSON Object | 可选 | 通知提示声音或警告通知 | 普通通知: string类型,如果无此字段,则此消息无声音提示;有此字段,如果找到了指定的声音就播放该声音,否则播放默认声音,如果此字段为空字符串,iOS 7 为默认声音,iOS 8 及以上系统为无声音。说明:JPush 官方 SDK 会默认填充声音字段,提供另外的方法关闭声音,详情查看各 SDK 的源码。 告警通知: JSON Object ,支持官方定义的 payload 结构,在该结构中包含 critical 、name 和 volume 等官方支持的 key . |
badge | int | 可选 | 应用角标 | 如果不填,表示不改变角标数字,否则把角标数字改为指定的数字;为 0 表示清除。JPush 官方 SDK 会默认填充 badge 值为 "+1",详情参考:badge +1 |
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 信息,以供业务使用。 |
thread-id | string | 可选 | 通知分组 | ios 的远程通知通过该属性来对通知进行分组,同一个 thread-id 的通知归为一组。 |
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类型;
- 值为 ture 表示启用应用内提醒功能;
- 值为 flase 表示禁用应用内提醒功能,
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 | 必填 | 单位为秒,不能超过 24 小时。设置为 0,表示立即发送短信。该参数仅对 android 和 iOS 平台有效,Winphone 平台则会立即发送短信。 |
signid | int | 选填 | 签名ID,该字段为空则使用应用默认签名。 |
temp_id | long | 必填 | 短信补充的内容模板 ID。没有填写该字段即表示不使用短信补充功能。 |
temp_para | JSON | 可选 | 短信模板中的参数。 |
active_filter | boolean | 可选 | active_filter 字段用来控制是否对补发短信的用户进行活跃过滤,默认为 true ,做活跃过滤;为 false,则不做活跃过滤; |
options:可选参数
推送可选项。
当前包含如下几个可选项:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
sendno | int | 可选 | 推送序号 | 纯粹用来作为 API 调用标识,API 返回时被原样返回,以方便 API 调用方匹配请求与返回。值为 0 表示该 messageid 无 sendno,所以字段取值范围为非 0 的 int. |
time_to_live | int | 可选 | 离线消息保留时长(秒) | 推送当前用户不在线时,为该用户保留多长时间的离线消息,以便其上线时再次推送。默认 86400 (1 天),最长 10 天。设置为 0 表示不保留离线消息,只有推送当前在线的用户可以收到。该字段对 iOS 的 Notification 消息无效。 |
override_msg_id | long | 可选 | 要覆盖的消息 ID | 如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即:1)该 msg_id 离线收到的消息是覆盖后的内容;2)即使该 msg_id Android 端用户已经收到,如果通知栏还未清除,则新的消息内容会覆盖之前这条通知;覆盖功能起作用的时限是:1 天。如果在覆盖指定时限内该 msg_id 不存在,则返回 1003 错误,提示不是一次有效的消息覆盖操作,当前的消息不会被推送;该字段仅对 Android 有效。 |
apns_production | boolean | 可选 | APNs 是否生产环境 | True 表示推送生产环境,False 表示要推送开发环境;如果不指定则为推送生产环境。但注意,JPush 服务端 SDK 默认设置为推送 “开发环境”。该字段仅对 iOS 的 Notification 有效。 |
apns_collapse_id | string | 可选 | 更新 iOS 通知的标识符 | APNs 新通知如果匹配到当前通知中心有相同 apns-collapse-id 字段的通知,则会用新通知内容来更新它,并使其置于通知中心首位。collapse id 长度不可超过 64 bytes。 |
big_push_duration | int | 可选 | 定速推送时长(分钟) | 又名缓慢推送,把原本尽可能快的推送速度,降低下来,给定的 n 分钟内,均匀地向这次推送的目标用户推送;最大值为 1400;最多能同时存在 20 条定速推送;未设置则不是定速推送。 |
third_party_channel | JSON Object | 可选 | 推送请求下发通道 | 仅针对配置了厂商用户使用有效 |
third_party_channel
示例:
"third_party_channel":{
"xiaomi":{
"distribution":"jpush", // 表示纯小米用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
"channel_id":"*******", //可选,2020/06 新增,由小米提供给到开发者,开发者通过此处透传;
//如果传递了此字段,也传递了 notification-android-channel_id 字段,则针对小米通道下发时,以此字段为准;
//如果此字段未传递,则以 notification-android-channel_id 字段为准。
//当 distribution 为 jpush 时,该参数实际无效
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", //可选,支持极光的media_id及小米厂商的大图标id,必须配合小米大文本或者是大图片使用,否则无效
"small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da", //可选,支持极光的media_id及小米厂商的小图标id
"small_icon_color":"#ABCDEF", //可选,不填充默认灰色
"big_text":"testbigtext", //可选,最多支持128个字符,配合小米style使用
"style":1 //可选,默认为0普通模式,bigText=1,bigPicture=3
"distribution_fcm":"fcm" // 可选,2020/09/15 新增,表示小米+fcm共存时下发逻辑,此处表示 fcm + 小米组合用户,消息走fcm下发
// 全部取值:jpush、fcm、pns、secondary_fcm_push(优先极光然后fcm)、secondary_pns_push(优先极光然后小米)
"distribution_customize":"first_ospush" // 可选,表示推送自定义消息优先走厂商通道下发,无效走极光通道下发
},
"huawei":{
"distribution":"secondary_push", // 表示纯华为用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
"distribution_fcm":"jpush", // 可选,2020/09/15 新增,表示华为+fcm共存时下发逻辑,此处表示 fcm+华为组合用户,消息走极光下发
// 全部取值:jpush、fcm、pns、secondary_fcm_push(优先极光然后fcm)、secondary_pns_push(优先极光然后华为)
"importance":"HIGH", //可选,2020/09/21 新增,对应华为的 importance 字段,值为 String 类型,对应值分别是:“LOW”(一般消息)、“NORMAL”(重要消息)、“HIGH”(非常重要消息),不填充默认为"NORMAL"
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", //可选,支持极光的media_id及网络https路径
"small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da", //可选,支持极光的media_id及华为厂商本地路径
"inbox": JSONObject, //可选,配合华为style使用
"style":2, //可选,默认为0普通模式,bigText=1,Inbox=2
"only_use_vendor_style":true //只使用自身通道设置的样式,不使用android里面设置大图标/小图标/大文本等样式
},
"meizu":{
"distribution":"jpush", // 表示纯魅族用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
"distribution_fcm":"pns" // 可选,2020/09/15 新增,表示魅族+fcm共存时下发逻辑,此处表示 fcm+魅族组合用户,消息走魅族下发
// 全部取值:jpush、fcm、pns、secondary_fcm_push(优先极光然后fcm)、secondary_pns_push(优先极光然后魅族)
},
"fcm":{ // 这个参数不支持 distribution_fcm 字段
"distribution":"jpush" // 表示纯 fcm 用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
},
"oppo":{
"distribution":"ospush", // 表示纯 oppo 用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
"channel_id":"*******", //可选,2020/06 新增,由开发者通自行去OPPO官方申请,申请通过,开发者通过过此处透传;
//如果传递了此字段,也传递了 notification-android-channel_id 字段,则针对 OPPO 通道下发时,以此字段为准;
//如果此字段未传递,则以 notification-android-channel_id 字段为准。
//当 distribution 为 jpush 时,该参数实际无效;
//当 distribution 为 secondary_push 时,限制策略走极光通道和走厂商通道逻辑一致:厂商不限制,极光也不限制;开发者如果恶意使用此字段,被转发到厂商的请求如果因配额限制导致推送无法下发问题,后台由开发者自行承担。
"distribution_fcm":"secondary_fcm_push", // 可选,2020/09/15 新增,表示oppo+fcm共存时下发逻辑,此处表示 fcm+oppo 组合用户,消息优先走极光,然后走fcm下发
// 全部取值:jpush、fcm、pns、secondary_fcm_push(优先极光然后fcm)、secondary_pns_push(优先极光然后oppo)
"large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", //可选,支持极光的media_id及oppo厂商的大图标id
"big_pic_path":"jgmedia-1-14b23451-0001-41ce-89d9-987b465122da", //可选,配合oppo的style使用
"style":1 //可选,默认为0普通模式,bigText=1,bigPicture=3
},
"vivo":{
"distribution":"jpush", // 表示纯 vivo 用户通知栏消息下发逻辑,全部取值:jpush、ospush、secondary_push
"classification": 0, //可选,int 类型,2020/06 新增,和vivo官方字段含义一致 0 代表运营消息,1 代表系统消息,不填vivo官方默认为0
//当 distribution 为 jpush 时,该参数实际无效;
//当 distribution 为 secondary_push 时,限制策略走极光通道和走厂商通道逻辑一致:厂商不限制,极光也不限制;开发者如果恶意使用此字段,被转发到厂商的请求如果因配额限制导致推送无法下发问题,后台由开发者自行承担。
"distribution_fcm":"secondary_pns_push", // 可选,2020/09/15 新增,表示vivo+fcm共存时下发逻辑,此处表示 fcm+vivo 组合用户,消息优先走极光,然后走vivo下发
// 全部取值:jpush、fcm、pns、secondary_fcm_push(优先极光然后fcm)、secondary_pns_push(优先极光然后vivo)
"push_mode":0 //可选,2020/09/21 新增,对应 vivo 的 pushMode 字段,值为int 类型,值分别是:“0”表示正式推送;“1”表示测试推送,不填默认为0
}
}
options.third_party_channel字段说明:
options.third_party_channel: key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm类型用户。 key 可以为上述6个类型中的其中一个或者多个同时存在,未传递的 key 其对应的厂商下发走默认下发逻辑。
默认下发逻辑为:如果推送的是通知,一次推送请求中,目标用户同时包含厂商用户和非厂商用户,那厂商用户走对应厂商下发,非厂商用户走极光通道下发;
每个厂商类型的KEY可以同时存在以下3个策略参数:
- distribution:面向通知栏消息,定义系统通道用户下发通知栏消息的逻辑,字符串类型,取值不能为空字符串,只能是"ospush"、"jpush"、"secondary_push" 和 "first_ospush"。
- 值为 first_ospush 时表示推送优先走厂商通道下发,无效走极光通道下发;
- 值为 ospush 表示推送强制走厂商通道下发;
- 值为 jpush 表示推送强制走极光通道下发;
- 值为 secondary_push 表示推送优先走极光,极光不在线再走厂商,厂商作为辅助;【建议此种方式】
- distribution_fcm: 面向通知栏消息,定义fcm+国内厂商组合类型用户下发通知栏消息的逻辑,字符串类型,取值不能为空字符串,只能是"jpush"、"fcm"、"pns"、"secondary_fcm_push"、"secondary_pns_push"。
- 值为 jpush 表示推送强制走极光通道下发;
- 值为 fcm 表示推送强制走 fcm 通道下发;
- 值为 pns 表示推送强制走小米/华为/魅族/oppo/vivo 通道下发;
- 值为 secondary_fcm_push 表示针对fcm+国内厂商组合类型用户,推送优先走极光,极光不在线再走fcm通道,fcm作为辅助;
- 值为 secondary_pns_push 表示针对fcm+国内厂商组合类型用户,推送优先走极光,极光不在线再走厂商通道,厂商作为辅助;
- distribution_customize: 面向自定义消息,定义国内厂商类型用户(当前仅对xiaomi、huawei生效)下发自定义消息的逻辑,字符串类型,取值不能为空字符串,只能是"first_ospush"。此功能生效需Android push SDK≥V3.9.0。
- 值为 jpush 表示推送强制走极光通道下发;
- 值为 first_ospush 时表示推送优先走厂商通道下发,无效走极光通道下发;
- 值为 secondary_push 表示推送优先走极光,极光不在线再走厂商,厂商作为辅助;
不同厂商类型的KEY可以存在以下属性参数:
- channel_id: 为了适配小米、oppo 手机厂商通知栏消息分类,由开发者自行向手机厂商申请,具体申请规则参考:小米 ,oppo 。
- classification: 为了适配 vivo 手机厂商通知栏消息分类,值为int 类型,“0”代表运营消息,“1”代表系统消息,不填默认为0,目前vivo对系统消息分类较为严格,具体规则参考:vivo ;
- push_mode: 为了适配 vivo 手机厂商通知栏消息,对应 vivo 的 pushMode 字段,值为int 类型,值分别是:“0”表示正式推送;“1”表示测试推送,不填默认为0;参考:vivo pushMode ;
- importance: 为了适配华为手机厂商的通知栏消息智能分类,对应华为的 importance 字段,值为 String 类型,对应值分别是:“LOW”(一般消息)、“NORMAL”(重要消息)、“HIGH”(非常重要消息),不填充默认为"NORMAL",参考:华为通知消息智能分类 。
- urgency:为了适配华为手机厂商自定义消息的优先级。值为string类型,对应值分别为是:“HIGH”(非常重要消息,HIGH级别消息到达用户手机时可强制拉起应用进程)、“NORMAL”(重要消息)。设置“HIGH”需要向华为申请特殊权限,参考:特殊权限如何申请 。
- category:为了适配华为手机厂商自定义消息,标识高优先级透传消息的特殊场景,值为string类型,对应值分别为是:“PLAY_VOICE”(语音播报)、“VOIP”(VoIP电话)。使用此字段申请特殊权限,参考:特殊权限如何申请 。
- large_icon: 为了适配厂商的消息大图标样式,目前支持小米/华为/oppo三个厂商,优先使用厂商字段, 厂商字段没有填充,则使用android里面定义large_icon字段android内的large_icon,其中小米支 持极光的media_id(极光media_id详见:Image API v3)及小米厂商的大图标id,但必须配合小米大文本或者是大图片使用,否则无效,华为支持极光的media_id及网络https路径,oppo支持极光的media_id及oppo厂商的大图标id,JPush Android SDK v3.9.0版本以上才支持该字段
- small_icon_uri: 为了适配厂商的消息小图标样式,目前支持小米/华为两个厂商,优先使用厂商字段, 厂商字段没有填充,则使用android里面定义small_icon_uri字段android内的small_icon_uri,其中小米支持极光的media_id及小米厂商的小图标id,支持极光的media_id及华为厂商本地路径
- small_icon_color: 为了适配小米厂商的消息小图标样式颜色,不填充默认是灰色,JPush Android SDK v3.9.0版本以上才支持该字段
- style: 为了适配厂商的消息大文本/inbox/大图片样式,不填充默认是0,对应关系bigText=1,Inbox=2,bigPicture=3,JPush Android SDK v3.9.0版本以上才支持该字段
- big_text: 为了适配厂商的消息大文本样式,目前支持小米/华为/oppo三个厂商,优先使用厂商字段, 厂商字段没有填充,则使用android里面定义big_text字段android内的big_text,其中小米最多支持128个字符(一个英文或一个中文算一个字符),配合小米style使用,oppo最多也是支持128个字符,配合style使用,JPush Android SDK v3.9.0版本以上才支持该字段
- inbox: 为了适配厂商的消息inbox样式,目前支持华为厂商,优先使用厂商字段, 厂商字段没有填充,则使用android里面定义inbox字段android内的inbox,配合华为style使用,JPush Android SDK v3.9.0版本以上才支持该字段
- big_pic_path: 为了适配厂商的消息大图片样式,目前支持小米/oppo两个厂商,优先使用厂商字段, 厂商字段没有填充,则使用android里面定义big_pic_path字段android内的big_pic_path,配合各自厂 商的style使用,JPush Android SDK v3.9.0版本以上才支持该字段
- only_use_vendor_style:值为布尔类型,为true,只使用自身通道设置的样式,不使用android里面设置大图标/小图标/大文本/inbox/大图片样式,反之则可使用android里面设置的样式,默认为false,JPush Android SDK v3.9.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:送达和点击回执
}
}
callback 包含如下字段:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
url | string | 可选 | 数据临时回调地址,指定后以此处指定为准,仅针对这一次推送请求生效;不指定,则以极光后台配置为准 |
params | JSON Object | 可选 | 需要回调给用户的自定义参数 |
type | string | 可选 | 回调数据类型,1:送达回执,2:点击回执,3:送达和点击回执 |
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 字段不能为空,且值不能为空字符串。 |
channel_id | string | 可选 | 不超过1000字节,Android 8.0开始可以进行 NotificationChannel配置,这里根据channel ID 来指定通知栏展示效果 |
uri_activity | string | 可选 | 该字段用于指定开发者想要打开的 activity,值为 activity 节点的 “android:name”属性值;适配华为、小米、vivo厂商通道跳转;针对 VIP 厂商通道用户使用生效。 |
uri_action | string | 可选 | 指定跳转页面;该字段用于指定开发者想要打开的 activity,值为 "activity"-"intent-filter"-"action" 节点的 "android:name" 属性值;适配 oppo、fcm跳转;针对 VIP 厂商通道用户使用生效。 |
badge_add_num | string | 可选 | 角标数字,取值范围1-99;此属性目前仅针对华为 EMUI 8.0 及以上、小米 MIUI 6 及以上设备生效; 此字段如果不填,表示不改变角标数字(小米设备由于系统控制,不论推送走极光通道下发还是厂商通道下发,即使不传递依旧是默认+1的效果。); 否则下一条通知栏消息配置的badge_add_num数据会和之前角标数量进行增加; 建议badge_add_num配置为1; 举例:badge_add_num配置1,应用之前角标数为2,发送此角标消息后,应用角标数显示为3。 |
badge_class | string | 可选 | 桌面图标对应的应用入口Activity类, 比如“com.test.badge.MainActivity;配合badge_add_num使用,二者需要共存,缺少其一不可; 针对华为设备推送时生效(此值如果填写非主Activity类,走厂商推送以华为厂商限制逻辑为准;走极光通道下发,默认以APP的主Activity为准) |
sound | string | 可选 | 填写Android工程中/res/raw/路径下铃声文件名称,无需文件名后缀;注意:针对Android 8.0以上,当传递了channel_id 时,此属性不生效。 |
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 | 必填 | 推送设备指定。 如果是调用RegID方式批量单推接口(/v3/push/batch/regid/single),那此处就是指定regid值; 如果是调用Alias方式批量单推接口(/v3/push/batch/alias/single),那此处就是指定alias值。 |
notification | 可选 | 通知内容体。是被推送到客户端的内容。与 message 一起二者必须有其一,可以二者并存 |
message | 可选 | 消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一,可以二者并存 |
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
功能说明
支持指定文件唯一标识(file_id)进行推送,文件唯一标识(file_id)可以参考 File API v3 的 文件上传接口获得。
调用说明
推送支持的参数和普通 Push API v3参数一致,仅仅只是 audience 参数和Push API v3接口有区别,此接口支持的 audience 参数仅仅支持传递 file,示例如下:
{
"audience": {
"file": {"file_id":"xxxx-xxxx"}
}
}
- 说明:文件推送 API 接口频率规则和 File API v3 频率规则一样 20次/min,且各个文件相关接口频率会互相消耗。
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 | 参数值不合法 | 必须改正。参数不合法的情况如:Audience 参数中 tag,alias,registration_id 有空值;单发指定的 registration_id 非法或者格式错误。 | 400 |
1004 | 验证失败 | 必须改正。检查 Appkey 与 MasterSecret,详情请看:调用验证 | 401 |
1005 | 消息体太大 | 必须改正。 Android 平台 Notification+Message 长度限制为 4000 字节; iOS Notification 中 “iOS”:{ } 及大括号内的总体长度不超过:3584 个字节(包括自定义参数和符号),iOS 的 Message 部分长度不超过 4000 字节; WinPhone 平台 Notification 长度限制为 1000 字节 | 400 |
1008 | app_key 参数非法 | 必须改正,请仔细对比你所传的 Appkey 是否与应用信息中的一致,是否多了空格 | 400 |
1009 | 推送对象中有不支持的 key | 必须改正,提示:Android 属性不支持 sound 字段;是否将 content-available 错误地写为 content_available,builder_id 错误地写为 build_id;除文档中指定的字段外,还需传递自定义的 key 请在 extras 中填写。 | 400 |
1011 | 没有满足条件的推送目标 | 1. 请检查是否有设备满足 audience 的目标条件(别名与标签是否设置成功);若客户端未完成 SDK 集成,服务端先做测试,需下载 demo 安装到手机上再做推送;第一次集成成功,若采用广播推送请等待 10 分钟。 2. 推送目标超过 255 天不活跃,被排除在推送目标之外。 |
400 |
1012 | 符合当前条件的推送已超过限制 | 1. 定速推送超过限制; 2. 厂商配额不足。 |
400 |
1016 | 参数非法 | 可能是因为没有开通对应厂商系统通道权限,但传递了厂商系统特性参数导致; 也可能是传递的其它参数所对应的功能权限未开通。 |
400 |
1017 | 参数非法 | 一般是因为传递了互斥的多个系统通道参数属性导致 | 400 |
1018 | 参数非法 | 请检查 callback 回调参数指定的 URL 是否在极光官网配置 | 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
- 老版本 Push API:Push API v2
- HTTP 规范参考:HTTP 基本认证
- Apple APNs 规范:Apple Push Notification Service
- Microsoft MPNs 规范:Push notifications for Windows Phone 8