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

統計 API

最新更新：2023-02-20

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

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

概述

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

調用驗證

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

訊息統計

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

調用地址

GET v4/messages/details

請求示例

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

< GET /v4/messages/details?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 { "1613113584": { "targets": 11, "sent": 11, "delivered": 10, "impressions": 8, "clicks": 2, "sub": { "notification": { "target": 1600, "sent": 1440, "delivered": 1280, "impressions": 1120, "click": 0, "sub_android": { "engageLab_android": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "huawei": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "xiaomi": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "oppo": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "vivo": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "meizu": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "fcm": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "honor": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 } }, "sub_ios": { "engageLab_ios": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 }, "apns": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0 } } }, "message": { "targets": 100, "sent": 90, "delivered": 80, "impressions": 70, "clicks": 0, "sub_android": {}, "sub_ios": {} } } }, "1229760629": { "targets": 11, "sent": 11, "delivered": 10, "impressions": 8, "clicks": 2, "sub": { "notification": {}, "message": {} } } }
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1613113584": {
        "targets": 11,
        "sent": 11,
        "delivered": 10,
        "impressions": 8,
        "clicks": 2,
        "sub": {
            "notification": {
                "target": 1600,
                "sent": 1440,
                "delivered": 1280,
                "impressions": 1120,
                "click": 0,
                "sub_android": {
                    "engageLab_android": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "huawei": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "xiaomi": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "oppo": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "vivo": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "meizu": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "fcm": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "honor": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    }
                },
                "sub_ios": {
                    "engageLab_ios": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    },
                    "apns": {
                        "targets": 100,
                        "sent": 90,
                        "delivered": 80,
                        "impressions": 70,
                        "clicks": 0
                    }
                }
            },
            "message": {
                "targets": 100,
                "sent": 90,
                "delivered": 80,
                "impressions": 70,
                "clicks": 0,
            "sub_android": {},
                "sub_ios": {}
            }
        }
    },
    "1229760629": {
        "targets": 11,
        "sent": 11,
        "delivered": 10,
        "impressions": 8,
        "clicks": 2,
        "sub": {
            "notification": {},
            "message": {}
        }
    }
}
    此代碼塊在浮窗中顯示

    返回參數

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

    關鍵字 類型 選項 含義
    targets Int64 必選 有效目標。將推送任務所選定的目標人群，經過有效性篩選後的目標設備數量。
    sent Int64 必選 發送數量。有效目標設備中，Engagelab 伺服器實際成功創建了發送任務的設備數量。
    delivered Int64 必選 送達數量。通知消息發送後，實際送達至設備終端的數量，5 天之後的送達數量不被計算在內，華為、魅族和 iOS 需要配置回調送達數據才更加精準。
    impressions Int64 必選 展示數量。通知消息送達後，實際在設備終端成功展示的數量，5 天之後的展示數量不被計算在內。
    clicks Int64 必選 點擊數量。通知消息成功展示後，實際被用戶點擊的數量，5 天之後的點擊數量不被計算在內。
    sub Object 必選 統計數據的細分指標，詳情見下表。
  • notification：通知欄消息類型的數據彙總統計。
  • message：自定義消息的數據彙總統計。
  • live_activity:即時活動消息的數據彙總統計。
  • voip:voip消息的數據彙總統計
    		•
    細分指標
    關鍵字 類型 選項 含義
    sub_android Object 可選 安卓各個推播通道的數據匯總統計
    engageLab_android Object 可選 安卓 Engagelab 通道的數據匯總統計
    huawei Object 可選 華為通道的數據匯總統計
    xiaomi Object 可選 小米通道的數據匯總統計
    oppo Object 可選 OPPO 通道的數據匯總統計
    vivo Object 可選 vivo 通道的數據匯總統計
    meizu Object 可選 魅族通道的數據匯總統計
    fcm Object 可選 FCM 通道的數據匯總統計
    sub_ios Object 可選 蘋果各個推播通道的數據匯總統計
    engageLab_ios Object 可選 iOS Engagelab 通道的數據匯總統計
    apns Object 可選 iOS APNs 通道的數據匯總統計

    推送計劃統計

    • 本接口用於 獲取推送計劃的詳細統計指標，支援批量查詢多個計劃在指定時間範圍內的全生命周期數據，包含多維度細分指標（平台/廠商/消息類型）。

    調用地址

    GET v4/status/plan/detail

    請求示例

    GET /v4/status/plan/detail?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-07
              GET /v4/status/plan/detail?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-07
    此代碼塊在浮窗中顯示

    請求參數

    參數名稱 類型 是否必填 說明
    plan_ids string 是 推送計劃ID列表，多個ID用英文逗號分隔，最多支援100個
    start_date string 是 統計開始日期（格式：yyyy-MM-dd），需滿足：
  • 1. 結束日期 >= 開始日期
  • 2. 日期間隔 ≤ 31天
    		•
    end_date string 是 統計結束日期（格式：yyyy-MM-dd）

    返迴參數說明

    成功響應

    • 返迴對象為鍵值對結構，鍵名為請求的plan_id
    • 每個plan_id對應對象包含以下字段：
    參數名稱 類型 說明
    targets int64 有效目標設備數（經過去重、有效性過濾後的設備總量）
    sent int64 實際創建發送任務的設備數
    delivered int64 實際送達設備數（僅統計5天內的數據）
    impressions int64 消息展示數（僅統計5天內的數據）
    clicks int64 用戶點擊次數（僅統計5天內的數據）
    sub object 消息類型細分統計（結構見下方子表）

    • sub對象結構

      消息類型 說明 子結構
      notification 通知欄消息統計 包含sub_android(安卓廠商統計)/sub_ios(iOS統計)
      message 自定義消息統計 包含sub_android/sub_ios
      live_activity 實時活動消息統計 僅含sub_ios
      voip VOIP消息統計 僅含sub_ios

    • 平台廠商統計字段

      參數名稱 類型 說明
      targets int64 對應廠商的有效目標設備數
      sent int64 廠商渠道實際發送數
      delivered int64 廠商渠道實際送達數
      impressions int64 廠商渠道展示數
      clicks int64 廠商渠道點擊數

    響應示例

    成功響應

    { "push_20231101": { "targets": 1500, "sent": 1450, "delivered": 1400, "impressions": 1350, "clicks": 120, "sub": { "notification": { "sub_android": { "huawei": { "targets":200, "sent":190, "delivered":185, "impressions":180, "clicks":15 }, "xiaomi": { "targets":180, "sent":175, "delivered":170, "impressions":165, "clicks":10 } }, "sub_ios": { "apns": { "targets":300, "sent":295, "delivered":290, "impressions":285, "clicks":25 } } }, "live_activity": { "sub_ios": { "apns": { "targets":50, "sent":48, "delivered":45, "impressions":40, "clicks":5 } } } } } }
              {
  "push_20231101": {
    "targets": 1500,
    "sent": 1450,
    "delivered": 1400,
    "impressions": 1350,
    "clicks": 120,
    "sub": {
      "notification": {
        "sub_android": {
          "huawei": { "targets":200, "sent":190, "delivered":185, "impressions":180, "clicks":15 },
          "xiaomi": { "targets":180, "sent":175, "delivered":170, "impressions":165, "clicks":10 }
        },
        "sub_ios": {
          "apns": { "targets":300, "sent":295, "delivered":290, "impressions":285, "clicks":25 }
        }
      },
      "live_activity": {
        "sub_ios": {
          "apns": { "targets":50, "sent":48, "delivered":45, "impressions":40, "clicks":5 }
        }
      }
    }
  }
}
    此代碼塊在浮窗中顯示

    失敗響應

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

    用戶統計

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

    調用地址

    GET v4/status/users

    請求示例

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

