logo
繁體中文
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
聯絡我們
登錄
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTPicon Marketing Automation
EngageLab 檔案 >AppPush >REST API >建立推播 API
EngageLab 檔案 >AppPush >REST API >建立推播 API

建立推播 API

最新更新：2024-04-16

向某單個設備或者某設備列表推播一條通知、或者消息。 推播的內容只能是 JSON 表示的一個推播對象。

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

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

請求頻率限制

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

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

請求方式

POST

調用地址

接口服務地址與數據中心選擇接入點一一對應，請選擇與您的應用服務接入點對應的 調用地址。

目前EngageLab已部署支持了兩個數據中心接入點，不同服務接入點之間數據完全隔離，您可根據創建產品時選擇的數據中心接入點選擇調用地址。

  • 新加坡數據中心調用地址：
POST /v4/push
          POST /v4/push
此代碼塊在浮窗中顯示

調用驗證

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

請求示例

請求頭

> POST /v4/push HTTP/1.1 > Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
          > POST /v4/push HTTP/1.1
> Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
此代碼塊在浮窗中顯示

請求體

{ "from": "push", "to": "all", "body": { "platform": "all", "notification": { "alert" :"Hello, Push!", "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":{ "Engagelab": "push to you" } }' > POST /v4/push HTTP/1.1 > Authorization: Basic Yzk2ZjQyZTBkMmU2NjJlNDVkMDM1YWIxOmRmNGQ1OWU4NGVhYzJmOWQ1M2IzNmYxMg==
          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "alert" :"Hello, Push!",
            "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":{
             "Engagelab": "push to you"
    }
}'
> 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 一起二者必須有其一，二者不可以並存。
    		•
    message JSON Object 可選
  • 消息内容体，是被推播到客户端的内容。
  • 与 notification 一起二者必须有其一，二者不可以并存。
    		•
    options JSON Object 可選 推播參數
    request_id String 可選 客戶自定義的可選字段，客戶用來標識是哪條請求，響應時返回。
    custom_args JSON Object 可選 客戶自定義的可選字段，回調時返回給客戶。最大不超过128个字符。

    from

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

    請求示例

    { "from":"push" }
              {
    "from":"push"
}
    此代碼塊在浮窗中顯示

    to

    推播設備對象，表示一條推播可以被推播到哪些設備列表。確認推播設備對象，App Push 提供了多種方式，比如：別名、標簽、註冊ID、分群、廣播等。

    推播目標

    廣播外的設備選擇方式，有如下幾種：

    關鍵字 類型 含義 說明 備註
    all String 发广播 給全部設備進行推播 推播目標為365天內活躍過的設備。
    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編碼）
    		•
    registration_id JSON Array 註冊ID 數組。多個註冊ID之間是 OR 關系，即取並集。 設備標識。一次推播最多 1000 個。
    live_activity_id string 即時活動標識 字串，對應 iOS SDK liveActivityId 的值 更新即時活動的時間必填

    數組裏多個值之間隱含的關系是是 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",
}
    此代碼塊在浮窗中顯示
    • 推播給多個標簽（只要在任何一個標簽範圍內都滿足）：在深圳、廣州、或者北京
    { "to":{ "tag":[ "深圳", "廣州", "北京" ] } }
              {
    "to":{
        "tag":[
            "深圳",
            "廣州",
            "北京"
        ]
    }
}
    此代碼塊在浮窗中顯示
    • 推播給多個標簽（需要同時在多個標簽範圍內）：在深圳並且是「女」
    { "to":{ "tag_and":[ "深圳", "女" ] } }
              {
    "to":{
        "tag_and":[
            "深圳",
            "女"
        ]
    }
}
    此代碼塊在浮窗中顯示
    • 推播給多個別名：
    { "to":{ "alias":[ "4314", "892", "4531" ] } }
              {
    "to":{
        "alias":[
            "4314",
            "892",
            "4531"
        ]
    }
}
    此代碼塊在浮窗中顯示
    • 推播給多個註冊ID：
    { "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } } 
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}
    此代碼塊在浮窗中顯示
    • 可同時推播指定多類推播目標：在深圳或者廣州，並且是 「女」 「會員」
    { "to":{ "tag":[ "深圳", "廣州" ], "tag_and":[ "女", "會員" ] } }
              {
    "to":{
        "tag":[
            "深圳",
            "廣州"
        ],
        "tag_and":[
            "女",
            "會員"
        ]
    }
}
    此代碼塊在浮窗中顯示

    推播即時活動

    { "to": { "live_activity_id": "LiveActivity-1" } }
              {
    "to": {
        "live_activity_id": "LiveActivity-1"
    }
}
    此代碼塊在浮窗中顯示

    body

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

    關鍵字 類型 選項 含義
    platform String 或 JSON Array 必填 推送平台
    notification JSON Object 可選 通知內容體，被推送到客戶端的內容。voip、message、notification、live_activity中的任一消息不可與其他消息同時存在
    message JSON Object 可選 消息內容體，被推送到客戶端的內容。voip、message、notification、live_activity中的任一消息不可與其他消息同時存在
    live_activity JSON Object 可選 實時活動消息內容體，被推送到客戶端的內容。voip、message、notification、live_activity中的任一消息不可與其他消息同時存在
    voip JSON Object 可選 voip消息內容體，被推送到客戶端的內容。voip、message、notification、live_activity中的任一消息不可與其他消息同時存在
    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對象 必填 通知內容
  • 如果指定，將覆蓋上級統一指定的通知內容。
  • 內容可以為空字符串，表示不顯示在通知欄中。
  • 各推播通道對此字段的限制詳見推播限制。
    		•
    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 可選 大文本通知欄樣式
  • 當style = 1時可用，內容將以大文本的形式顯示在通知欄中。
  • 支持API 16及以上的ROM。
    		•
    inbox JSONObject 可選 文本條目通知欄樣式
  • 當style = 2時可用，JSON的每個鍵對應的值將被視為文本條目逐條顯示。
  • 支持API 16及以上的ROM。
    		•
    big_pic_path String 可選 大圖片通知欄樣式
  • 當style = 3時可用，目前支持.JPEG（僅FCM通道）.BMP（僅FCM通道）.jpg和.png格式的圖片。
  • 支持網絡圖片URL，本地圖片的路徑（指定SD卡上的相對路徑）。
  • 支持API 16及以上的ROM。
  • 圖片大小上限是1MB。
    		•
    extras JSON對象 可選 額外字段 在JSON格式中自定義的Key/Value信息，供業務使用。
    intent JSON對象 可選 指定跳轉頁面（推薦） 使用intent字段中的URL指定單擊通知欄後要跳轉的目標頁面。建議填寫intent字段，否則單擊通知可能無法執行跳轉操作。此字段支持以下三種類型：
  • 跳轉到目標頁面：“intent：#Intent；action=action路徑；component=包名/Activity全名；end”
  • 應用程序首頁：“intent：#Intent；action=android.intent.action.MAIN；end”（固定為此地址）
  • 跳轉到深度鏈接地址：“scheme://test？key1=val1&key2=val2”
    		•
    large_icon String 可選 通知大圖標
  • 圖標大小不超過300KB。
  • 支持網絡圖片URL，本地圖片的路徑（指定SD卡上的相對路徑）。
    		•
    small_icon String 可選 通知小圖標
  • 通知小圖標，圖標路徑可以是以http或https開頭的網絡圖片，大小不能超過300KB。
  • 如果未填充厂商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一起使用；兩者必須共存，缺少任何一個都不允許。
    		•
    display_foreground String 可選 應用程序在前台時，是否應該顯示通知
  • 如果值為“1”，則應用程序在前台時通知將在通知欄中彈出。
  • 如果值為“0”，則應用程序在前台時不會彈出通知欄消息。
  • 備註：默認情況下，應用程序在前台時會彈出通知欄消息，MTPush Android SDK v4.3.1版本開始支持。
    		•
    { "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.engagelab.com/largeIcon.jpg", "small_icon": "http://www.small.com/small_icon.jpg", "intent": { "url": "intent:#Intent;component=push.engagelab.com/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.engagelab.com/largeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.engagelab.com/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 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 長度限製為 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"
    }
  }
}
    此代碼塊在浮窗中顯示

    live_activity

    注意：實時活動消息要求使用 iOS P8 證書，對應EngageLab WebPortal 集成設置中 iOS 鑒權方式需要選擇「Token Authentication配置」方式。

    實時活動消息內容體，有如下字段信息：

    關鍵字 類型 選項 說明
    ios JSON 物件 必填 詳細字段參考下表iOS JSON Object 部分。

    iOS JSON Object

    关鍵字 類型 選項 說明
    event string 必填 創建：“start”，更新：“update”，結束："end"；必填
    attributes-type string 可選 實時活動類型，開發者自定義值，當event=start時該參數必填
    content-state JSON 物件 必填 實時活動動態內容，需與客戶端 SDK 值匹配（對應 Apple 官方的content-state 字段）。
    alert JSON 物件 可選 參考下表iOS alert JSON Object 說明。
    dismissal-date int 可選 實時活動結束展示時間。
    attributes JSON 物件 可選 實時活動靜態內容，需與客戶端 SDK 值匹配（對應 Apple 官方的attributes字段）。
    stale-date int 可選 實時活動顯示過期時間，如果該時間小於當前時間，實時活動將不會更新
    relevance-score int 可選 實時活動在靈動島上展示的優先級，取值[1,100],該值和實時活動的重要性呈正相關，不填默認為最高
    apns-priority int 可選 為5或10 ，不填默認為10。因為時候活動通知每小時是有頻控限制的，apns-priority=5的通知將不消耗蘋果廠商頻控配額，當超出頻控上限，推播通知將被限制

    iOS alert JSON Object

    關鍵字 類型 選項 說明
    title string 可選 顯示到Apple Watch的消息標題。
    body string 可選 顯示到Apple Watch的消息內容。
    sound string 可選 提示音。
    • iOS 實時活動消息（Live Activity） Engagelab Push 要轉發給蘋果伺服器。蘋果要求實時活動消息 （ActivityKit）遠程推送的動態更新數據大小不超過 4096 字節。
    • Engagelab Push 因為需要重新組包，並且考慮一點安全冗余，要求 "live_activity" 參數體內 "iOS":{ } 及大括號內的總體長度不超過：3584 個字節。JPush 使用 utf-8 編碼，所以一個漢字佔用 3 個字節長度。

    實時活動推送示例

    實時活動使用的attributes-type和live_activity_id均來自開發者sdk上報，在使用實時活動前必須上報設備的push-to-start token和update-token，詳細流程參考蘋果廠商實時活動說明

    Create a live activety message

    { "from": "push", "to": { "registration_id": [ "161a3797c816b134042" ] }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "start", "content-state": { "eventStr": "hello", "eventTime":1685952000 }, "attributes": { "name": "1", "number": 2, "tag": "mytag" }, "alert": { "title": "hello", "body": "welcome" }, "attributes-type": "my_la_type", "relevance-score": 100, "apns-priority": 100 } } }, "request_id": "12345678", "custom_args": "12345678" }
              {
    "from": "push",
   "to": {
        "registration_id": [
            "161a3797c816b134042"
        ]
    },
    "body": {
        "platform": "ios",
        "live_activity": {
            "ios": {
                "event": "start",
                "content-state": {
                    "eventStr": "hello",
                    "eventTime":1685952000
                },
                "attributes": {
                    "name": "1",
                    "number": 2,
                    "tag": "mytag"
                },
                "alert": {
                    "title": "hello",
                    "body": "welcome"
                },
                "attributes-type": "my_la_type",
                "relevance-score": 100,
                "apns-priority": 100
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "12345678"
}
    此代碼塊在浮窗中顯示

    Update a live activety message

    { "from": "push", "to": { "live_activity_id": "my_la_id" }, "body": { "platform": "ios", "live_activity": { "ios": { "event": "update", "content-state": { "eventStr": "test_live", "eventTime": 198 }, "alert": { "title": "123411", "body": "123411" } } } }, "request_id": "12345678", "custom_args": "12345678" }
              {
   "from": "push",
   "to": {
         "live_activity_id": "my_la_id"
    },
    "body": {
        "platform": "ios",
        "live_activity": {
            "ios": {
                "event": "update",
                "content-state": {
                    "eventStr": "test_live",
                    "eventTime": 198
                },

                "alert": {
                    "title": "123411",
                    "body": "123411"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "12345678"
}
    此代碼塊在浮窗中顯示

    voip

    iOS VOIP 功能。 该類型不支援和 iOS 的其他訊息類型並存，請求參數結構參考：

    { "from": "push", "to": { "registration_id": [ "1a0018970a91da03de5" ] }, "request_id": "12345", "custom_args": "12345", "body": { "platform": "ios", "voip": { "key": "value // 任意自定義 key/value 對，會透傳給 APP" } } }
              { 
    "from": "push", 
    "to": { 
        "registration_id": [ "1a0018970a91da03de5" ] 
    }, 
    "request_id": "12345", 
    "custom_args": "12345", 
    "body": { 
        "platform": "ios", 
        "voip": { 
            "key": "value // 任意自定義 key/value 對，會透傳給 APP" 
        } 
    } 
}
    此代碼塊在浮窗中顯示

    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。
    multi_language json object 可選 多語言推播設置 推播內容多語言適配設置，詳情查看multi_language 說明。
    third_party_channel JSON Object 可選 Android 廠商通道配置信息 僅針對配置了廠商通道的用戶有效參數，詳情查看third_party_channel 說明。
    classification Int 可選 推播消息分類設置 EngageLab不對指定的消息類型進行判斷或校準。不填默認為 0。0：代表運營消息。1：代表系統消息。
    voice_value String 可選 語音文件值 多個參數用英文逗號隔開，帶了#的表示需要解析的，沒帶的就直接默認匹配mp3文件。注意數值如果有小數點的，上傳的文件名必須為point.mp3。目前支持的語言包括 "en"（英語）、"zh-Hans"（簡體中文）和 "zh-Hant"（繁體中文）。如果推播內容的指定語言沒有匹配上對應的語言規則，則該推播內容不會轉為語音播報。
    enhanc_message Bool 可選 啟用應用內消息展示 true-開啟增強；false-關閉增強。如果通知權限被關閉，啟用此功能後，當使用者在前台運行 APP 時，會通過應用內消息的方式展示原本通知欄中的消息內容。此功能的預設值為 false，只有在明確開啟時才會生效。
    plan_id String 可選 推送計劃標識 需先創建計劃標識值，可在控制台創建或者通過API創建。

    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、honor 這 7 個 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或者手機廠商），則會忽略指定FCM和廠商通道的策略，走集成成功的系統通道（FCM或者廠商通道）。
    		•
    channel_id String 可選 通知欄消息分類
  • 為了適配小米、華為、OPPO手機廠商通知欄消息分類，由開發者自行向手機廠商申請，具體申請規則參考：廠商消息分類使用指南。
  • 注意，華為數據處理位置為中國區的應用不支持該字段，詳情參見華為自定義通知渠道。
  • Android下也有channel_id字段，若本字段有填充，則優先使用；若無填充則以android.channel_id的定義為準。
  • 特別注意：由於OPPO廠商2024年11月20日實施OPPO消息分類新規，建議您同時填寫此字段和下面的category、notify_level字段。
    		•
    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 可選 華為廠商自定義消息場景標識 為了適配華為、vivo、OPPO手機廠商消息，用於標識「雲端通知」消息類型，確定消息提醒方式，對特定類型消息加快發送。
  • 對應值及其說明參考：華為 category 值說明、vivo 分類標準。
  • OPPO category 值說明
  • 說明1：華為需完成自分類權益申請。
  • 說明2：華為從2023年9月15日開始基於《華為消息分類標準》對其雲端通知和本地通知進行共同管控推播，開發者通過極光服務發起推播時，請注意此字段傳值需符合華為官方「華為雲端通知 category」取值要求。
  • 說明3：vivo具體規則參考vivo 官方說明。
  • 說明4：OPPO於2024年11月20日實施消息分類新規，具體規則參考OPPO 官方說明。
    		•
    notify_level Int 可選 OPPO通知欄消息提醒等級
  • 官方取值定義：1 代表通知欄，2 代表通知欄+鎖屏，16 代表通知欄+鎖屏+橫幅+震動+鈴聲。
  • notify_level 字段僅適用於「服務與通訊類」消息。
  • 使用 notify_level 參數時，必須傳遞 category 參數。
    		•
    small_icon_uri String 可選 廠商消息小圖標樣式
  • 目前支持小米 / 華為廠商。
  • 優先使用廠商字段， 廠商字段沒有填充，則使用 android 內的 small_icon 字段。
  • 小米支持 小米廠商的大圖標 id，華為、支持 Engagelab 的 media_id 及廠商本地路徑。(小米官方後續不再支持自定義小圖標，建議開發者不要繼續使用小米 small Icon 相關特性功能)。
    		•
    small_icon_color String 可選 小米廠商小圖標樣式顏色 為了適配小米廠商的消息小圖標樣式顏色，不填充默認是灰色 (小米官方後續不在支持自定義小圖標，建議開發者不要繼續使用小米 small icon 相關特性功能)。
    big_text String 可選 廠商消息大文本樣式
  • 為了適配廠商的消息大文本樣式, 目前支持華為/榮耀/小米/OPPO，其中小米OPPO最多支持128個字符。
  • 優先使用此廠商字段， 廠商字段沒有填充，則使用 android 裏面定義 big_text 字段。
  • android裏面字段style=1時使用。
    		•
    only_use_vendor_style Boolean 可選 是否使用自身通道設置樣式 是否只使用自身通道設置的樣式，不使用 android 裏面設置的樣式，默認為 false，
  • true：只使用自身通道設置的樣式。
  • false：可使用 android 裏面設置的樣式。
    		•

    為統一多廠商通道策略並簡化配置邏輯，現對 distribution_new 欄位的配置方式做如下調整，您的舊廠商級配置仍可繼續生效，但建議逐步遷移至全局配置以規避未來兼容風險。（2025.04.03起執行下列新規則）：

    • 配置優先級（新規則）
      • 第一優先級：全局配置 third_party_channel.distribution_new（推薦新方式）
        範例："distribution_new": "pns_mtpush"
      • 第二優先級：廠商級配置 third_party_channel.{廠商key}.distribution_new（兼容舊方式）
        僅當全局配置未設置時生效
      • 無配置時：使用 默認策略：pns_mtpush

    兼容性說明

    • 兼容性保障：舊廠商級配置在未設置全局欄位時仍會生效，不影響現有業務。
    • 衝突解決：若同時配置全局和廠商級欄位，僅讀取全局值並忽略廠商級配置。
    • 遠期規劃：廠商級 distribution_new 可能在後續版本廢棄，請盡量提前適配。
    請求範例
    { "third_party_channel": { "distribution_new": "pns_mtpush", "xiaomi": { "channel_id": "*******", "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png", "small_icon_color": "#ABCDEF" }, "huawei": { "importance": "NORMAL", "small_icon_uri": "https://xx.com/xx.jpg", "only_use_vendor_style": true }, "oppo": { "channel_id": "*******", "large_icon": "3653918_5f92b5739ae676f5745bcbf4" }, "vivo": { "pushMode": 0 } } }
              {
    "third_party_channel": {
        "distribution_new": "pns_mtpush",
        "xiaomi": {
            "channel_id": "*******",
            "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
            "small_icon_color": "#ABCDEF"
        },
        "huawei": {
            "importance": "NORMAL",
            "small_icon_uri": "https://xx.com/xx.jpg",
            "only_use_vendor_style": true
        },
        "oppo": {
            "channel_id": "*******",
            "large_icon": "3653918_5f92b5739ae676f5745bcbf4"
        },
        "vivo": {
            "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":{ "args1": "args1" } }
              {
  "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/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}
    此代碼塊在浮窗中顯示

    失敗返回

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

    字段 類型 選項 描述
    code int 必選 錯誤碼，詳見錯誤碼 說明
    message String 必選 錯誤詳情
    { "error":{ "code": 3002, "message": "Push.template field must be set correctly when type is template" } } 
              {
    "error":{
    "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
    21050 live_activity event參數錯誤 event參數必須為“start”，“update”、"end" 400
    21051 live_activity audience參數錯誤 實時活動創建時，推送目標只能是廣播或者reg推送 400
    21052 live_activity attributes-type參數錯誤 event=start時，attributes-type不允許為空 400
    21053 live_activity content-state參數錯誤 content-state不允許為空 400
    21054 live_activity 參數錯誤，不允許同時通知和自定義訊息 voip、message、notification、live_activity不能並存 400
    21055 live_activity ios非p8證書 實時活動僅支援p8證書 400
    21056 live_activity 僅支援ios平台 platform參數必須是ios 400
    21057 voip 訊息不允許和其他訊息類型並存 voip、message、notification、live_activity不能並存 400
    21058 voip 僅支援ios平台 platform參數必須是ios 400
    23006 參數錯誤 定速推送 big_push_duration 超過最大值 1440 400
    23008 接口限速 單應用推送接口 qps 達到上限(500 qps) 400
    23009 推送權限錯誤 當前推送ip地址不在應用ip白名單內 400
    27000 系統內存錯誤 請重试
    27001 参数错误 校验信息为空 401
    27008 参数错误 third_party_channel 里面的 distribution 不为空，但是 notification 的 alert 内容为空 401
    27009 参数错误 third_party_channel 中 distribution 格式无效或为空 401
    21038 推送权限错误 VIP已过期或未开通 401
    21306 参数错误 通知消息和自定义消息不能同时推送 401
    21059 参数错误 这个消息类型不支持 big_push_duration。 401

    推播限製

    廠商通道 標題長度 內容長度 敏感詞 其他說明
    Engagelab 通道 ＜ 50 個字符 不限製，但限製消息體總大小 - MTPush 中 Notification 長度限製為 4000 個字節。
    華為通道 ＜ 40 個字符 ＜ 1024 字符 禁止攜帶政府，領導人名稱、臺獨等相關內容 默認【營銷通知】的權限為靜默通知，靜默推播沒有聲音、震動等提示。
    榮耀通道 不限製，但消息體總大小<4096字節 不限製，但消息體總大小 ＜ 4096 字節 禁止攜帶政府，領導人名稱、臺獨等相關內容 -
    魅族通道 ＜ 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
    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
    在文档中心打开
    icon
    聯繫銷售