極光API推送（v3 版本）

時間 2019-11-10

標籤極光 api 推送 v3 版本简体版

原文原文鏈接

Push API v3

這是 Push API 最近的版本。android

相比於 API v2 版本，v3 版本的改進爲：ios

徹底基於 https，再也不提供 http 訪問；算法
使用 HTTP Basic Authentication 的方式作訪問受權。這樣整個 API 請求可使用常見的 HTTP 工具來完成，好比：curl，瀏覽器插件等；json
推送內容徹底使用 JSON 的格式；windows
支持的功能有所改進：支持多 tag 的與或操做；可單獨發送通知或者自定義消息，也可同時推送通知與自定義消息；windows phone 目前只有通知。api

推送概述

功能說明

向某單個設備或者某設備列表推送一條通知、或者消息。數組

推送的內容只能是 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 組成：字母（區分大小寫）、數字、下劃線、漢字。限制：每個 tag 的長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
tag_and	JSON Array	標籤AND	數組。多個標籤之間是 AND 關係，即取交集。	註冊與 tag 區分。一次推送最多 20 個。
alias	JSON Array	別名	數組。多個別名之間是 OR 關係，即取並集。	用別名來標識一個用戶。一個設備只能綁定一個別名，但多個設備能夠綁定同一個別名。一次推送最多 1000 個。有效的 alias 組成：字母（區分大小寫）、數字、下劃線、漢字。限制：每個 alias 的長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
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