简体中文
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 https://push.api.engagelab.cc/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 必选
  • 消息 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：自定义消息的数据汇总统计。
    		•
    细分指标
    关键字 类型 选项 含义
    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 可选 苹果各个推送通道的数据汇总统计
    ngageLab_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/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 必选 时间单位。有三个取值：
  • HOUR：小时
  • DAY：天
  • MONTH：月
    		•
    start String 必选 起始时间。
  • 如果单位是小时，则起始时间是小时（包含天，不足两位要补 0），格式例：2022-06-11T09
  • 如果单位是天，则起始时间是日期（天），格式例：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 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?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 必选
  • 设备 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" }, "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 可选 取值范围：
  • 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
    在文档中心打开