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

Statistics API

Last updated：2023-02-28

info This is the latest version of Stats API.The improvement of the v4 version is as follows：

  • Use HTTP Basic Authentication to authorize access. In this way, the entire API request can be completed using common HTTP tools, such as curl and browser plug-ins
  • The push content is in JSON format

Overview

Stats API v4 provides multiple functions of data query.

Call Validation

For more information, see Authentication method

Message Statistics

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

Request Api Uri

GET v4/messages/details

Request Example

curl -v https://webpush.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://webpush.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

Keywords Type Option Description
message_ids String required <li>message id，Multiple message_ids are separated by ","<li>up to 100 messages_ids

Return Example

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

Return Parameters

The successful response is a JSON object, where the key is each message_id, and each message needs to contain the life cycle statistics of each phase：

Keywords Type Option Description
targets Int64 required Effective objectives. The number of target devices selected by the task after effectiveness screening will be pushed.
sent Int64 required Send quantity. Among the effective target devices, the Engagelab server actually successfully created the number of devices that sent the task.
delivered Int64 required Delivery quantity. After the notification message is sent, the actual delivery quantity to the Web end is not included in the delivery quantity after 5 days.
impressions Int64 required Display quantity. After the notification message is delivered, the actual number of successful displays on the device terminal will not be counted.
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 Breakdown indicators of statistical data.<li>notification：Data summary statistics of notification bar message types.<li>message：Data summary statistics of user-defined messages.
indicator
Keywords Type Option Description
sub_web Object Optinal Data summary statistics of various push channels on the Web channel
engageLab_web Object Optinal Data summary statistics of Engagelab channel
chrome Object Optinal Data summary statistics of Chrome channel
safari Object Optinal Data summary statistics of Safari channel
firefox Object Optinal Data summary statistics of Firefox channel
edge Object Optinal Data summary statistics of Edge channel
other Object Optinal Data summary statistics of other channel

User statistics

  • Provide relevant statistical data of users in a certain period of time in the past 2 months: including new users, online users and active users.
  • Time Unit：HOUR、DAY、MONTH

Request Api Url

GET v4/status/users

Request Example

curl -v https://webpush.api.engagelab.cc/v4/status/users?time_unit=DAY&start=2014-06-10&duration=3 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/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/users?time_unit=&start=&duration= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
This code block in the floating window

Request parameters

Keywords Type Option Description
time_unit String Optional time unit：<li>HOUR<li>DAY<li>MONTH
start String Optional Start time<li>If the unit is hour, the start time is hour (including days, and 0 should be filled if less than two digits)，eg：2006-01-02T15<li>If the unit is day, the start time is date (day), eg：2022-06-11<li>If the unit is month, the start time is date (month)，eg：2022-06
duration String Optional duration<li>If the unit is day, it is the number of days<li>Only user information within 60 days can be queried. For those whose timeunit is HOUR, only the statistical results of the current day can be output.

Example

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

Parameters

Success Response a JSON Object：

Keywords Type Option Description
time_unit String Required time unit include there value：<li>HOUR<li>DAY<li>MONTH
start String Required Start time<li>If the unit is hour, the start time is hour (including days, and 0 should be filled if less than two digits)，eg：2022-06-11 09<li>If the unit is day, the start time is date (day), eg：2022-06-11<li>If the unit is month, the start time is date (month)，eg：2022-06
duration String Required duration<li>If the unit is day, it is the number of days<li>Only user information within 60 days can be queried. For those whose timeunit is HOUR, only the statistical results of the current day can be output.
items JSON Array Required Query the statistical results within the range by duration
  • items ：
    • web：Data summary statistics of Web platform
Keywords Type Option Description
new Int64 optional New user
online Int64 optional Online user
active Int64 optional Active user

Query message lifecycle status

  • Query the message lifecycle status of the corresponding device under message_id.
  • The statistics of each push message can be retained for one month at most.

Request Api Url

GET v4/status/message

Example

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_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_id=&registration_ids= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
This code block in the floating window

Parameters

Keywords Type Option Description
message_id String Required Message ID
registration_ids String Required <li>Registration ID， Multiple Registration IDs are separated by ","<li>Support up to 1000 registration_ids

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

Parameters

The successful response is a JSON object containing the current status of each registration_id under this message. If there is any exception information, the information will be included in the error-message

Keywords type option Description
status String optional the range of value：<li>plan：plan objectives<li>target_valid：valid objectives<li>target_invalid：Invalid target<li>sent：send out<li>sent_failed：fail in send<li>delivered：deliverd<li>delivered_failed：delivered failed<li>impression：impression<li>click：click
error_message String optional error message

Request Return

HTTP Status

References：HTTP-Status-Code

Return Business Code

Code Description HTTP Status Code
0 success 200
21001 The method is not supported or url err 404
21003 Parameter value is invalid 400
23001 Basic authentication failed 401
23002 Missing parameter! 400
23004 time_unit value does not match with start! 400
23007 Only support quering the message_id within 30 days! 400
23100 server error 500
27000 Server response time out, please try again later 500
27201 msgid is not existed or not belong to this application 400
在文档中心打开
icon
Contact Sales