Logo Site EngageLab Mark Colored Transparent文件
WebPush
文檔首頁
使用者指南開發者指南最佳實踐更新日誌
搜尋
登錄
開發者指南/REST API/統計 API
開發者指南REST API統計 API...

統計 API

最新更新：超過 3 年前

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

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

概述

Stats API v4 提供各類統計數據查詢功能。

調用驗證

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

訊息統計

  • 查詢 message_id 生命週期中各個狀態的統計數據。
  • 每條推播訊息的統計數據最多保留一個月。

調用地址

GET v4/status/detail
              
              GET v4/status/detail
此代碼塊在浮窗中顯示

請求示例

curl -v https://webpushapi-sgp.engagelab.com/v4/status/detail?message_ids=1613113584,1229760629 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status/detail?message_ids=1613113584,1229760629 HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
              
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/detail?message_ids=1613113584,1229760629 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status/detail?message_ids=1613113584,1229760629 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
此代碼塊在浮窗中顯示

請求參數

關鍵字 類型 選項 含義
message_ids String 必選
  • 訊息 ID，如果有多個 message_id 時，中間通過","分割。
  • 最多支援 100 個 message_id。
    		•

    返回示例

    < HTTP/1.1 200 OK < Content-Type: application/json { "1083008": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0, "sub": { "notification": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0, "sub_web": { "engageLab_web": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "chrome": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0 }, "safari": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "firefox": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "edge": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "other": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 } } }, "message": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 } }, "plan_id": "engageLab_msg", "pushContent": { "message": { "title": "msg", "content": "Hi,MTPush" } } } }
                  
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1083008": {
        "targets": 1,
        "sent": 1,
        "delivered": 1,
        "impressions": 1,
        "clicks": 0,
        "sub": {
            "notification": {
                "targets": 1,
                "sent": 1,
                "delivered": 1,
                "impressions": 1,
                "clicks": 0,
                "sub_web": {
                    "engageLab_web": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "chrome": {
                        "targets": 1,
                        "sent": 1,
                        "delivered": 1,
                        "impressions": 1,
                        "clicks": 0
                    },
                    "safari": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "firefox": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "edge": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "other": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    }
                }
            },
            "message": {
                "targets": 0,
                "sent": 0,
                "delivered": 0,
                "impressions": 0,
                "clicks": 0
            }
        },
        "plan_id": "engageLab_msg",
        "pushContent": {
            "message": {
                "title": "msg",
                "content": "Hi,MTPush"
            }
        }
    }
}
    此代碼塊在浮窗中顯示

    返回參數

    成功響應為一個 JSON Object，其中 key 為每個 message_id，每個訊息需要包含各個階段的生命週期統計數據：

    關鍵字 類型 選項 含義
    targets Int64 必選 有效目標。將推播任務所選定的目標人群，經過有效性篩選後的目標設備數量。
    sent Int64 必選 發送數量。有效目標設備中，Engagelab 伺服器實際成功創建了發送任務的設備數量。
    delivered Int64 必選 送達數量。通知訊息發送後，實際送達至 Web 端的數量，5 天之後的送達數量不被計算在內。
    impressions Int64 必選 展示數量。通知訊息送達後，實際在設備終端成功展示的數量，5 天之後的展示數量不被計算在內。
    clicks Int64 必選 點擊數量。通知訊息成功展示後，實際被用戶點擊的數量，5 天之後的點擊數量不被計算在內。
    sub Object 必選 統計數據的細分指標，詳情見 下表。
  • notification：通知欄訊息類型的數據彙總統計。
  • message：自訂訊息的數據彙總統計。
    		•
    plan_id String 必選 推播計劃 ID，標識該訊息所屬的推播計劃類型
    pushContent Object 必選 推播內容詳情，包含不同平台的推播內容資訊：
    - android：安卓平台推播內容（包含 title、content 等欄位）
    - ios：iOS 平台推播內容（包含 title、content、subtitle 等欄位）
    - message：自訂訊息內容（包含 title、content 等欄位）
    細分指標
    關鍵字 類型 選項 含義
    sub_web Object 可選 Web 各個推播通道的數據彙總統計
    engageLab_web Object 可選 Engagelab 通道的數據彙總統計
    chrome Object 可選 Chrome 通道的數據彙總統計
    safari Object 可選 Safari 通道的數據彙總統計
    firefox Object 可選 Firefox 通道的數據彙總統計
    edge Object 可選 Edge 通道的數據彙總統計
    other Object 可選 其他通道的數據彙總統計

    用戶統計

    • 提供近 2 個月內某時間段的用戶相關統計數據：包括新增用戶、在線用戶、活躍用戶。
    • 時間單位支援：HOUR（小時）、DAY（天）、MONTH（月）。

    調用地址

    v4/status/users
                  
              v4/status/users
    此代碼塊在浮窗中顯示

    請求示例

    curl -v https://webpushapi-sgp.engagelab.com/v4/status/users?time_unit=DAY&start=2014-06-10&duration=3 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status/users?time_unit=&start=&duration= HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
                  
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/users?time_unit=DAY&start=2014-06-10&duration=3 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status/users?time_unit=&start=&duration= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
    此代碼塊在浮窗中顯示

    請求參數

    關鍵字 類型 選項 含義
    time_unit String 必選 時間單位。有三個取值：
  • HOUR：小時
  • DAY：天
  • MONTH：月
    		•
    start String 必選 起始時間。
  • 如果單位是小時，則起始時間是小時（包含天，不足兩位要補 0），格式例：2022-06-11 09
  • 如果單位是天，則起始時間是日期（天），格式例：2006-01-02T15
  • 如果單位是月，則起始時間是日期（月），格式例：2022-06
    		•
    duration String 必選 持續時長。
  • 如果單位是天，則是持續的天數。以此類推。
  • 只支援查詢 60 天以內的用戶資訊，對於 time_unit 為 HOUR 的，只支援輸出當天的統計結果。
    		•

    返回示例

    < HTTP/1.1 200 OK < Content-Type: application/json { "time_unit": "DAY", "start": "2014-06-10", "duration": 3, "items": [{ "time": "2014-06-12", "web": { "new": 1, "active": 1, "online": 2 } }] }
                  
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "time_unit": "DAY",
    "start": "2014-06-10",
    "duration": 3,
    "items": [{
        "time": "2014-06-12",
        "web": {
      "new": 1,
            "active": 1,
            "online": 2
    }
    }]
}
    此代碼塊在浮窗中顯示

    返回參數

    成功響應為一個 JSON Object：

    關鍵字 類型 選項 含義
    time_unit String 必選 時間單位。有三個取值：
  • HOUR：小時
  • DAY：天
  • MONTH：月
    		•
    start String 必選 起始時間。
  • 如果單位是小時，則起始時間是小時（包含天，不足兩位要補 0），格式例：2022-06-11 09
  • 如果單位是天，則起始時間是日期（天），格式例：2022-06-11
  • 如果單位是月，則起始時間是日期（月），格式例：2022-06
    		•
    duration String 必選 持續時長。
  • 如果單位是天，則是持續的天數。以此類推。
  • 只支援查詢 60 天以內的用戶資訊，對於 time_unit 為 HOUR 的，只支援輸出當天的統計結果。
    		•
    items JSON Array 必選 按持續時間查詢範圍內的統計結果
    • items 格式說明：
      • web：Web 平台的數據彙總統計。
    關鍵字 類型 選項 含義
    new Int64 可選 新增用戶
    online Int64 可選 在線用戶
    active Int64 可選 活躍用戶

    查詢訊息生命週期狀態

    • 查詢 message_id 下對應設備的訊息生命週期狀態。
    • 每條推播訊息的統計數據最多保留一個月。

    調用地址

    GET v4/status/message

    請求示例

    curl -v https://webpushapi-sgp.engagelab.com/v4/status/message?message_id=1613113584&registration_ids=1507bfd3a7c568d4761,1618cfd3a7c568d4761,17259fd3a7c568d4371 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status/message?message_id=&registration_ids= HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
                  
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/message?message_id=1613113584&registration_ids=1507bfd3a7c568d4761,1618cfd3a7c568d4761,17259fd3a7c568d4371 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status/message?message_id=&registration_ids= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
    此代碼塊在浮窗中顯示

    請求參數

    關鍵字 類型 選項 含義
    message_id String 必選 訊息 ID
    registration_ids String 必選
  • 設備 ID，如果有多個 registration_id 時，中間通過","分割。
  • 最多支援 1000 個 registration_id。
    		•

    返回示例

    < HTTP/1.1 200 OK < Content-Type: application/json { "1507bfd3a7c568d4761": { "itime": 1762331775, "channel": "FCM", "status": "delivered" }, "17259fd3a7c568d4371": { "error_code": 21003, "error_message": "The `registration_id` does not belong to the appkey" }, "17259fd3a7c568d4787":{ "itime": 1762331775, "status": "sent_failed", "error_code": 401, "error_message": "token is invalid", "channel": "FCM" }, "17259fd3a7c568d4372": { "error_code": 21061, "error_message": "no effect status" } }
                  
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1507bfd3a7c568d4761": {
        "itime": 1762331775,
        "channel": "FCM",
        "status": "delivered"
    },
    "17259fd3a7c568d4371": {
        "error_code": 21003,
        "error_message": "The `registration_id` does not belong to the appkey"
    },
    "17259fd3a7c568d4787":{
        "itime": 1762331775,
        "status": "sent_failed",
        "error_code": 401,
        "error_message": "token is invalid",
        "channel": "FCM"		
    },
    "17259fd3a7c568d4372": {
        "error_code": 21061,
        "error_message": "no effect status"
    }
}
    此代碼塊在浮窗中顯示

    失敗返回

    { "error": { "code": 21003, "message": "Parameter value is invalid" } }
                  
              {
  "error": {
    "code": 21003,
    "message": "Parameter value is invalid"
  }
}
    此代碼塊在浮窗中顯示

    批量查詢訊息生命週期狀態

    • 批量查詢 message_id 下單個 regid 的訊息生命週期狀態。如果不是單個 registration_id，則返回到報錯 message_id 陣列。
    • 每條推播訊息的統計數據最多保留一個月。

    調用地址

    GET v4/status/batch/message

    請求示例

    curl -v https://webpushapi-sgp.engagelab.com/v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
                  
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
    此代碼塊在浮窗中顯示

    請求參數

    關鍵字 類型 選項 含義
    message_ids String 必選
  • 訊息 ID，如果有多個 message_id 時，中間通過","分割。
  • 最多支援 100 個 message_id。
    		•

    返回參數說明

    成功響應為一個 JSON Object，包含這條訊息下各個 message_id 單個 registration_id 的訊息當前狀態，如果有異常資訊，則將資訊包含在 error_message 中。

    關鍵字 類型 選項 含義
    message_id String 必選 訊息 message_id
    registration_id String 可選 單個 registration_id
    status String 可選 取值範圍：
  • plan：計劃目標
  • target_valid：有效目標
  • target_invalid：無效目標
  • sent：發送
  • sent_failed：發送失敗
  • delivered：送達
  • delivered_failed：送達失敗
  • Impression：展示
  • click：點擊
    		•
    error_message String 可選 錯誤資訊，只有部分狀態有該資訊。
    error_code Int64 可選 錯誤狀態碼，只有部分狀態有該資訊。
    itime Int64 可選 狀態更新時間，時間精確到秒。
    channel String 可選 推播訊息所走的通道資訊。

    返回示例

    成功返回

    < HTTP/1.1 200 OK < Content-Type: application/json [ { "message_id": "261585110", "error_message": "Multiple `registration_id` found under the same `message_id`.", "error_code": 21003 }, { "message_id": "261585123", "registration_id": "170976fa8ab73279b2f", "status": "click", "itime": 1766047747, "channel": "EngageLab" }, { "message_id": "1613113585", "error_message": "The `message_id` is invalid or does not exist.", "error_code": 21003 } ]
                  
              < HTTP/1.1 200 OK
