創建推送 API
向某單個設備或者某設備列表推送一條通知、或者消息。
推送的內容只能是 JSON 表示的一個推送對象。
這是 Push API 最近的版本。 v4 版本的改進為:
- 使用 HTTP Basic Authentication 的方式做訪問授權。這樣整個 API 請求可以使用常見的 HTTP 工具來完成,比如:curl,瀏覽器插件等。
- 推送內容完全使用 JSON 的格式。
請求方式
POST
調用地址
接口服務地址與數據中心選擇接入點一一對應,請選擇與您的應用服務接入點對應的 調用地址。
目EngageLab已部署支持了兩個數據中心接入點,不同服務接入點之間數據完全隔離,您可根據創建產品時選擇的數據中心接入點選擇調用地址。
- 新加坡數據中心調用地址:
POST https://push.api.engagelab.cc/v4/push
- 美國弗吉尼亞數據中心調用地址
POST https://push-usva.api.engagelab.cc/v4/push
調用驗證
詳情參見 REST API 概述的 鑒權方式 說明。
請求示例
請求頭
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
請求體
{
"from": "push",
"to": "all",
"body": {
"platform": "all",
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"builder_id": 1,
"extras": {
"newsid": 321
}
},
"ios": {
"alert": "Hi, MTPush!",
"sound": "default",
"badge": "+1",
"extras": {
"newsid": 321
}
}
},
"message": {
"msg_content": "Hi,MTPush",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}
},
"request_id": "12345678",
"custom_args": "business info"
}'
> POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
請求參數
推送的參數結構體,詳見下表:
關鍵字 | 類型 | 選項 | 含義 |
---|---|---|---|
from | String | 可選 | 當前業務發送方 |
to | String 或 JSON Object | 必填 | 發送目標 |
body | JSON Object | 必填 | 發送請求體 |
platform | String 或 JSON Array | 必填 | 推送平臺 |
notification | JSON Object | 可選 | |
message | JSON Object | 可選 | |
options | JSON Object | 可選 | 推送參數 |
request_id | String | 可選 | 客戶自定義的可選字段,客戶用來標識是哪條請求,響應時返回。 |
custom_args | JSON Object | 可選 | 客戶自定義的可選字段,回調時返回給客戶。 |
from
當前業務發送方,String 類型,可選字段。
請求示例
{
"from":"push"
}
to
推送設備對象,表示一條推送可以被推送到哪些設備列表。確認推送設備對象,App Push 提供了多種方式,比如:別名、標簽、註冊ID、分群、廣播等。
推送目標
廣播外的設備選擇方式,有如下幾種:
關鍵字 | 類型 | 含義 | 說明 | 備註 |
---|---|---|---|---|
all | String | 发广播 | 給全部設備進行推送 | 推送目標為30天內活躍過的設備。 |
tag | JSON Array | 標簽 | 數組。多個標簽之間是 OR 的關系,即取並集。 | 用標簽來進行大規模的設備屬性、用戶屬性分群。 |
tag_and | JSON Array | 標簽AND | 數組。多個標簽之間是 AND 關系,即取交集。 | 註意與 tag 區分,一次推送最多 20 個。 |
tag_not | JSON Array | 標簽NOT | 數組。多個標簽之間,先取多標簽的並集,再對該結果取補集。 | 一次推送最多 20 個。 |
alias | JSON Array | 別名 | 數組。多個別名之間是 OR 關系,即取並集。 | 用別名來標識一個用戶。 |
registration_id | JSON Array | 註冊ID | 數組。多個註冊ID之間是 OR 關系,即取並集。 | 設備標識。一次推送最多 1000 個。 |
數組裏多個值之間隱含的關系是是 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":{
"tag":[
"深圳",
"廣州",
"北京"
]
}
}
- 推送給多個標簽(需要同時在多個標簽範圍內):在深圳並且是「女」
{
"to":{
"tag_and":[
"深圳",
"女"
]
}
}
- 推送給多個別名:
{
"to":{
"alias":[
"4314",
"892",
"4531"
]
}
}
- 推送給多個註冊ID:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
- 可同時推送指定多類推送目標:在深圳或者廣州,並且是 「女」 「會員」
{
"to":{
"tag":[
"深圳",
"廣州"
],
"tag_and":[
"女",
"會員"
]
}
}
body
發送請求體。支持的字段如下:
關鍵字 | 類型 | 選項 | 含義 |
---|---|---|---|
platform | String 或 JSON Array | 必填 | 推送平台 |
notification | JSON Object | 可選 | |
message | JSON Object | 可選 | |
options | JSON Object | 可選 | 推送參數 |
platform
MTPush 当前支持 Android, iOS 平台的推送。其關鍵字分别为:"android", "ios"。
如果目标平台为 iOS 平台,需要在 options 中通过 apns_production 字段来制定推送环境。True 表示推送生产环境,False 表示要推送开发环境; 如果不指定则为推送开发环境。
推送到所有平台:
{ "platform" : "all" }
指定特定推送平台:
{
"platform": [
"android",
"ios"
]
}
notification
“通知”对象,是一条推送的实体内容对象之一(另一个是“消息”),是会作为“通知”推送到客户端的。
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
alert | String 或 JSON Object | 必填 | 內容 | 消息內容本身。若 android、ios 下沒有指定 alert,則以此為準。 |
android | JSON Object | 選填 | android 平臺屬性 | android 平臺推送參數,詳見android 說明 |
ios | JSON Object | 選填 | ios 平臺屬性 | ios 平臺推送參數,詳見ios 說明 |
alert
這個位置的 "alert" 屬性(直接在 notification 對象下),是一個快捷定義,各平臺的 alert 信息如果都一樣,則可不定義平臺下的 alert,以此為準。如果各平臺有定義,則覆蓋這裏的定義。
{
"notification" : {
"alert" : "Hello, Push!"
}
}
上面定義的 notification 對象,將被推送到 "platform" 指定的多個平臺,並且其通知 alert 信息都一樣。
Android
Android平台上的通知是由MTPush SDK以特定的通知樣式顯示的。支援的欄位如下:
關鍵字 | 數據類型 | 可選 | 意義 | 說明 |
---|---|---|---|---|
alert | String或JSON對象 | 必填 | 通知內容 | |
title | String | 可選 | 通知標題 | |
builder_id | Int | 可選 | 通知欄樣式ID | Android SDK可以設置自定義通知佈局,這裡根據樣式ID來指定使用哪套樣式。 |
channel_id | String | 可選 | Android通知欄通道ID | 不超過1000字節,從Android 8.0開始,您可以配置通知通道。此字段根據通道ID指定通知欄的顯示效果。 |
priority | Int | 可選 | 通知欄顯示優先級 | 默認值為0,範圍為-2~2。 |
category | String | 可選 | 通知欄條目過濾或排序 | 完全依賴於ROM製造商對類別的處理策略。 |
style | Int | 可選 | 通知欄樣式類型 | 用於指定通知欄樣式類型,默認為0。 |
big_text | String | 可選 | 大文本通知欄樣式 | |
inbox | JSONObject | 可選 | 文本條目通知欄樣式 | |
big_pic_path | String | 可選 | 大圖片通知欄樣式 | |
extras | JSON對象 | 可選 | 額外字段 | 在JSON格式中自定義的Key/Value信息,供業務使用。 |
intent | JSON對象 | 可選 | 指定跳轉頁面(推薦) | 使用intent字段中的URL指定單擊通知欄後要跳轉的目標頁面。建議填寫intent字段,否則單擊通知可能無法執行跳轉操作。此字段支持以下三種類型: |
large_icon | String | 可選 | 通知大圖標 | |
small_icon | String | 可選 | 通知小圖標 | |
sound | String | 可選 | 鈴聲 | |
badge_add_num | Int | 可選 | 設置角標數字累加值,在原角標的基礎上進行累加 | |
badge_class | String | 可選 | 桌面圖標對應的應用程序入口Activity類,例如“com.test.badge.MainActivity” | |
display_foreground | String | 可選 | 應用程序在前台時,是否應該顯示通知 |
|
{
"notification": {
"android": {
"alert": "hello, MTPush!",
"title": "Push test",
"builder_id": 3,
"style": 1,
"big_text": "big text content",
"inbox":JSONObject,
"big_pic_path": "picture url",
"priority": 0,
"category": "category str",
"large_icon": "http://push.api.engagelab.cc/largeIcon.jpg",
"small_icon": "http://www.small.com/small_icon.jpg",
"intent": {
"url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end"
},
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
ios
iOS 平臺上 APNs 通知。
該通知內容會由 MTPush 代理發往 Apple APNs 服務器,並在 iOS 設備上在系統通知的方式呈現。
該通知內容滿足 APNs 的規範,支持的字段如下:
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
alert | String 或 JSON Object | 必填 | 通知內容 | |
sound | String 或 JSON Object | 可選 | 通知提示聲音 | |
badge | Int 或 String | 可選 | 應用角標 | |
content-available | Boolean | 可選 | 推送喚醒 | 推送的時候攜帶"content-available":true 說明是 Background Remote Notification,如果不攜帶此字段則是普通的Remote Notification。詳情參考:Background Remote Notification |
mutable-content | Boolean | 可選 | 通知擴展 | iOS 10 新增的 Notification Service Extension 功能,用於上報每條 APNs 信息的送達狀態,使用該功能需要客戶端實現 Service Extension 接口,並在服務端使用 mutable-content 字段完成設置。 |
category | String | 可選 | iOS 8 才支持。設置APNs payload中的"category"字段值。 | |
extras | JSON Object | 可選 | 擴展字段 | 這裏自定義 Key/value 信息,以供業務使用。 |
thread-id | String | 可選 | 通知分組 | iOS 的遠程通知通過該屬性來對通知進行分組,同一個 thread-id 的通知歸為一組。 |
interruption-level | String | 可選 | 通知優先級和交付時間的中斷級別 | iOS 15 的通知級別,取值只能是 active,critical,passive,timeSensitive 中的一個,詳情參考:UNNotificationInterruptionLevel。 |
iOS 通知 MTPush 要轉發給 APNs 服務器。 MTPush 中 Notification + Message 長度限製為 4000 個字節。 MTPush 在推送時使用 utf-8 編碼,所以一個漢字占用 3 個字節長度。
服務端發送示例:
{
"notification": {
"ios": {
"alert": "hello, Push!",
"sound": "sound.caf",
"badge": 1,
"extras": {
"news_id": 134,
"my_key": "a value"
}
}
}
}
客戶端收到的消息:
{
"_j_msgid" = 813843507;
aps = {
alert = "hello,Push!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}
message
應用內消息。或者稱作:自定義消息,透傳消息。
- 此部分內容不會展示到通知欄上,MTPush SDK 收到消息內容後透傳給 App。App 需要自行處理。
- iOS 在推送應用內消息通道(非 APNS)獲取此部分內容,需 App 處於前臺。
支持的字段如下:
關鍵字 | 類型 | 選項 | 含義 |
---|---|---|---|
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"
}
}
}
options
推送可選項。當前包含如下幾個可選項:
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
time_to_live | Int 或 String | 可選 | 離線消息保留時長(秒) | |
override_msg_id | Long | 可選 | 要覆蓋的消息 ID | 如果當前的推送要覆蓋之前的一條推送,這裏填寫前一條推送的 msg_id 就會產生覆蓋效果,即: |
apns_production | Boolean | 可選 | APNs 是否生產環境 | 該字段僅對 iOS 的 Notification 有效,如果不指定則為推送开发環境。註意:MTPush 官方 API LIbrary (SDK) 默認設置為推送 「開發環境」。 |
apns_collapse_id | String | 可選 | 更新 iOS 通知的標識符 | |
big_push_duration | Int | 可選 | 定速推送時長(分鐘) | |
multi_language | json object | 可選 | 多語言推送設置 | 推送內容多語言適配設置,詳情查看multi_language 說明。 |
third_party_channel | JSON Object | 可選 | Android 廠商通道配置信息 | 僅針對配置了廠商通道的用戶有效參數,詳情查看third_party_channel 說明。 |
multi_language
本字段是 EngageLab Push 服務的多語言推送功能。它允許您為不同語言的用戶推送定製化的通知內容。通過在推送請求中指定多個語言及對應的消息內容、標題和 iOS 子標題,您可以針對用戶的語言設置發送適當的推送通知。
請求參數
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
en | string | 可選 | 多語言key | 對應推送用戶語言,key碼詳見附錄 |
content | string | 可選 | 消息內容 | 根據用戶語言替換notification.android.alert、notification.ios.alert、notification.web.alert、message.msg_content裏的數據 |
title | string | 可選 | 消息標題 | 根據用戶語言替換notification.android.title、notification.ios.alert、notification.web.title、message.title裏的數據 |
ios_subtitle | string | 可選 | ios子標題 | 根據用戶語言替換notification.ios.alert裏的數據 |
請求示例
http請求方式: Post
請求地址:/v4/grouppush 或者 /v4/push
POST數據格式:json
POST數據例子:
{
"options": {
"multi_language": {
"en": {
"content": "",
"title": "",
"ios_subtitle": ""
}
}
}
}
返回示例
成功時:
{
}
失敗時:
{
"code":400,
"data":"",
"message":"錯誤信息"
}
third_party_channel
本字段用來填寫 Android 廠商通道的個性化信息,key 只支持 xiaomi、huawei、meizu、oppo、vivo、fcm、honor 這 7 個 Android 廠商通道,可以為其中一個或者多個同時存在,每個廠商類型的 KEY 當前可包含如下幾個可選項:
註:多個key存在的情況下,distribution_new取值以廠商通道(xiaomi、huawei、meizu、oppo、vivo、honor)的設置為準。
請求參數
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
distribution_new | String | 必選 | Engagelab 和廠商通道並存時,設置下發優先級 | 取值不能為空字符串。 |
channel_id | String | 可選 | 通知欄消息分類 | 支持OPPO 的私信、小米的通知消息、華為消息分類 類別,分類 ChannelID 值需開發者自行向廠商申請。 |
classification | Int | 可選 | 通知欄消息分類 | vivo 手機廠商通知欄消息分類,不填默認為 0。 |
pushMode | Int | 可選 | vivo推送模式 | 不填默認為 0。詳情參考vivo pushMode,使用測試推送需要手動在 vivo 後臺配置測試設備的 ID 。 |
importance | String | 可選 | 華為/榮耀通知欄消息智能分類 | 為了適配華為手機廠商的通知欄消息智能分類,對應華為的 importance 字段,不填充默認為 "NORMAL",參考:華為通知消息智能分類。 |
urgency | String | 可選 | 華為廠商自定義消息優先級 | 為了適配華為手機廠商自定義消息的優先級。 |
category | String | 可選 | 華為廠商自定義消息場景標識 | 為了適配華為手機廠商自定義消息,標識高優先級透傳消息的特殊場景,或用於標識消息類型以對特定類型消息加快發送,對應值及其說明參考:category 值說明。 |
small_icon_uri | String | 可選 | 廠商消息小圖標樣式 | |
small_icon_color | String | 可選 | 小米廠商小圖標樣式顏色 | 為了適配小米廠商的消息小圖標樣式顏色,不填充默認是灰色 (小米官方後續不在支持自定義小圖標,建議開發者不要繼續使用小米 small icon 相關特性功能)。 |
big_text | String | 可選 | 廠商消息大文本樣式 | |
only_use_vendor_style | Boolean | 可選 | 是否使用自身通道設置樣式 | 是否只使用自身通道設置的樣式,不使用 android 裏面設置的樣式,默認為 false, |
請求示例
"third_party_channel": {
"xiaomi": {
"distribution_new": "mtpush",
"channel_id": "*******",
"small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
"small_icon_color": "#ABCDEF",
},
"huawei": {
"distribution_new": "mtpush_pns",
"importance": "NORMAL",
"small_icon_uri": "https://xx.com/xx.jpg",
"only_use_vendor_style": true
},
"meizu": {
"distribution_new": "mtpush"
},
"fcm": {
"distribution_new": "mtpush"
},
"oppo": {
"distribution_new": "mtpush",
"channel_id": "*******",
"large_icon": "3653918_5f92b5739ae676f5745bcbf4",
},
"vivo": {
"distribution_new": "mtpush",
"classification": 0,
"pushMode": 0
}
}
request_id
請求 id,客戶自定義的可選字段。客戶用來標識是哪條請求,響應時返回。
請求示例
{
"request_id":"12345678"
}
返回示例
{
"msg_id": "1225764",
"request_id": "12345678"
}
custom_args
客戶自定義的,可選字段,響應時不返回,回調時返回。
請求示例
{
"custom_args":{
"args1": "args1"
}
}
返回參數
成功返回
字段 | 類型 | 選項 | 描述 |
---|---|---|---|
request_id | String | 可選 | 請求時提交的自定義 ID,響應時原樣返回。 |
message_id | String | 必選 | 消息 ID,唯一標識某一條消息。 |
< 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"
}
調用返回
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 |
21038 | 權益權限錯誤 | VIP已過期或未開通 | 401 |
21306 | 參數錯誤 | 通知訊息和自訂訊息不能同時活躍 | 401 |
推送限製
廠商通道 | 標題長度 | 內容長度 | 敏感詞 | 其他說明 |
---|---|---|---|---|
Engagelab 通道 | < 50 個字符 | 不限製,但限製消息體總大小 | - | MTPush 中 Notification + Message 長度限製為 4000 個字節。 |
華為通道 | < 40 個字符 | < 1024 字符 | 禁止攜帶政府,領導人名稱、臺獨等相關內容 | 默認【營銷通知】的權限為靜默通知,靜默推送沒有聲音、震動等提示。 |
榮耀通道 | 不限製,但消息體總大小<4096字節 | 不限製,但消息體總大小 < 4096 字節 | 禁止攜帶政府,領導人名稱、臺獨等相關內容 | - |
魅族通道 | < 32 個字符 | < 100 個字符 | 禁止特殊字符,如:# | |
小米通道 | < 50 個字符 | < 128 個字符 | 禁止特殊字符,如:#、>> | |
OPPO 通道 | < 32 個字符 | < 200 個字符 | 暫無說明 | |
vivo 通道 | < 40 個字符 | < 100 個字符 | ||
APNS 通道 | < 20 個字符(40 個英文字符) | 暫無說明 | 暫無 |
多語言碼
語言 | 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 |
泰語 | Turkish | th |
越南語 | Vietnamese | vi |