繁體中文
English
繁體中文
简体中文
にほんご
ภาษาไทย
登入 註冊
icon AppPush icon WebPush icon WhatsApp icon Email icon SMS icon OTP
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 https://push.api.engagelab.cc/v4/messages/details

請求示例

curl -v https://push.api.engagelab.cc/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://push.api.engagelab.cc/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 必選 <li>訊息 ID，如果有多個 message_id 時，中間通過","分割。<li>最多支援 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 必選 統計數據的細分指標，詳情參考細分指標。<li>notification：通知欄訊息類型的數據匯總統計。<li>message：自訂訊息的數據匯總統計。
細分指標
關鍵字 類型 選項 含義
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 通道的數據匯總統計

用戶統計

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

調用地址

GET https://push.api.engagelab.cc/v4/status/users

請求示例

curl -v https://push.api.engagelab.cc/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://push.api.engagelab.cc/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 必選 時間單位。有三個取值：<li>HOUR：小時<li>DAY：天<li>MONTH：月
start String 必選 起始時間。<li>如果單位是小時，則起始時間是小時（包含天，不足兩位要補 0），格式例：2022-06-11 09<li>如果單位是天，則起始時間是日期（天），格式例：2022-06-11<li>如果單位是月，則起始時間是日期（月），格式例：2022-06
duration String 必選 持續時長。<li>如果單位是天，則是持續的天數。以此類推。<li>隻支援查詢 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 必選 時間單位。有三個取值：<li>HOUR：小時<li>DAY：天<li>MONTH：月
start String 必選 起始時間。<li>如果單位是小時，則起始時間是小時（包含天，不足兩位要補 0），格式例：2022-06-11 09<li>如果單位是天，則起始時間是日期（天），格式例：2022-06-11<li>如果單位是月，則起始時間是日期（月），格式例：2022-06
duration String 必選 持續時長。<li>如果單位是天，則是持續的天數。以此類推。<li>隻支援查詢 60 天以內的用戶信息，對於 time_unit 為 HOUR 的，隻支援輸出當天的統計結果。
items JSON Array 必選 按持續時間查詢範圍內的統計結果
  • items 格式說明：
    • android：安卓平台的數據匯總統計。
    • ios：蘋果平台的數據匯總統計。
關鍵字 類型 選項 含義
new Int64 可選 新增用戶
online Int64 可選 在線用戶
active Int64 可選 活躍用戶

查詢訊息生命周期狀態

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

調用地址

GET https://push.api.engagelab.cc/v4/status/message

請求示例

curl -v https://push.api.engagelab.cc/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://push.api.engagelab.cc/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 必選 <li>設備 ID，如果有多個 registration_id 時，中間通過","分割。<li>最多支援 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 可選 取值範圍：<li>plan：計畫目標<li>target_valid：有效目標<li>target_invalid：無效目標<li>sent：傳送；<li>sent_failed：傳送失敗<li>delivered：送達<li>delivered_failed：送達失敗<li>Impression：展示<li>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
在文档中心打开