Push API v3

这是 Push API 最近的版本。

相比于 API v2 版本，v3 版本的改进为：

• 完全基于 https，不再提供 http 访问；
• 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成，比如：curl，浏览器插件等；
• 推送内容完全使用 JSON 的格式；
• 支持的功能有所改进：支持多 tag 的与或操作；可单独发送通知或者自定义消息，也可同时推送通知与自定义消息；windows phone 目前只有通知。

推送概述

功能说明

向某单个设备或者某设备列表推送一条通知、或者消息。推送的内容只能是 JSON 表示的一个推送对象。

调用地址

https://api.jpush.cn/v3/push

如果创建的极光应用分配的北京机房，并且 API 调用方的服务器也位于北京，则比较适合调用极光北京机房的 API，可以提升一定的响应速度。

通过极光 Web 控制台 “应用设置” -> "应用信息" 中可以看到应用所在机房。如果应用所在地为北京机房，同时会给出各 API 的调用地址。

北京机房 Push API 调用地址： https://bjapi.push.jiguang.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 格式表达，表示一条推送相关的所有信息。

示例与说明

{
    "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
            }
        }
    },
    "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"
    }
}

platform：推送平台

JPush 当前支持 Android, iOS, Windows Phone 三个平台的推送。其关键字分别为："android", "ios", "winphone"。

如果目标平台为 iOS 平台，推送 Notification 时需要在 options 中通过 apns_production 字段来设定推送环境。True 表示推送生产环境，False 表示要推送开发环境； 如果不指定则为推送生产环境；一次只能推送给一个环境。

推送到所有平台：

{ "platform" : "all" }

指定特定推送平台：

{ "platform" : ["android", "ios"] }

audience：推送目标

推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，JPush 提供了多种方式，比如：别名、标签、注册 ID、分群、广播等。

all

如果要发广播（全部设备），则直接填写 “all”。

推送目标

广播外的设备选择方式，有如下几种：

以上几种类型至少需要有其一。如果值数组长度为 0，表示该类型不存在。

这几种类型可以并存，多项的隐含关系是 AND，即取几种类型结果的交集。

例如：

"audience" : { "tag" : [ "tag1", "tag2" ], "tag_and" : [ "tag3", "tag4"], "tag_not" : [ "tag5", "tag6"] }

先计算 "tag" 字段的结果 tag1或tag2=A;

再计算 "tagand" 字段的结果 **tag3且tag4=B_**;

再计算 "tagnot" 字段的结果 **非(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 按照一定的通知栏样式展示。

支持的字段有：

{
    "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 的规范，支持的字段如下：

iOS 通知 JPush 要转发给 APNs 服务器。APNs 协议定义通知长度为 2048 字节。

JPush 因为需要重新组包，并且考虑一点安全冗余，要求 "iOS":{ } 及大括号内的总体长度不超过：2000 个字节。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;
}

winphone

Windows Phone 平台上的通知。该通知由 JPush 服务器代理向微软的 MPNs 服务器发送，并在 Windows Phone 客户端的系统通知栏上展示。该通知满足 MPNs 的相关规范。当前 JPush 仅支持 toast 类型：

    {
        "notification" : {
            "winphone" : {
                 "alert" : "hello, JPush!", 
                 "title" : "Push Test", 
                 "_open_page" : "/friends.xaml", 
                 "extras" : {
                      "news_id" : 134, 
                      "my_key" : "a value"
                 }
            }
        }
    }

message：自定义消息

应用内消息。或者称作：自定义消息，透传消息。此部分内容不会展示到通知栏上，JPush SDK 收到消息内容后透传给 App。需要 App 自行处理。iOS 在推送应用内消息通道（非 APNS）获取此部分内容，即需 App 处于前台。Windows Phone 暂时不支持应用内消息。

消息包含如下字段：

Android 1.6.2 及以下版本 接收 notification 与 message 并存（即本次 api 调用同时推送通知和消息）的离线推送， 只能收到通知部分，message 部分没有透传给 App。
Android 1.6.3 及以上 SDK 版本已做相应调整，能正常接收同时推送通知和消息的离线记录。
iOS 1.7.3 及以上的版本才能正确解析 v3 的 message，但是无法解析 v2 推送通知同时下发的应用内消息。

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 业务协议相匹配，消息有如下字段信息：

options：可选参数

推送可选项。

当前包含如下几个可选项：

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 列表

Group Push API：应用分组推送

调用地址

POST https://api.jpush.cn/v3/grouppush

功能说明

该 API 用于为开发者在 portal 端创建的应用分组创建推送。

groupkey 可以在创建的分组信息中获取，使用起来同 appkey 类似，但在使用的时候前面要加上 “group-” 前缀。

注：暂不支持 option 中 override_msg_id 的属性；分组推送仅在官网支持设置定时，调 Schedule API 时不支持。

调用示例

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"}}'

推送校验 API

调用地址

POST https://api.jpush.cn/v3/push/validate

功能说明

该 API 只用于验证推送调用是否能够成功，与推送 API 的区别在于：不向用户发送任何消息。其他字段说明：同推送 API。

调用返回

参考

• 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.aspx)