Push API v4

嚮某單個設備或者某設備列表推播一條通知、或者訊息。

推播的內容隻能是 JSON 表示的一個推播對象。

這是 Push API 最近的版本。v4 版本的改進為：

使用 HTTP Basic Authentication 的方式做訪問授權。這樣整個 API 請求可以使用常見的 HTTP 工具來完成，比如：curl，瀏覽器插件等。
推播內容完全使用 JSON 的格式。

請求頻率限制

我們的API對呼叫頻率有限制，以確保服務的穩定性和公平性。每個AppKey的QPS（每秒查詢量）限制如下：

標準限制：每秒最多500次請求。
高級限制：如果您是我們的付費計劃用戶，且您的付費AppKey需要更高的QPS限制，請聯繫我們的商務團隊：Sales@engagelab.com。

調用驗證

詳情參見 REST API 概述的鑒權方式說明。

調用地址

POST v4/push

          POST v4/push

此代碼塊在浮窗中顯示

請求示例

請求頭

> POST /v4/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

          > POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

此代碼塊在浮窗中顯示

請求體

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }

          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

此代碼塊在浮窗中顯示

請求參數

推送的參數結構體，詳見下表：

關鍵字	類型	選項	含義
from	String	可選	當前業務傳送方
to	String 或 JSON Object	必填	傳送目標
body	JSON Object	必填	傳送請求體
platform	String 或 JSON Array	必填	推播平台
notification	JSON Object	可選	通知內容體，是被推播到客戶端的內容。與 message 一起二者必須有其一，二者不可以並存。
message	JSON Object	可選	訊息內容體，是被推播到客戶端的內容。與 notification 一起二者必須有其一，二者不可以並存。
options	JSON Object	可選	推播參數
request_id	String	可選	客戶自訂的可選字段，客戶用來標識是哪條請求，回響時返回。
custom_args	JSON Object	可選	客戶自訂的可選字段，回調時返回給客戶。

from

當前業務傳送方，String 類型，可選字段。

請求示例

{ "from":"push" }

          {
    "from":"push"
}

此代碼塊在浮窗中顯示

to

推播設備對象，表示一條推播可以被推播到哪些設備列表。確認推播設備對象，MTPush 提供了兩種方式，分別是註冊 ID 和廣播。

推播目標

關鍵字	類型	含義	說明	備註
all	String	發廣播	給全部設備進行推播	推播目標為 30 天內活躍過的設備。
registration_id	JSON Array	註冊 ID	數組。多個註冊 ID 之間是 OR 關係，即取並集。	設備標識。一次推播最多 1000 個。
tag	JSON Array	標簽	數組。多個標簽之間是 OR 的關系，即取並集。	用標簽來進行大規模的設備屬性、用戶屬性分群。一次推播最多 20 個。有效的 tag 組成：字母（區分大小寫）、數字、下劃線、漢字。限製：每一個 tag 的長度限製為 40 字節。（判斷長度需采用UTF-8編碼）
tag_and	JSON Array	標簽AND	數組。多個標簽之間是 AND 關系，即取交集。	註意與 tag 區分，一次推播最多 20 個。
tag_not	JSON Array	標簽NOT	數組。多個標簽之間，先取多標簽的並集，再對該結果取補集。	一次推播最多 20 個。
alias	JSON Array	別名	數組。多個別名之間是 OR 關系，即取並集。	用別名來標識一個用戶。一個設備只能綁定一個別名，但多個設備可以綁定同一個別名。一次推播最多 1000 個。有效的 alias 組成：字母（區分大小寫）、數字、下劃線、漢字。限製：每一個 alias 的長度限製為 40 字節。（判斷長度需采用UTF-8編碼）

數組裏多個值之間隱含的關系是是 OR，即取並集;但 tag_and 不同，其數組裏多個值之間是 AND 關系，即取交集。

tag_not 不能單獨使用，其他 5 種類型至少需要有其一。如果值數組長度為 0，表示該類型不存在。

這幾種類型可以並存。並存時多項的隱含關系是 AND，即取交集。例如：

