Push API v4
嚮某單個設備或者某設備列表推播一條通知、或者訊息。 推播的內容隻能是 JSON 表示的一個推播對象。
這是 Push API 最近的版本。v4 版本的改進為:
- 使用 HTTP Basic Authentication 的方式做訪問授權。這樣整個 API 請求可以使用常見的 HTTP 工具來完成,比如:curl,瀏覽器插件等。
- 推播內容完全使用 JSON 的格式。
調用驗證
詳情參見 REST API 概述的 鑒權方式 說明。
調用地址
POST https://push.api.engagelab.cc/v4/push
請求示例
請求頭
> POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
請求體
{
"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"
}
請求參數
推播的參數結構體,詳見下表:
關鍵字 | 類型 | 選項 | 含義 |
---|---|---|---|
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
推播設備對象,表示一條推播可以被推播到哪些設備列表。確認推播設備對象,MTPush 提供了兩種方式,分別是廣播和註冊 ID。
推播目標
關鍵字 | 類型 | 含義 | 說明 | 備註 |
---|---|---|---|---|
all | String | 發廣播 | 給全部設備進行推播 | 推播目標為 30 天內活躍過的設備。 |
registration_id | JSON Array | 註冊 ID | 多個註冊 ID 之間是 OR 關係,即取並集。 | 設備標識。一次推播最多 1000 個。 |
請求示例
- 推播給全部(廣播):
{
"to": "all",
}
- 推播給多個註冊 ID:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
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 Object | 必填 | 通知內容 | |
title | String | 可選 | 通知標題 | |
builder_id | Int | 可選 | 通知欄樣式ID | Android SDK 可 設定通知欄樣式,這雷根據樣式 ID 來指定該使用哪套樣式。 |
channel_id | String | 可選 | Android 通知欄通道 ID | 不超過 1000 字節,Android 8.0 開始可以進行NotificationChannel 配置,這雷根據 channel ID 來指定通知欄展示效果。 |
priority | Int | 可選 | 通知欄展示優先級 | 預設為 0,範圍為 -2~2。 |
category | String | 可選 | 通知欄條目過濾或排序 | 完全依賴 rom 廠商對 category 的處理策略。 |
style | Int | 可選 | 通知欄樣式類型 | 用來指定通知欄樣式類型,預設為 0。 |
big_text | String | 可選 | 大文本通知欄樣式 | |
inbox | JSONObject | 可選 | 文本條目通知欄樣式 | |
big_pic_path | String | 可選 | 文本條目通知欄樣式 | |
extras | JSON Object | 可選 | 擴展字段 | 這裏自訂 JSON 格式的 Key/Value 信息,以供業務使用。 |
intent | JSON Object | 可選 | 指定跳轉頁面(推薦) | 使用 intent 裡的 url 指定點擊通知欄後跳轉的目標頁面。建議填寫 intent 字段,否則點擊通知可能無跳轉動作。此字段支持以下三種類型: intent:#Intent;action=action 路徑;component= 包名 /Activity 全名;end scheme://test?key1=val1&key2=val2 |
large_icon | String | 可選 | 通知大圖示 | |
small_icon | String | 可選 | 通知小圖示 | |
sound | String | 可選 | 鈴聲 | |
badge_add_num | Int | 可選 | 設定角標數字纍加值,在原角標的基礎上進行纍加 | |
badge_class | String | 可選 | 桌面圖示對應的應用程式入口 Activity 類, 比如“com.test.badge.MainActivity” |
{
"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 分类 | 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 這6 個 Android 廠商通道,可以為其中一個或者多個同時存在,每個廠商類型的 KEY 當前可包含如下幾個可選項:
關鍵字 | 類型 | 選項 | 含義 | 說明 |
---|---|---|---|---|
distribution_new | String | 必選 | Engagelab 和廠商通道並存時,設定下發優先級 | 取值不能為空字符串。 注:针对pns_mtpush/fcm_mtpush/mtpush_pns/mtpush_fcm这四种策略而言,如果设备可用的系统推送通道仅有一种(FCM或者手机厂商),则会忽略强制优先级,走集成成功的系统通道。 |
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 | 可選 | 小米廠商小圖示樣式顔色 | |
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":"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 狀態碼為 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 |
27000 | 係統記憶體錯誤 | 請重試 | 500 |
27001 | 參數錯誤 | 校驗信息為空 | 401 |
27008 | 參數錯誤 | third_party_channel 裏面的 distribution 不為空,但是 notification 的 alert 內容為空 | 401 |
27009 | 參數錯誤 | third_party_channel 中 distribution 格式無效或為空 | 401 |
推播限製
廠商通道 | 標題長度 | 內容長度 | 敏感詞 | 其他說明 |
---|---|---|---|---|
Engagelab 通道 | 不限製,但限製訊息體總大小 | 不限製,但限製訊息體總大小 | - | MTPush 中 Notification + Message 長度限製為 4000 個字節。 |
華為通道 | < 40 個字符 | < 1024 字符 | 禁止攜帶政府,領導人名稱、台獨等相關內容 | 預設【營銷通知】的權限為靜默通知,靜默推播冇有聲音、震動等提示。 |
魅族通道 | < 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 |