Push API v4
最新更新:2023-03-02

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==
          > 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": "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 一起二者必須有其一,二者不可以並存。
  • 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 個。

    請求示例

    • 推播給全部(廣播):
    { "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 一起二者必須有其一,二者不可以並存。
  • message JSON Object 可選
  • 訊息內容體,是被推播到客戶端的內容。
  • 與 notification 一起二者必須有其一,二者不可以並存。
  • options JSON Object 可選 推播參數

    platform

    MTPush 當前支持 Android, iOS 平台的推播。其關鍵字分別為:"android", "ios"。

    如果目標平台為 iOS 平台,需要在 options 中通過 apns_production 字段來製定推播環境。True 表示推播生産環境,False 表示要推播開發環境; 如果不指定則為推播生産環境。

    推播到所有平台:

    { "platform" : "all" }
              { "platform" : "all" }
    
            
    此代碼塊在浮窗中顯示

    指定特定推播平台:

    { "platform": [ "android", "ios" ] }
              {
      "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" : {
        "alert" : "Hello, Push!"
      }
    }
    
            
    此代碼塊在浮窗中顯示

    上面定義的 notification 對象,將被推播到 "platform" 指定的多個平台,並且其通知 alert 信息都一樣。

    android

    Android 平台上的通知,被 MTPush SDK 按照一定的通知欄樣式展示。支持的字段如下:

    關鍵字 類型 選項 含義 說明
    alert String 或 JSON Object 必填 通知內容
  • 這裏指定後會覆蓋上級統一指定的 alert 信息。
  • 內容可以為空字符串,表示不展示到通知欄。
  • 各推播通道對此字段的限製詳見 推播限製
  • title String 可選 通知標題
  • 如果指定了,則通知裏原來展示 App 名稱的地方,將展示 title。
  • 各推播通道對此字段的限製詳見 推播限製
  • 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。
  • 1:bigText
  • 2:Inbox
  • 3:bigPicture
  • big_text String 可選 大文本通知欄樣式
  • 當 style = 1 時可用,內容會被通知欄以大文本的形式展示出來。
  • 支持 api 16 以上的 rom。
  • inbox JSONObject 可選 文本條目通知欄樣式
  • 當 style = 2 時可用, json 的每個 key 對應的 value 會被當作文本條目逐條展示。
  • 支持 api 16 以上的 rom。
  • big_pic_path String 可選 文本條目通知欄樣式
  • 當 style = 3 時可用,目前支持 .jpg 和 .png 格式的圖片。
  • 支持網路圖片 url、在地圖片的 path,如果是 http/https 的 url,會自動下載;如果要指定開發者準備的在地圖片就填 sdcard 的相對路徑。
  • 支持 api 16 以上的 rom。
  • extras JSON Object 可選 擴展字段 這裏自訂 JSON 格式的 Key/Value 信息,以供業務使用。
    intent JSON Object 可選 指定跳轉頁面(推薦) 使用 intent 裡的 url 指定點擊通知欄後跳轉的目標頁面。建議填寫 intent 字段,否則點擊通知可能無跳轉動作。此字段支持以下三種類型:
  • 跳轉到目標頁:
    intent:#Intent;action=action 路徑;component= 包名 /Activity 全名;end
  • 應用首頁: intent:#Intent;action=android.intent.action.MAIN;end (固定為此地址)
  • 跳轉到deeplink地址:
    scheme://test?key1=val1&key2=val2
  • large_icon String 可選 通知大圖示
  • 圖示大小不超過 300 k。
  • 支持網路圖片 url、在地圖片的 path,如果是 http/https 的 url,會自動下載;如果要指定開發者準備的在地圖片就填 sdcard 的相對路徑。
  • small_icon String 可選 通知小圖示
  • 通知小圖示,圖示路徑可以是以 http 或 https 開頭的網路圖片,大小不能超過 300 k。
  • 若冇有填充 廠商 small_icon_uri,則預設使用該 small_icon 字段展示。
  • sound String 可選 鈴聲
  • 填寫 Android 專案中 /res/raw/ 路徑下鈴聲文件名稱,無需文件名字尾。
  • 註意:針對 Android 8.0 以上,當傳遞了 channel_id 時,此屬性不生效。
  • badge_add_num Int 可選 設定角標數字纍加值,在原角標的基礎上進行纍加
  • 此屬性目前僅針對華為 EMUI 8.0 及以上、小米 MIUI 6 及以上、vivo 設備走廠商通道時生效。
  • 此字段如果不填,表示不改變角標數字(小米設備由於係統控製,不論推播走 Engagelab 通道下發還是廠商通道下發,即使不傳遞依舊是預設 +1 的效果)。
  • 取值範圍為:1-99,若設定了取值範圍內的數字,下一條通知欄訊息配置的 badge_add_num 數據會和原角標數量進行相加,建議取值為 1。
  • 舉例:badge_add_num 取值為 1,原角標數為 2,傳送此角標訊息後,應用程式角標數顯示為 3。
  • badge_class String 可選 桌面圖示對應的應用程式入口 Activity 類, 比如“com.test.badge.MainActivity”
  • 僅華為通道推播時生效,此值如果填寫非主 Activity 類,以廠商限製邏輯為準。
  • 若需要實現角標纍加功能,需配合 badge_add_num 使用,二者需要共存,缺少其一不可。
  • { "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" } } } }
              {
        "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 必填 通知內容
  • 這裏指定內容將會覆蓋上級統一指定的 alert 信息。
  • 內容為空則不展示到通知欄。
  • 支持字符串形式也支持官方定義的 alert payload
  • 結構,在該結構中包含 title 和 subtitle 等官方支持的 key。
  • sound String 或 JSON Object 可選 通知提示聲音
  • 普通通知: String 類型。
  • 如果無此字段,則此訊息無聲音提示;
  • 有此字段,如果找到了指定的聲音就播放該聲音,否則播放預設聲音。
  • 如果此字段為空字符串,iOS 7 為預設聲音,iOS 8 及以上係統為無聲音。
  • 告警通知: JSON Object , 支持官方定義的 payload 結構,在該結構中包含 critical 、name 和 volume 等官方支持的 key 。
  • badge Int 或 String 可選 應用程式角標
  • 可設定為 N、+N、-N,N 的取值範圍為 [0,99]。若上載的角標值 value 為 10,表示角標會設定為 N、10+N、10-N(值小於 0 時預設清除角標)。
  • 為 0 或空字符串,則表示清除角標。
  • 如果不填,表示不改變角標數字。
  • MTPush 官方 API Library(SDK) 會預設填充badge值為"+1"。
  • 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 字段完成設定。
  • true:說明支持 iOS 10 的UNNotificationServiceExtension 功能。
  • 如果不攜帶此字段則是普通的 Remote Notification,無法統計抵達數據。
  • 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" } } } }
              {
        "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; }
              {
      "_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" } } }
              {
      "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 Android 端用戶已經收到,如果通知欄還未清除,則新的訊息內容會覆蓋之前這條通知。
  • 覆蓋功能起作用的時限是:1 天,如果在覆蓋指定時限內該 msg_id 不存在,則返回 7006 錯誤,提示不是一次有效的訊息覆蓋操作,當前的訊息不會被推播。
  • 該字段僅對 Android 有效僅支持Engagelab 通道、小米通道、魅族通道、OPPO 通道、FCM 通道、華為通道(EMUI10 及以上的設備)。
  • apns_production Boolean 可選 APNs 是否生産環境 該字段僅對 iOS 的 Notification 有效,如果不指定則為推播生産環境。註意:MTPush 官方 API LIbrary (SDK) 預設設定為推播 “開發環境”。
  • true:表示推播生産環境。
  • false:表示推播開發環境。
  • apns_collapse_id String 可選 更新 iOS 通知的標識符
  • APNs 新通知如果匹配到當前通知中心有相同 apns-collapse-id 字段的通知,則會用新通知內容來更新它,並使其置於通知中心首位。
  • collapse id 長度不可超過 64 bytes。
  • big_push_duration Int 可選 定速推播時長(分鍾)
  • 又名緩慢推播,把原本盡可能快的推播速度,降低下來,給定的 n 分鍾內,均勻地嚮這次推播的目標用戶推播;最大值為 1440。
  • 最多能同時存在 20 條定速推播。
  • 未設定則不是定速推播。
  • 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": "" } } } }
                 http請求方式: Post
       請求地址:/v4/grouppush 或者 /v4/push
       POST數據格式:json
       POST數據例子:
       {
        "options": {
          "multi_language": {
            "en": {
              "content": "",
              "title": "",
              "ios_subtitle": ""
            }
          }
        }
       }
    
            
    此代碼塊在浮窗中顯示
    返回示例
    成功時: { } 失敗時: { "code":400, "data":"", "message":"錯誤信息" }
              成功時:
    {
       
    }
        
    失敗時:
    {   
        "code":400,    
        "data":"",
      "message":"錯誤信息"
    }   
    
            
    此代碼塊在浮窗中顯示

    third_party_channel

    本字段用來填寫 Android 廠商通道的個性化信息,key 隻支持 xiaomi、huawei、meizu、oppo、vivo、fcm 這6 個 Android 廠商通道,可以為其中一個或者多個同時存在,每個廠商類型的 KEY 當前可包含如下幾個可選項:

    關鍵字 類型 選項 含義 說明
    distribution_new String 必選 Engagelab 和廠商通道並存時,設定下發優先級 取值不能為空字符串。
  • mtpush:表示推送强制走 Engagelab 通道下发。
  • pns_mtpush:表示表示针对 fcm+ 国内厂商组合类型用户,推送强制优先走小米 / 华为 / 魅族 /oppo/vivo/荣耀 通道下发,无效再走engagelab通道。
  • mtpush_pns:表示针对 fcm+ 国内厂商组合类型用户,推送优先走engagelab,engagelab不在线再走厂商通道,厂商作为辅助。
  • fcm_mtpush:表示表示针对 fcm+ 国内厂商组合类型用户,推送强制优先走 fcm 通道下发,无效再走engagelab通道
  • mtpush_fcm:表示针对 fcm+ 国内厂商组合类型用户,推送优先走engagelab,engagelab不在线再走 fcm 通道,fcm 作为辅助。
    注:针对pns_mtpush/fcm_mtpush/mtpush_pns/mtpush_fcm这四种策略而言,如果设备可用的系统推送通道仅有一种(FCM或者手机厂商),则会忽略强制优先级,走集成成功的系统通道。
  • channel_id String 可選 通知欄訊息分類 支持 OPPO 的私信小米的通知訊息華為訊息分類 類別,分類 ChannelID 值需開發者自行嚮廠商申請。
    classification Int 可選 通知欄訊息分類 vivo 手機廠商通知欄訊息分類,不填預設為 0。
  • 0:代錶營運訊息。
  • 1:代錶係統訊息。目前 vivo 對係統訊息分類較為嚴格,具體規則參考:vivo。
  • pushMode Int 可選 vivo推播模式 不填預設為 0。詳情參考 vivo pushMode,使用測試推播需要手動在 vivo 後台配置測試設備的 ID 。
  • 0:表示正式推播。
  • 1:表示測試推播。
  • importance String 可選 華為通知欄訊息智能分類 為了適配華為手機廠商的通知欄訊息智能分類,對應華為的 importance 字段,不填充預設為 "NORMAL",參考:華為通知訊息智能分類
  • LOW:一般訊息。
  • NORMAL:重要訊息。
  • HIGH:非常重要訊息。
  • urgency String 可選 華為廠商自訂訊息優先級 為了適配華為手機廠商自訂訊息的優先級。
  • HIGH:非常重要訊息,HIGH 級別訊息到達用戶手機時可強製拉起應用程式進程。
  • NORMAL:重要訊息。設定“HIGH”需要嚮華為申請特殊權限,參考:特殊權限如何申請
  • category String 可選 華為廠商自訂訊息場景標識 為了適配華為手機廠商自訂訊息,標識高優先級透傳訊息的特殊場景,或用於標識訊息類型以對特定類型訊息加快傳送,對應值及其說明參考:category 值說明
    small_icon_uri String 可選 廠商訊息小圖示樣式
  • 目前支持小米 / 華為廠商。
  • 優先使用廠商字段, 廠商字段冇有填充,則使用 android 內的 small_icon 字段。
  • 小米支持 小米廠商的大圖示 id,華為、支持 Engagelab 的 media_id 及廠商在地路徑。(小米官方後續不再支持自訂小圖示,建議開發者不要繼續使用小米 small Icon 相關特性功能)。
  • small_icon_color String 可選 小米廠商小圖示樣式顔色
  • 為了適配小米廠商的訊息小圖示樣式顔色,不填充預設是灰色 (小米官方後續不在支持自訂小圖示,建議開發者不要繼續使用小米 small icon 相關特性功能)。
  • only_use_vendor_style Boolean 可選 是否使用自身通道設定樣式 是否隻使用自身通道設定的樣式,不使用 android 裏面設定的樣式,預設為 false,
  • true:隻使用自身通道設定的樣式。
  • false:可使用 android 裏面設定的樣式。
  • 調用示例如下:

    "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 } }
              "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" }
              {
          "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
    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 個字符 禁止特殊字符,如:#
  • 中英文字符均計算為 1 個字符。
  • 部分訊息可能會存入魅族手機右上角【魅族訊息盒子】中。
  • 小米通道 < 50 個字符 < 128 個字符 禁止特殊字符,如:#、>>
  • 中英文字符均計算為 1 個字符。
  • 部分訊息可能會存在通知欄的不重要通知裏。
  • OPPO 通道 < 32 個字符 < 200 個字符 暫無說明
  • 中英文字符均計算為 1 個字符。
  • 預設關閉通知權限。
  • vivo 通道 < 40 個字符 < 100 個字符
  • 禁止特殊字符,如:#、>>
  • 正式訊息禁止:純數字、純英文、純符號、符號加數字,測試、test、大括號、中括號等
  • 英文為 1 個字符,中文為 2 個字符。
  • 預設關閉通知權限。
  • 同設備 1 天內營運訊息的推播條數不能超過 5 條。
  • 同設備 1 天內不能重複推播內容相同的營運訊息。
  • APNS 通道 < 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
    泰語 Turkish th
    越南語 Vietnamese vi
    在文档中心打开