"to" : {"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;

"to" 的最終結果為 A 且 B 且 C 。

#### 請求示例

推播給全部（廣播）：

{ "to": "all", }

          {
  "to": "all",
}

此代碼塊在浮窗中顯示

推播給多個註冊 ID：

{ "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }

          {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

此代碼塊在浮窗中顯示

body

傳送請求體。支持的字段如下：

關鍵字	類型	選項	含義
platform	String 或 JSON Array	必填	推播平台
notification	JSON Object	可選	通知內容體，是被推播到客戶端的內容。與 message 一起二者必須有其一，二者不可以並存。
options	JSON Object	可選	推播參數

platform

MTPush 當前僅支持 Web 平台的推播，所以 platform 指定的關鍵字為："web"。

{ "platform" : "web" }

          { "platform" : "web" }

此代碼塊在浮窗中顯示

notification

“通知”對象，是一條推播的實體內容對象之一（另一個是“訊息”），是會作為“通知”推播到 web 端的。

關鍵字	類型	選項	含義	說明
web	JSON Object	必填	平台屬性	平台推播參數

web

Web 平台上的通知。

關鍵字	類型	選項	含義	說明
alert	String 或 JSON Object	必填	內容	訊息內容本身，這裏指定了，將會覆蓋上級統一指定的 alert 信息。
url	String	必填	web 推播 url	通知點選跳轉地址
title	String	可選	標題	訊息標題
extras	JSON Object	可選	擴展字段	這裏自訂 JSON 格式的 Key / Value 信息，以供業務使用。
icon	String	可選	通知 icon	建議 192*192px，不強制限制；強制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Firefox（Safari 和 Edge 系統默認無法自訂）
image	String	可選	通知大圖	建議 360*180px，不強制限制；強制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Edge（Firefox 和 Safari 不支持）

{ "notification": { "web": { "alert": "hello, Push!", "title": "Push Test", "url":"http://www.google.com", "icon":"", "image":"", "extras": { "news_id": 134, "my_key": "a value" } } } }

          {
    "notification": {
        "web": {
            "alert": "hello, Push!",
            "title": "Push Test",
            "url":"http://www.google.com",
            "icon":"",
            "image":"",
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代碼塊在浮窗中顯示

message

應用程式內訊息。或者稱作：自訂訊息，透傳訊息。

此部分內容不會展示在瀏覽器上，SDK 收到訊息內容後透傳給 Web，Web 自行處理業務邏輯。

訊息包含如下字段：

關鍵字	類型	選項	含義
msg_content	String 或 JSON Object	必填	訊息內容本身
title	String	可選	訊息標題
content_type	String	可選	訊息內容類型
extras	JSON Object	可選	JSON 格式的可選參數

示例：

{ "message": { "msg_content": "Hi,Push", "content_type": "text", "title": "msg", "extras": { "key": "value" } } }

          {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

此代碼塊在浮窗中顯示

options

推播可選項。當前包含如下幾個可選項：

關鍵字	類型	選項	含義	說明
time_to_live	Int 或 String	可選	離線訊息保留時長(秒)	若推播時用戶不在線，可為該用戶保留指定時長的離線訊息，以便其上線時再次推播。預設 86400 （1 天），最長 15 天，若係統瀏覽器支持的最大值 < 傳遞的有效值，則以係統最大值為準。設定為 0 表示不保留離線訊息，隻有推播當前在線的用戶可以收到。
override_msg_id	Long	可選	要覆蓋的訊息 ID	如果當前的推播要覆蓋之前的一條推播，這裏填寫前一條推播的 msg_id 就會産生覆蓋效果，即：該 msg_id 離線收到的訊息是覆蓋後的內容，即使該 msg_id web 端用戶已經收到，如果通知欄還未清除，則新的訊息內容會覆蓋之前這條通知。覆蓋功能起作用的時限是：1 天，如果在覆蓋指定時限內該 msg_id 不存在，則返回 1003 錯誤，提示不是一次有效的訊息覆蓋操作，當前的訊息不會被推播。
big_push_duration	Int	可選	定速推播時長(分鍾)	又名緩慢推播，把原本盡可能快的推播速度，降低下來，給定的 n 分鍾內，均勻地嚮這次推播的目標用戶推播；最大值為 1440。最多能同時存在 20 條定速推播。未設定則不是定速推播。
multi_language	json object	可選	多語言推送設置	推送內容多語言適配設置，詳情查看multi_language 說明。
third_party_channel	JSON Object	可選	Web 係統通道配置信息	僅針對配置了係統通道的用戶有效參數詳情查看 third_party_channel 說明。

multi_language

本字段是 EngageLab Push 服務的多語言推送功能。它允許您為不同語言的用戶推送定制化的通知內容。通過在推送請求中指定多個語言及對應的消息內容、標題和 iOS 子標題，您可以針對用戶的語言設置發送適當的推送通知。

請求參數

關鍵字	類型	選項	含義	說明
en	string	可選	多語言key	對應推送用戶語言，key碼詳見附錄
content	string	可選	消息內容	根據用戶語言替換notification.web.alert、message.msg_content裡的數據
title	string	可選	消息標題	根據用戶語言替換notification.web.title、message.title裡的數據

請求示例

http請求方式: Post 請求地址：/v4/push POST數據格式:json POST數據例子: { "options": { "multi_language": { "en": { "content": "", "title": "", } } } }

             http請求方式: Post
   請求地址：/v4/push
   POST數據格式:json
   POST數據例子:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
        }
      }
    }
   }

此代碼塊在浮窗中顯示

返回示例

成功時： { } 失敗時： { "code":400, "data":"", "message":"錯誤資訊" }

          成功時：
{
   
}

失敗時：
{   
    "code":400,  
    "data":"",
  "message":"錯誤資訊"
}

此代碼塊在浮窗中顯示

third_party_channel

本字段用來填寫 Web 係統通道的個性化信息，key 名稱為 w3push ，value 值為一個 Json Object 對象,該對象裏面僅包含一個可選的 distribution 字段，類型為 String 本字段用來填寫 Web 係統通道的個性化信息，key 名稱為 w3push ，value 值為一個 Json Object 對象,該對象裏面僅包含一個可選的 distribution 字段，類型為 String

關鍵字	類型	選項	含義	說明
distribution	必選	String	Engagelab 和係統通道並存時，設定下發優先級	取值不能為空字符串。 first_ospush：表示推播優先走係統通道下發，無效走 Engagelab 通道下發。 mtpush：表示推播強製走 Engagelab 通道下發。 secondary_push：表示推播優先走 Engagelab ，Engagelab 不在線再走係統通道，係統通道作為輔助（建議此種方式)。 ospush：表示推播強制僅走系統頻道下發。

調用示例如下：

{ "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

          {
  "third_party_channel":{
    "w3push":{
      "distribution":"mtpush"
    }
  }
}

此代碼塊在浮窗中顯示

request_id

請求 id，客戶自訂的可選字段。客戶用來標識是哪條請求，回響時返回。

請求示例

{ "request_id":"12345678" }

          {
      "request_id":"12345678"
}

此代碼塊在浮窗中顯示

返回示例

{ "msg_id": "1225764", "request_id": "12345678" }

          {
    "msg_id": "1225764",
    "request_id": "12345678"
}

此代碼塊在浮窗中顯示

custom_args

客戶自訂的，可選字段，回響時不返回，回調時返回。

{ "custom_args":"business info" }

          {
  "custom_args":"business info"
}

此代碼塊在浮窗中顯示

返回參數

成功返回

字段	類型	選項	描述
request_id	String	可選	請求時提交的自定義 ID，響應時原樣返回。
message_id	String	必選	消息 ID，唯一標識某一條消息。

< HTTP/1.1 200 OK < Content-Type: application/json {"request_id":"18","msg_id":"1828256757"}

          < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

此代碼塊在浮窗中顯示

失敗返回

http 狀態碼為 4xx 或者 5xx，響應體包含字段如下：

字段	類型	選項	描述
code	int	必選	錯誤碼，詳見錯誤碼說明
message	String	必選	錯誤詳情

{ "code": 3002, "message": "Push.template field must be set correctly when type is template" }

          {
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
}

此代碼塊在浮窗中顯示

調用返回

HTTP 狀態碼

參考文檔：HTTP-Status-Code

錯誤碼

Code	描述	詳細解釋	HTTP Status Code
20101	推播參數無效	registration_id 無效或不屬於當前 appkey	400
21001	隻支持 HTTP Post 方法	不支持 Get 方法	405
21002	缺少了必須的參數	必須改正	400
21003	參數值不合法	必須改正	400
21004	驗證失敗	必須改正，詳情請看：調用驗證	401
21005	訊息體太大	必須改正，Notification+Message 長度限製為 2048 字節	400
21008	app_key 參數非法	必須改正，請仔細對比你所傳的 appkey 是否與應用程式資訊中的一緻，是否多了空格	400
21009	係統內部錯誤	必須改正	400
21011	冇有滿足條件的推播目標	請檢查 to 字段	400
21015	請求參數校驗失敗	存在非預期的參數	400
21016	請求參數校驗失敗	參數類型錯誤，或者參數長度超出限製	400
21030	內部服務超時	稍後重試	503
23006	參數錯誤	定速推播 big_push_duration 超過最大值 1440	400
23008	接口限速	單應用推送接口 qps 達到上限(500 qps)	400
27000	係統記憶體錯誤	請重試	500
27001	參數錯誤	校驗信息為空	401
27008	參數錯誤	third_party_channel 裏面的 distribution 不為空，但是 notification 的 alert 內容為空	401
27009	參數錯誤	third_party_channel 中 distribution 格式無效或為空	401

推播限製

係統通道	標題長度	內容長度	其他說明
Engagelab 通道	不限製，但限製訊息體總大小	不限製，但限製訊息體總大小	MTPush 中 Notification + Message 長度限製為 4000 個字節。
係統通道	＜ 20 個字符（40 個英文字符）	通知中心和鎖屏狀態最多顯示 110 個字符，55 個漢字。頂部彈窗最多顯示 62 個字符，31 個漢字，超過部分會顯示省略號。	暫無

多語言碼

Language	Language Code
English	en
Arabic	ar
Chinese (Simplified)	zh-Hans
Chinese (Traditional)	zh-Hant
Czech	cs
Danish	da
Dutch	nl
French	fr
German	de
Hindi	hi
Italian	it
Japanese	ja
Korean	ko
Malay	ms
Russian	ru
Spanish	es
Thai	th
Vietnamese	vi
Indonesian	id
Norwegian	no
Swedish	sv
Polish	pl
Turkish	tr
Hebrew	he
Portuguese	pt
Romanian	ro
Hungarian	hu
Finnish	fi
Greek	el