logo
日本語
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
お問い合わせ
ログイン
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTPicon Marketing Automation
EngageLab ドキュメント >AppPush >REST API >Statistics API
EngageLab ドキュメント >AppPush >REST API >Statistics API

Statistics API

最新更新：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://pushapi-sgp.engagelab.com/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://pushapi-sgp.engagelab.com/v4/messages/details?message_ids=1613113584,1229760629 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/messages/details?message_ids=1613113584,1229760629 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
このコードブロックはフローティングウィンドウ内に表示されます

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
                    }
                }
            }
        }
    }
}
    このコードブロックはフローティングウィンドウ内に表示されます

    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

    Push Plan Statistics

    • This interface is used to obtain detailed statistical indicators of the push plan. It supports batch query of the full lifecycle data of multiple plans within the specified time range, including multi-dimensional subdivision indicators (platform/vendor/message type).

    Call Address

    GET v4/status/plan/detail

    Request Example

    GET /v4/status/plan/detail?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-07
              GET /v4/status/plan/detail?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-07
    このコードブロックはフローティングウィンドウ内に表示されます

    Request Parameters

    Parameter Name Type Required Description
    plan_ids string Yes List of push plan IDs, separated by English commas for multiple IDs. Up to 100 IDs are supported.
    start_date string Yes Statistical start date (Format: yyyy-MM-dd). It needs to meet:
  • 1. End date >= Start date
  • 2. Date interval ≤ 31 days
    		•
    end_date string Yes Statistical end date (Format: yyyy-MM-dd)

    Return Parameter Description

    Successful Response

    • The returned object is in a key-value pair structure, and the key name is the requested plan_id.
    • Each plan_id corresponding object contains the following fields:
    Parameter Name Type Description
    targets int64 Number of valid target devices (total number of devices after deduplication and validity filtering)
    sent int64 Number of devices for which the sending task was actually created
    delivered int64 Number of devices actually delivered (only data within 5 days is counted)
    impressions int64 Number of message impressions (only data within 5 days is counted)
    clicks int64 Number of user clicks (only data within 5 days is counted)
    sub object Subdivision statistics of message types (structure is shown in the sub-table below)

    • Structure of the sub object

      Message Type Description Sub-structure
      notification Statistics of notification bar messages Contains sub_android (Android vendor statistics)/sub_ios (iOS statistics)
      message Statistics of custom messages Contains sub_android/sub_ios
      live_activity Statistics of live activity messages Only contains sub_ios
      voip Statistics of VOIP messages Only contains sub_ios

    • Platform Vendor Statistics Fields

      Parameter Name Type Description
      targets int64 Number of valid target devices for the corresponding vendor
      sent int64 Actual number of sends through the vendor channel
      delivered int64 Actual number of deliveries through the vendor channel
      impressions int64 Number of impressions through the vendor channel
      clicks int64 Number of clicks through the vendor channel

    Response Example

    Successful Response

    { "push_20231101": { "targets": 1500, "sent": 1450, "delivered": 1400, "impressions": 1350, "clicks": 120, "sub": { "notification": { "sub_android": { "huawei": { "targets":200, "sent":190, "delivered":185, "impressions":180, "clicks":15 }, "xiaomi": { "targets":180, "sent":175, "delivered":170, "impressions":165, "clicks":10 } }, "sub_ios": { "apns": { "targets":300, "sent":295, "delivered":290, "impressions":285, "clicks":25 } } }, "live_activity": { "sub_ios": { "apns": { "targets":50, "sent":48, "delivered":45, "impressions":40, "clicks":5 } } } } } }
              {
  "push_20231101": {
    "targets": 1500,
    "sent": 1450,
    "delivered": 1400,
    "impressions": 1350,
    "clicks": 120,
    "sub": {
      "notification": {
        "sub_android": {
          "huawei": { "targets":200, "sent":190, "delivered":185, "impressions":180, "clicks":15 },
          "xiaomi": { "targets":180, "sent":175, "delivered":170, "impressions":165, "clicks":10 }
        },
        "sub_ios": {
          "apns": { "targets":300, "sent":295, "delivered":290, "impressions":285, "clicks":25 }
        }
      },
      "live_activity": {
        "sub_ios": {
          "apns": { "targets":50, "sent":48, "delivered":45, "impressions":40, "clicks":5 }
        }
      }
    }
  }
}
    このコードブロックはフローティングウィンドウ内に表示されます

    Failed Response

    { "error": { "code": 21003, "message": "Parameter value is invalid" } }
              {
  "error": {
    "code": 21003,
    "message": "Parameter value is invalid"
  }
}
    このコードブロックはフローティングウィンドウ内に表示されます

    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://pushapi-sgp.engagelab.com/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://pushapi-sgp.engagelab.com/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==
    このコードブロックはフローティングウィンドウ内に表示されます

    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
        }
    }]
}
    このコードブロックはフローティングウィンドウ内に表示されます

    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://pushapi-sgp.engagelab.com/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://pushapi-sgp.engagelab.com/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==
    このコードブロックはフローティングウィンドウ内に表示されます

    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"  
    }
}
    このコードブロックはフローティングウィンドウ内に表示されます

    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
    お問い合わせ