< GET /v4/users?time_unit=DAY&start=2014-06-10&duration=3 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
    此代碼塊在浮窗中顯示

    請求參數

    關鍵字 類型 選項 含義
    time_unit String 必選 時間單位。有三個取值：
  • HOUR：小時
  • DAY：天
  • MONTH：月
    		•
    start String 必選 起始時間。
  • 如果單位是小時，則起始時間是小時（包含天，不足兩位要補 0），格式例：2022-06-11 09
  • 如果單位是天，則起始時間是日期（天），格式例：2022-06-11
  • 如果單位是月，則起始時間是日期（月），格式例：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", "android": { "new": 1, "active": 1, "online": 2 }, "ios": { "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",
        "android": {
      "new": 1,
            "active": 1,
            "online": 2
        },
    "ios": {
      "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 格式說明：
      • android：安卓平台的數據匯總統計。
      • ios：蘋果平台的數據匯總統計。
    關鍵字 類型 選項 含義
    new Int64 可選 新增用戶
    online Int64 可選 在線用戶
    active Int64 可選 活躍用戶

    查詢訊息生命周期狀態

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

    調用地址

    GET v4/status/message

    請求示例

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

< GET /v4/status?message_id=1613113584&registration_ids=1507bfd3a7c568d4761,1618cfd3a7c568d4761,17259fd3a7c568d4371 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": { "status": "plan" }, "1618cfd3a7c568d4761": { "error_message": "The `registration_id` does not belong to the appkey" }, "17259fd3a7c568d4371": { "error_message": "internal error" } }
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1507bfd3a7c568d4761": {
        "status": "plan"
    },
    "1618cfd3a7c568d4761": {
        "error_message": "The  `registration_id` does not belong to the appkey"
    },
    "17259fd3a7c568d4371": {
        "error_message": "internal error"
    }
}
    此代碼塊在浮窗中顯示

    返回參數

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

    關鍵字 類型 選項 含義
    status String 可選 取值範圍：
  • plan：計畫目標
  • target_valid：有效目標
  • target_invalid：無效目標
  • sent：傳送；
  • sent_failed：傳送失敗
  • delivered：送達
  • delivered_failed：送達失敗
  • Impression：展示
  • click：點選
    		•
    error_message String 可選 錯誤信息

    調用返回

    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
    聯繫銷售