简体中文
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 提供各类统计数据查询功能。

这是 Stats API 最近的版本。v4 版本的改进为：

  • 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成，比如：curl，浏览器插件等。
  • 推送内容完全使用 JSON 的格式。

调用验证

详情参见 REST API 概述的 鉴权方式 说明。

消息统计

  • 查询 message_id 生命周期中各个状态的统计数据。
  • 每条推送消息的统计数据最多保留一个月。

调用地址

GET v4/status/detail
          GET v4/status/detail
此代码块在浮窗中显示

请求示例

curl -v https://push.api.engagelab.cc/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://push.api.engagelab.cc/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 必选 <li>消息 ID，如果有多个 message_id 时，中间通过","分割。<li>最多支持 100 个 message_id。

返回示例

< HTTP/1.1 200 OK < Content-Type: application/json { "1229760629": { "targets": 11, "sent": 11, "delivered": 10, "impressions": 8, "clicks": 2, "sub": { "notification": { }, "message": { } } }, "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": { } }, "live_activity": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 0, "clicks": 0, "sub_ios": { "engageLab_ios": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "apns": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 0, "clicks": 0 } } } } } }
          < HTTP/1.1 200 OK
< Content-Type: application/json

{
    "1229760629": {
        "targets": 11,
        "sent": 11,
        "delivered": 10,
        "impressions": 8,
        "clicks": 2,
        "sub": {
            "notification": {

            },
            "message": {

            }
        }
    },
    "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": {

                }
            },
            "live_activity": {
                "targets": 1,
                "sent": 1,
                "delivered": 1,
                "impressions": 0,
                "clicks": 0,
                "sub_ios": {
                    "engageLab_ios": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "apns": {
                        "targets": 1,
                        "sent": 1,
                        "delivered": 1,
                        "impressions": 0,
                        "clicks": 0
                    }
                }
            }
        }
    }
}
此代码块在浮窗中显示

返回参数

成功响应为一个 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：自定义消息的数据汇总统计。<li>live_activity:实时活动消息的数据汇总统计。<li>voip:voip消息的数据汇总统计
细分指标
关键字 类型 选项 含义
sub_android Object 可选 安卓各个推送通道的数据汇总统计
engageLab_android Object 可选 安卓 Engagelab 通道的数据汇总统计
huawei Object 可选 华为通道的数据汇总统计
xiaomi Object 可选 小米通道的数据汇总统计
oppo Object 可选 OPPO 通道的数据汇总统计
vivo Object 可选 vivo 通道的数据汇总统计
meizu Object 可选 魅族通道的数据汇总统计
honor Object 可选 荣耀通道的数据汇总统计
fcm Object 可选 FCM 通道的数据汇总统计
sub_ios Object 可选 苹果各个推送通道的数据汇总统计
engageLab_ios Object 可选 iOS Engagelab 通道的数据汇总统计
apns Object 可选 iOS APNs 通道的数据汇总统计

用户统计

  • 提供近 2 个月内某时间段的用户相关统计数据：包括新增用户、在线用户、活跃用户。
  • 时间单位支持：HOUR（小时）、DAY（天）、MONTH（月）。

调用地址

GET 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/status/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/status/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-11T09<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 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?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?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" }, "17259fd3a7c568d4xxx":{ "error_message": "regid illegal" } }
          < 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"
    },
    "17259fd3a7c568d4xxx":{
        "error_message": "regid illegal"  
    }
}
此代码块在浮窗中显示

返回参数

成功响应为一个 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
在文档中心打开
Contact Sales