English
English
繁體中文
简体中文
にほんご
ภาษาไทย
Login Sign Up
icon AppPush icon WebPush icon WhatsApp icon Email icon SMS icon 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 https://push.api.engagelab.cc/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 <li>message_id，If there are multiple messages_id, the middle is divided by ",".<li>Up to 100 message_ids are supported

Response Example

< 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": {}
        }
    }
}
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
targets Int64 required Effective goals. The number of target devices filtered by the effectiveness of the target population selected for the push task.
sent Int64 required Number of sended. Among the effective target devices, the Engagelab server actually successfully created the number of devices to send tasks.
delivered Int64 required Number of deliveries. After the notification message is sent, the actual quantity delivered to the device terminal is not included in the quantity delivered five days later. Huawei, Meizu and iOS need to configure callback delivery data to be more accurate.
impressions Int64 required Number of displays. After the notification message is delivered, the actual number of successful displays at the device terminal is not included in the number of displays after 5 days.
clicks Int64 required Number of clicks. After the notification message is successfully displayed, the actual number of clicks by the user will not be counted.
sub Object required A breakdown indicator of statistical data.<li>notification：Data summary statistics of notification bar message types.<li>message：Data summary statistics of user-defined messages.
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 https://push.api.engagelab.cc/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：<li>HOUR<li>DAY<li>MONTH
start String required Start time<li>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<li>If the unit is day, the start time is the date (day). Format example: 2022-06-11<li>If the unit is month, the start time is the date (month). Format example: 2022-06
duration String required Duration<li>If the unit is a day, it is a continuous number of days. and so on.<li>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<li>HOUR<li>DAY<li>MONTH
start String required 起始时间。<li>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<li>If the unit is day, the start time is the date (day). Format example: 2022-06-11<li>If the unit is month, the start time is the date (month). Format example: 2022-06
duration String required Duration<li>If the unit is a day, it is a continuous number of days. and so on.<li>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
online Int64 optional Online 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 https://push.api.engagelab.cc/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 <li>device ID，If there are multiple registration_ids, the middle is divided by ","<li>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 可选 取值范围：<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 可选 错误信息

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
在文档中心打开