Push API v3

推送概述

功能说明

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

调用地址

POST 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 格式表达，表示一条推送相关的所有信息。

示例与说明

{
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android",
            "builder_id": 1,
            "extras": {
                "newsid": 321
            }
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "extras": {
                "newsid": 321
            }
        }
    },
    "message": {
        "msg_content": "Hi,JPush",
        "content_type": "text",
        "title": "msg",
        "extras": {
            "key": "value"
        }
    },
    "sms_message":{
        "content":"sms msg content",
        "delay_time":3600
    },
    "options": {
        "time_to_live": 60,
        "apns_production": false,
        "apns_collapse_id":"jiguang_test_201706011100"
    }
}

platform：推送平台

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

推送到所有平台：

{ "platform" : "all" }

指定特定推送平台：

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

audience：推送目标

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

all

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

推送目标

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

示例

• 推送给全部（广播）：

{
   "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",
             "extras" : {
                  "news_id" : 134, 
                  "my_key" : "a value"
             }
        }
    }
}

iOS

iOS 平台上 APNs 通知结构。
该通知内容会由 JPush 代理发往 Apple APNs 服务器，并在 iOS 设备上在系统通知的方式呈现。
该通知内容满足 APNs 的规范，支持的字段如下：

服务端发送消息串

{
    "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）获取。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：短信补充

用于设置短信推送内容以及短信发送的延迟时间。手机接收号码,开发者需要先把用户的手机号码与设备的registration id匹配。绑定方法：服务端-Device-更新设备

与原有 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 的属性。

调用示例

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