< Content-Type: application/json
[
    {
        "message_id": "261585110",
        "error_message": "Multiple `registration_id` found under the same `message_id`.",
        "error_code": 21003
    },    
    {
        "message_id": "261585123",
        "registration_id": "170976fa8ab73279b2f",
        "status": "click",
        "itime": 1766047747,
        "channel": "EngageLab"
    },
    {
        "message_id": "1613113585",
        "error_message": "The `message_id` is invalid or does not exist.",
        "error_code": 21003
    }
]
    此代碼塊在浮窗中顯示

    失敗返回

    { "error": { "code": 21003, "message": "Parameter value is invalid" } }
                  
              {
  "error": {
    "code": 21003,
    "message": "Parameter value is invalid"
  }
}
    此代碼塊在浮窗中顯示

    調用返回

    HTTP 狀態碼

    參考文檔：HTTP-Status-Code

    錯誤碼

    Code 描述 詳細解釋 HTTP Status Code
    0 success 成功 200
    21001 The method is not supported or url err 請求方法(GET/POST)錯誤或者 url 錯誤(接口不存在) 404
    21003 Parameter value is invalid 參數值不合法 400
    23001 Basic authentication failed HTTP Basic authorization 失敗 401
    23002 Missing parameter! 缺少了必須的參數 400
    23004 time_unit value does not match with start! time_unit 與 start 參數值不匹配 400
    23007 Only support quering the message_id within 30 days! 只支援查詢 30 天以內的訊息資訊 400
    23100 server error 系統內部錯誤 500
    27000 Server response time out, please try again later 系統內部錯誤 500
    27201 msgid 不存在或不屬於此 app msgid 不存在或不屬於此 app 400
    Icon Solid Transparent White Qiyu
    聯繫銷售