Push API v4

最新更新:2024-05-08

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

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

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

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

請求頻率限制

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

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

調用驗證

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

調用地址

POST https://webpush.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": "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 個。

    請求示例

    • 推播給全部(廣播):
    { "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
    Turkish th
    Vietnamese vi
    Indonesian id
    Norwegian no
    Swedish sv
    Polish pl
    Turkish tr
    Hebrew he
    在文档中心打开