Push API v3
這是 Push API 最近的版本。
相比於 API v2 版本，v3 版本的改進為：
-
完全基於 https，不再提供 http 訪問；
-
使用 HTTP Basic Authentication 的方式做訪問授權。這樣整個 API 請求可以使用常見的 HTTP 工具來完成，比如：curl，瀏覽器插件等；
-
推送內容完全使用 JSON 的格式；
-
支持的功能有所改進：支持多 tag 的與或操作；可單獨發送通知或者自定義消息，也可同時推送通知與自定義消息；windows phone 目前只有通知。
推送概述
功能說明
向某單個設備或者某設備列表推送一條通知、或者消息。
推送的內容只能是 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!"}}'> 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 轉換。
推送校驗 API
POST https://api.jpush.cn/v3/push/validate
功能說明
該 API 只用於驗證推送調用是否能夠成功，與推送 API 的區別在於：不向用戶發送任何消息。 其他字段說明：同推送 API。
推送對象
一個推送對象，以 JSON 格式表達，表示一條推送相關的所有信息。
示例與說明
{
"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" } }, "options": { "time_to_live": 60, "apns_production": false }}| 關鍵字 | 選項 | 含義 |
|---|---|---|
| platform | 必填 | 推送平台設置 |
| audience | 必填 | 推送設備指定 |
| notification | 可選 | 通知內容體。是被推送到客戶端的內容。與 message 一起二者必須有其一，可以二者並存 |
| message | 可選 | 消息內容體。是被推送到客戶端的內容。與 notification 一起二者必須有其一，可以二者並存 |
| options | 可選 | 推送參數 |
platform
JPush 當前支持 Android, iOS, Windows Phone 三個平台的推送。其關鍵字分別為："android", "ios", "winphone"。
如果目標平台為 iOS 平台 需要在 options 中通過 apns_production 字段來制定推送環境。True 表示推送生產環境，False 表示要推送開發環境； 如果不指定則為推送生產環境
推送到所有平台：
{ "platform" : "all" }指定特定推送平台：
{ "platform" : ["android", "ios"] }audience
推送設備對象，表示一條推送可以被推送到哪些設備列表。確認推送設備對象，JPush 提供了多種方式，比如：別名、標簽、注冊ID、分群、廣播等。
all
如果要發廣播（全部設備），則直接填寫 “all”。
推送目標
廣播外的設備選擇方式，有如下幾種：
| 關鍵字 | 含義 | 類型 | 說明 | 備注 |
|---|---|---|---|---|
| tag | JSON Array | 標簽 | 數組。多個標簽之間是 OR 的關系，即取並集。 | 用標簽來進行大規模的設備屬性、用戶屬性分群。 一次推送最多 20 個。
|
| tag_and | JSON Array | 標簽AND | 數組。多個標簽之間是 AND 關系，即取交集。 | 注冊與 tag 區分。一次推送最多 20 個。 |
| alias | JSON Array | 別名 | 數組。多個別名之間是 OR 關系，即取並集。 | 用別名來標識一個用戶。一個設備只能綁定一個別名，但多個設備可以綁定同一個別名。一次推送最多 1000 個。
|
| registration_id | JSON Array | 注冊ID | 數組。多個注冊ID之間是 OR 關系，即取並集。 | 設備標識。一次推送最多 1000 個。 |
每種類型的值都是數組（Array），數組里多個值之間隱含的關系是是 OR，即取並集。但 tag_and 不同，其數組里多個值之間是 AND 關系，即取交集。
4 種類型至少需要有其一。如果值數組長度為 0，表示該類型不存在。
這幾種類型可以並存。並存時多項的隱含關系是 AND，即取交集。
示例
-
推送給全部（廣播）：
{
"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 來指定該使用哪套樣式。 |
| extras | JSON Object | 可選 | 擴展字段 | 這里自定義 JSON 格式的 Key/Value 信息，以供業務使用。 |
{
"notification" : { "android" : { "alert" : "hello, JPush!", "title" : "JPush test", "builder_id" : 3, "extras" : { "news_id" : 134, "my_key" : "a value" } } }}iOS
iOS 平台上 APNs 通知。
該通知內容會由 JPush 代理發往 Apple APNs 服務器，並在 iOS 設備上在系統通知的方式呈現。
該通知內容滿足 APNs 的規范，支持的字段如下：
| 關鍵字 | 類型 | 選項 | 說明 | |
|---|---|---|---|---|
| alert | string | 必填 | 通知內容 | 這里指定了，將會覆蓋上級統一指定的 alert 信息；內容為空則不展示到通知欄。支持 emoji 表情。 |
| sound | string | 可選 | 通知提示聲音 | 如果無此字段，則此消息無聲音提示；有此字段，如果找到了指定的聲音就播放該聲音，否則播放默認聲音,如果此字段為空字符串，iOS 7 為默認聲音，iOS 8 為無聲音。(消息) 說明：JPush 官方 API Library (SDK) 會默認填充聲音字段。提供另外的方法關閉聲音。 |
| badge | int | 可選 | 應用角標 | 如果不填，表示不改變角標數字；否則把角標數字改為指定的數字；為 0 表示清除。JPush 官方 API Library(SDK) 會默認填充badge值為"+1",詳情參考：badge +1 |
| content-available | boolean | 可選 | 推送喚醒 | 推送的時候攜帶"content-available":true 說明是 Background Remote Notification，如果不攜帶此字段則是普通的Remote Notification。詳情參考：Background Remote Notification |
| category | string | 可選 | IOS8才支持。設置APNs payload中的"category"字段值 | |
| extras | JSON Object | 可選 | 擴展字段 | 這里自定義 Key/value 信息，以供業務使用。 |
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 類型：
| 關鍵字 | 類型 | 選項 | 含義 | 說明 |
|---|---|---|---|---|
| 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" } } } }message
應用內消息。或者稱作：自定義消息，透傳消息。
此部分內容不會展示到通知欄上，JPush SDK 收到消息內容后透傳給 App。App 需要自行處理。
iOS 平台上，有此部分內容，才會推送應用內消息通道。
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推送通知同時下發的應用內消息。
options
推送可選項。
當前包含如下幾個可選項：
| 關鍵字 | 類型 | 選項 | 含義 | 說明 |
|---|---|---|---|---|
| sendno | int | 可選 | 推送序號 | 純粹用來作為 API 調用標識，API 返回時被原樣返回，以方便 API 調用方匹配請求與返回。 |
| time_to_live | int | 可選 | 離線消息保留時長(秒) | 推送當前用戶不在線時，為該用戶保留多長時間的離線消息，以便其上線時再次推送。默認 86400 （1 天），最長 10 天。設置為 0 表示不保留離線消息，只有推送當前在線的用戶可以收到。 |
| override_msg_id | long | 可選 | 要覆蓋的消息ID | 如果當前的推送要覆蓋之前的一條推送，這里填寫前一條推送的 msg_id 就會產生覆蓋效果，即：1）該 msg_id 離線收到的消息是覆蓋后的內容；2）即使該 msg_id Android 端用戶已經收到，如果通知欄還未清除，則新的消息內容會覆蓋之前這條通知；覆蓋功能起作用的時限是：1 天。如果在覆蓋指定時限內該 msg_id 不存在，則返回 1003 錯誤，提示不是一次有效的消息覆蓋操作，當前的消息不會被推送。 |
| apns_production | boolean | 可選 | APNs是否生產環境 | True 表示推送生產環境，False 表示要推送開發環境；如果不指定則為推送生產環境。JPush 官方 API LIbrary (SDK) 默認設置為推送 “開發環境”。 |
| big_push_duration | int | 可選 | 定速推送時長(分鍾) | 又名緩慢推送，把原本盡可能快的推送速度，降低下來，給定的n分鍾內，均勻地向這次推送的目標用戶推送。最大值為1400.未設置則不是定速推送。 |
調用返回
HTTP 狀態碼
參考文檔：HTTP-Status-Code
業務返回碼
| Code | 描述 | 詳細解釋 | HTTP Status Code |
|---|---|---|---|
| 1000 | 系統內部錯誤 | 服務器端內部邏輯錯誤，請稍后重試。 | 500 |
| 1001 | 只支持 HTTP Post 方法 | 不支持 Get 方法。 | 405 |
| 1002 | 缺少了必須的參數 | 必須改正 | 400 |
| 1003 | 參數值不合法 | 必須改正 | 400 |
| 1004 | 驗證失敗 | 必須改正。詳情請看：調用驗證 | 401 |
| 1005 | 消息體太大 | 必須改正。 Android平台Notification+Message長度限制為1000字節； iOS Notification 中 “iOS”:{ } 及大括號內的總體長度不超過：2000個字節（包括自定義參數和符號），iOS 的 Message部分長度不超過 1000 字節； WinPhone平台Notification長度限制為1000字節 | 400 |
| 1008 | app_key參數非法 | 必須改正 | 400 |
| 1011 | 沒有滿足條件的推送目標 | 請檢查audience | 400 |
| 1020 | 只支持 HTTPS 請求 | 必須改正 | 404 |
| 1030 | 內部服務超時 | 稍后重試 | 503 |