Get Push Logs
The IM service can provide push history records under the App Key. Push history records are provided in the form of log files and are compressed. You can use the server API to obtain the push logs for a specified app.
The server API interface only returns the download URL of the push log file. After obtaining the URL, please download it yourself.
Enable the Service
If needed, please submit a ticket to apply for enabling the Push Log Download Service.
Pricing Rules: "Push Log Download" is a value-added service. The IM Ultimate Plan allows free use of this service. Other IM pricing plans are charged based on the number of push logs generated by the server, in increments of 10 million logs. The cost is 150 RMB per 10 million logs for domestic data centers and 300 RMB per 10 million logs for international data centers. If the monthly push log count does not reach 10 million, the minimum charge applies. For specific details, refer to the Pricing Guide.
Push Log Description
If your app uses an international data center, please complete the necessary configurations based on your SDK version to ensure that push-related statistics are reported to the correct data center. For more details, refer to the International Data Center Usage Guide.
Push logs currently support statistics for offline push notifications of one-to-one chats, group chats, and system conversations, as well as pushes sent via the /push.json and /push/user.json server APIs. The offline push log records for ultra groups are not yet complete and are not recommended for use.
Push Delivery Log Collection Notes
- For Huawei and Meizu devices, the data collection for push delivery rates relies on the "Delivery Receipt" feature provided by Huawei and Meizu. You need to complete the corresponding configurations on the manufacturers' platforms. A brief guide is provided in the developer documentation:
- The delivery rate statistics for Google FCM pushes only support the data message method and do not support the notification message method. Additionally, log data collection relies on active reporting by the application. For more details, refer to the Android client SDK documentation Collect FCM Push Delivery Data.
- The delivery rate statistics for Apple APNs pushes rely on active reporting by the application. For more details, refer to the iOS client SDK documentation Report Push Data.
Push Click Log Collection Notes
- The click rate statistics for Huawei pushes may rely on active reporting by the application, depending on the client SDK version:
- SDK < 5.1.4: Does not support push click statistics.
- 5.1.4 ≦ SDK < 5.2.3: Relies on active reporting by the application. See the Android client SDK documentation Collect Huawei Push Click Data.
- SDK ≧ 5.2.3: The SDK automatically reports clicks, no application handling is required.
- The click rate statistics for Apple APNs pushes rely on active reporting by the application. For more details, refer to the iOS client SDK documentation Report Push Data.
Data Timeliness
There is a certain delay in obtaining data (T+0 mode).
- First, the data file for each natural hour is generated only after the hour ends. For example, the log data for the period between 12:00 and 13:00 is generated after 13:00.
- Second, due to the time required for data statistics and file compression, it generally takes an additional 3 hours before the download URL is available. For example, the log data for the period between 12:00 and 13:00 will be available for download after 16:00.
- Additionally, once the service is enabled, the server can save the push log data for the current natural hour. For example, if you enable the service at any time between 12:00 and 13:00, the IM server can provide push logs starting from 12:00.
The IM server packages push log data by natural hour, so push log data packages are only available on an hourly basis.
Log Retention Period
Push log files stored on the server are retained for only 7 days. After 7 days, the server automatically deletes these log files.
Log Format
| Name | Type | Description |
|---|---|---|
| messageId | String | Push message ID. |
| receiverId | String | Receiver user ID. |
| systemType | String | Receiver's device operating system type: iOS, Android |
| pushStatus | String | Push status, which can be success (0), failure (1), delivered (2), or clicked (3). |
| sendTime | String | Message send time, accurate to milliseconds, in UTC time for international data centers. |
| time | String | Timestamp of push status change, which may be the time of push success, failure, delivery, or click, depending on the pushStatus value. Accurate to milliseconds, in UTC time for international data centers. |
| pushType | String | Push type. Possible values include MI, HW, HONOR, MEIZU, OPPO, VIVO, FCM, APNS, RONG (IM self-built push). |
| pushChannelId | String | Channel ID, only valid when pushStatus is success (0). Currently supported for Xiaomi, Huawei, and OPPO. |
| pId | String | Push correlation ID, only supported for FCM and APNS. Can be used to correlate push success, delivery, and click records to track push status changes for FCM and APNs. This field requires client SDK version ≧ 5.1.7. |
| requestId | String | Push request ID, which is the unique identifier for the IM server's API call to third-party push services. Can be used with pushToken to correlate push success, delivery, and click records for Xiaomi, Meizu, Huawei, VIVO, and OPPO. |
| pushToken | String | Push Token. Can be used with requestId to correlate push success, delivery, and click records for Xiaomi, Meizu, Huawei, VIVO, and OPPO. |
| deviceId | String | Target device ID for the push. Can be used with messageId to correlate push success and click records for Huawei, VIVO, and OPPO. |
| senderId | String | Message sender ID. If the push is sent directly (not triggered by a message), there is no message sender ID. |
| channelType | String | The type of conversation the message belongs to, which can be one-to-one chat (1), group chat (3), system notification (6), or ultra group chat (10). |
| channelId | String | This field is deprecated. Currently, this field is only used for compatibility with older versions and is not recommended. Use targetId as a replacement. |
| targetId | String | Conversation ID. Depending on the channelType value, this may be a group chat ID or ultra group ID. If channelType is a system conversation or one-to-one chat, this field is empty because the conversation ID is the receiver's user ID (receiverId). |
| groupChannelId | String | Channel ID in the ultra group scenario. This field is empty in non-ultra group scenarios. |
| thirdRespBody | String | (Third-party platform return field) Push status callback from third-party push platforms, relying on the push receipt services provided by each manufacturer. Due to limitations of third-party platforms, callback data varies: Xiaomi and Meizu callbacks include push delivery and click data. Huawei, VIVO, and OPPO include push delivery data. In Huawei push callback data, if the push is triggered by the IM service, the bitag parameter value will have an rc prefix, structured as rc_{appkey}_{messageid}_0, e.g., rc_fafweefwf_596E-P5PG-4FS2-7OJK_0. |
| pushErrorCode | String | Error code for push failures when the IM service sends pushes to third-party vendors. |
| pushErrorMsg | String | Push failure description corresponding to the pushErrorCode. |
| thirdApiRespInfo | String | (Third-party platform return field) Response returned by the third-party push API. Refer to the third-party push platform documentation below the table. |
| thirdApiHttpStatusCode | String | (Third-party platform return field) HTTP Status Code returned by the third-party push API. Refer to the third-party push platform documentation below the table. |
| thirdApiBusCode | String | (Third-party platform return field) Business Code returned by the third-party push API. Refer to the third-party push platform documentation below the table. |
Third-party push platform official documentation:
- Huawei Push Server API Documentation, Huawei Push Downstream Message Receipt
- Xiaomi Push Server API Documentation, Xiaomi Push Message Receipt, Xiaomi Push Error Codes
- Meizu Push Server API Documentation
- VIVO Push Server API Documentation, VIVO Push Message Receipt
- OPPO Push Server API Documentation (Broadcast Push), OPPO Push Server API Documentation (Single Push), OPPO Push Message Receipt
Request Method
POST: https://Data Center Domain/message/push/detail/history.json
Rate Limit: 100 requests per second
Signature Rule: All server API requests must be verified. For details, refer to API Request Signature.
Body Parameters
The HTTP request body data format is application/x-www-form-urlencoded, and the following HTTP form parameters are supported:
| Parameter | Type | Required | Description |
|---|---|---|---|
| date | String | Yes | Specified time in the format YYYYMMDDHH, used to obtain push log data for a specific hour. For example, for an app using the China (Beijing) data center, to obtain data for the period between 1:00 AM and 2:00 AM on January 1, 2023, pass 2023010101. Note: If your app uses the Singapore data center, the date value should use Beijing time. |
Request Example
POST /message/push/detail/history.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Timestamp: 1408710653491
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded
date=2023010101
Response Parameters
| Return Value | Return Type | Description |
|---|---|---|
| code | Int | Return code, 200 indicates success. |
| url | String | Download URL for the historical records. If there is no message record data, the url value is empty. |
| date | String | Historical record time. |
Response Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code":200,
"url":"http://xx.com/1/c6720eea-452b-4f93-8159-7af3046611f1.gz",
"date":"2023010101"
}