logo
简体中文
English
繁體中文
简体中文
日本語
ภาษาไทย
联系我们
登录
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab 文档 >WebPush >REST API >统计 API
EngageLab 文档 >WebPush >REST API >统计 API

统计 API

最新更新：2023-03-01

这是 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://webpush.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://webpush.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 { "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 } } } }
              < 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
            }
        }
    }
}
    此代码块在浮窗中显示

    返回参数

    成功响应为一个 JSON Object，其中 key 为每个 message_id，每个消息需要包含各个阶段的生命周期统计数据：

    关键字 类型 选项 含义
    targets Int64 必选 有效目标。将推送任务所选定的目标人群，经过有效性筛选后的目标设备数量。
    sent Int64 必选 发送数量。有效目标设备中，Engagelab 服务器实际成功创建了发送任务的设备数量。
    delivered Int64 必选 送达数量。通知消息发送后，实际送达至 Web 端的数量，5 天之后的送达数量不被计算在内。
    impressions Int64 必选 展示数量。通知消息送达后，实际在设备终端成功展示的数量，5 天之后的展示数量不被计算在内。
    clicks Int64 必选 点击数量。通知消息成功展示后，实际被用户点击的数量，5 天之后的点击数量不被计算在内。
    sub Object 必选 统计数据的细分指标，详情见 下表。
  • notification：通知栏消息类型的数据汇总统计。
  • message：自定义消息的数据汇总统计。
    		•
    细分指标
    关键字 类型 选项 含义
    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://webpush.api.engagelab.cc/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://webpush.api.engagelab.cc/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://webpush.api.engagelab.cc/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://webpush.api.engagelab.cc/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": { "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
    联系销售