logo
English
English
繁體中文
简体中文
日本語
ภาษาไทย
Contact Us
Login
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab Docs >AppPush >REST API >Statistics API
EngageLab Docs >AppPush >REST API >Statistics API

Statistics API

Last updated：2023-02-27

info This is the latest version of the Stats API. Some improvements in v4：

  • Use HTTP Basic Authentication for access authorization. n this way, the entire API request can be completed using common HTTP tools，like：curl，browser plugins。
  • Push content completely uses JSON format.

Overviews

Stats API v4 provides various statistical data query functions.

Authentication

See REST API Overview for details Authentication method

Message statistics

  • Query the statistics of each state in the message lifecycle.
  • The statistical data of each push message can be kept for at most one month.

API Url

GET v4/status/detail

request example

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==
This code block in the floating window

Request Parameters

key words type Option Description
message_ids String required
  • message_id，If there are multiple messages_id, the middle is divided by ",".
  • Up to 100 message_ids are supported
    		•

    Response Example

    < 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
                    }
                }
            }
        }
    }
}
    This code block in the floating window

    Response Parameters

    The successful response is a JSON object，and the key is message_id，Each message needs to include lifecycle statistics of each phase:

    | key words | type | option | Description |

    Keyword Type Options Meaning
    targets Int64 Required Valid targets. The number of target devices after the push task's selected target audience has been filtered for validity.
    sent Int64 Required Number of sends. The number of devices for which the Engagelab server successfully created a send task among the valid target devices.
    delivered Int64 Required Number of deliveries. The number of devices to which the notification message was actually delivered. Deliveries after 5 days are not counted. For Huawei, Meizu, and iOS, callback configuration is needed for more accuracy.
    impressions Int64 Required Number of impressions. The number of devices on which the notification message was successfully displayed. Impressions after 5 days are not counted.
    clicks Int64 Required Number of clicks. The number of times the notification message was clicked by users after being successfully displayed. Clicks after 5 days are not counted.
    sub Object Required Detailed metrics of the statistical data, see table below.
  • notification: Summary statistics of notification bar message type data.
  • message: Summary statistics of custom message data.
  • live_activity: Summary statistics of real-time activity message data.
  • voip: Summary statistics of voip message data.
    		•
    indicator
    key words Type option description
    sub_android Object optional Data summary and statistics of Android push channels
    engageLab_android Object optional Data summary and statistics of Android Engagelab channel
    huawei Object optional Data summary and statistics of Huawei channels
    honor Object optional Data summary and statistics of Honor channels
    xiaomi Object optional Data summary and statistics of Xiaomi Channel
    oppo Object optional Data summary and statistics of OPPO channel
    vivo Object optional Summary and statistics of vivo channel data
    meizu Object optional Data summary and statistics of Meizu channel
    fcm Object optional Data summary statistics of FCM channel
    sub_ios Object optional Data summary and statistics of Apple's push channels
    engageLab_ios Object optional Data summary and statistics of iOS Engagelab channel
    apns Object optional Data summary statistics of iOS APNs channels

    User statistics

    • Provide user related statistical data of a certain period in the past two months：It includes new users, online users and active users.
    • Time Unit：HOUR 、DAY、MONTH.

    Request Api Url

    GET v4/status/users

    Request Example

    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==
    This code block in the floating window

    Request Parameters

    key words Type Option description
    time_unit String required time unit：
  • HOUR
  • DAY
  • MONTH
    		•
    start String required Start time
  • If the unit is hour, the starting time is hour (including days, and 0 should be filled in if less than two digits). Format example: 2022-06-11 09
  • If the unit is day, the start time is the date (day). Format example: 2022-06-11
  • If the unit is month, the start time is the date (month). Format example: 2022-06
    		•
    duration String required Duration
  • If the unit is a day, it is a continuous number of days. and so on.
  • Only user information within 60 days can be queried. If the time unit is HOUR, only statistical results of the current day can be output.
    		•

    Response Example

    < 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
        }
    }]
}
    This code block in the floating window

    Response Parameters

    Success response a JSON Object：

    key words Type options Description
    time_unit String required time unit
  • HOUR
  • DAY
  • MONTH
    		•
    start String required 起始时间。
  • If the unit is hour, the starting time is hour (including days, and 0 should be filled in if less than two digits). Format example: 2022-06-11 09
  • If the unit is day, the start time is the date (day). Format example: 2022-06-11
  • If the unit is month, the start time is the date (month). Format example: 2022-06
    		•
    duration String required Duration
  • If the unit is a day, it is a continuous number of days. and so on.
  • Only user information within 60 days can be queried. If the time unit is HOUR, only statistical results of the current day can be output.
    		•
    items JSON Array required Statistical results within the query range by duration
    • items field description：
      • android：Data summary statistics of Android platform.
      • ios：Data summary and statistics of Apple platform.
    key words type option description
    new Int64 optional New Users
    active Int64 optional Active Users

    Query message lifecycle status

    • Querying the message lifecycle status of the corresponding device under message_id.
    • The statistical data of each push message can be kept for at most one month.

    Request Api Url

    GET v4/status/message

    Request example

    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==
    This code block in the floating window

    Request Paramaters

    key words type option description
    message_id String required message ID
    registration_ids String required
  • device ID，If there are multiple registration_ids, the middle is divided by ","
  • Support up to 1000 registration_ids
    		•

    Response Example

    < 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"  
    }
}
    This code block in the floating window

    Response Parameters

    成功响应为一个 JSON Object，包含这条消息下各个 registration_id 的消息当前状态，如果有异常信息，则将信息包含在 error_message 中。

    关键字 类型 选项 含义
    status String 可选 取值范围：
  • plan：计划目标
  • target_valid：有效目标
  • target_invalid：无效目标
  • sent：发送；
  • sent_failed：发送失败
  • delivered：送达
  • delivered_failed：送达失败
  • Impression：展示
  • click：点击
    		•
    error_message String 可选 错误信息

    Response code

    HTTP status code

    Reference Documents：HTTP-Status-Code

    Return codes

    Code description detail description HTTP Status Code
    0 success request success 200
    21001 The method is not supported or url err Request method (GET/POST) error or url error (interface does not exist) 404
    21003 Parameter value is invalid Illegal parameter value 400
    23001 Basic authentication failed HTTP Basic authorization failed 401
    23002 Missing parameter! Missing the necessary parameter! 400
    23004 time_unit value does not match with start! The time_unit and start parameter values do not match 400
    23007 Only support quering the message_id within 30 days! Only messages within 30 days can be queried 400
    23100 server error System internal error 500
    27000 Server response time out, please try again later System internal error 500
    27201 msgid not exist or not belong this app Msgid does not exist or does not belong to this app 400
    在文档中心打开
    icon
    Contact Sales