Push Troubleshooting - Jiguang Docs

Push Troubleshooting Best Practices

The key to troubleshooting push delivery is not only checking whether a user received a message. A push should be split into verifiable stages: whether the request was accepted, whether the target matched, whether the channel was available, whether the vendor accepted the message, whether the device displayed it, and whether the user clicked it. Each stage has corresponding tools and data metrics.

This guide applies to notification messages, custom messages, Android vendor channels, iOS APNs, HarmonyOS channels, and push tasks created through either the API or the console.

Information to Prepare First

When troubleshooting a single device, prepare the following information first:

AppKey: Confirm that the app being checked is the same AppKey used by the push request.
Message ID: For console pushes, find it in Push Records; for API pushes, use the msg_id returned by the API.
Registration ID: Obtain it after client initialization. Single-device troubleshooting requires the current valid Registration ID of the target device.
Push request body: Especially platform, audience, notification, message, options, and third_party_channel.
Device environment: OS type, OS version, device model, app version, SDK version, notification permission, network status, and whether the app was reinstalled.
Business expectation: Whether the message should arrive immediately, be kept offline, arrive only while online, overwrite an old message, be revoked, or fall back to SMS.

For test scenarios, use Registration ID targeting first. This avoids interference from tags, aliases, segments, or other targeting rules.

Recommended Troubleshooting Flow

Confirm whether the push request was submitted successfully and obtain the msg_id.
Check the push status, message body, target conditions, and platform data in Push Records.
Use Message Query in the troubleshooting tool. Enter the Message ID and Registration ID to view the message lifecycle.
Use Device Query to confirm whether the Registration ID belongs to the current AppKey, whether the device is online, whether notification permission is enabled, and whether the vendor token is available.
Continue by platform and channel: for Android, check the JPush channel and vendor channels; for iOS, check APNs environment and certificate configuration; for HarmonyOS, check vendor parameters and receipts.
Use the Report API, message status query API, or Callback API for batch verification and long-term monitoring.

Identify the Failed Stage First

Symptom	Check First	Common Causes
API returns an error directly	Push API response code, authentication, request body	Incorrect AppKey/Secret, invalid JSON, empty target, invalid field value, insufficient quota
Console shows push failure	Failure reason in Push Records	Target condition mismatch, insufficient vendor quota, invalid platform parameters
Push succeeds but one device does not receive it	Message Query, Device Query, Registration ID	Expired Registration ID, device does not belong to the AppKey, device offline, notification permission disabled
Android does not use vendor channel	Vendor token, delivery strategy, quota query	Vendor SDK not integrated correctly, token not obtained, strategy mismatch, quota exhausted
iOS notification is not received	APNs environment, certificate or Token Authentication, `apns_production`	Production/development environment mismatch, expired certificate, Bundle ID mismatch, device token changed
Delivery rate is low but request succeeds	Push Records, Report API, callbacks, vendor classification	Users offline, notification permission disabled, vendor quota/QPS limit, invalid message classification, TTL too short
Click rate is abnormal	Click action configuration, client callback, landing page state	Incorrect jump URL, click callback not handled, message expired but landing page does not validate state

Console Troubleshooting

Push Records

Go to JPush Console > Message Push > Push Management > Push Records to view task status.

Focus on:

Push status: A successful push means the JPush service has processed the push task request. It does not mean all devices have received it.
Message body: Click the message body to view the full JSON and confirm whether the actual payload matches expectations.
Platform and channel data: For Android, check JPush channel and vendor channel data separately.
Loss analysis: View failure or loss ratios at different stages.
Message troubleshooting entry: When entering lifecycle troubleshooting from Push Records, you must provide both the Message ID and the device Registration ID.

Huawei and Meizu channels require vendor delivery receipts for more accurate delivery data. Display-rate statistics are supported only by Xiaomi and the JPush channel.

Troubleshooting Tools

Go to JPush Console > JPush > Management Tools > Troubleshooting Tools.

Common tools:

Message Query: Enter the Message ID and Registration ID to view the message lifecycle, failed stage, error code, message details, and device details.
Device Query: Enter the Registration ID to view device online status, registration time, notification permission, vendor-channel support, and vendor token information.
Quota Query: View daily quota and remaining quota for vendors such as Xiaomi, OPPO, and vivo. If quota is insufficient, messages may switch to the JPush channel; if the vendor channel is forced, the push may fail.

Server API Troubleshooting

Request Submission Stage

First confirm whether the Push API returns success.

If the request succeeds, save the msg_id for later queries in Push Records, reports, and message lifecycle tools.
If the request fails, fix authentication, request body, target, platform, vendor fields, or quota issues based on the response code.
When pushing by alias, tag, or segment, confirm that the target value matches what the client reported.
When pushing by Registration ID, confirm that the Registration ID belongs to the current AppKey and has not changed because of reinstalling the app, clearing data, changing packages, or similar actions.

Reports and Status Queries

Use the Report API to establish a stable view of push results:

GET /v3/received/detail: Query detailed delivery statistics by msg_id, including JPush channel, Android vendor channel, iOS APNs, and HarmonyOS metrics.
POST /status/message: Query the delivery status of one message across a group of devices. This is suitable for single-message troubleshooting in VIP scenarios.
Callback API: Receive detailed delivery, non-delivery, click, and push-success data for internal monitoring and business analysis.

Report data may continue to increase as clients report delivery. Do not treat the instant statistics right after sending as the final result.

Android Troubleshooting

Android troubleshooting usually requires separating the JPush channel from vendor channels.

Client Integration

Confirm that the JPush SDK initializes successfully and can obtain the current Registration ID.
Confirm that the vendor SDK for the target device brand is integrated correctly.
Confirm vendor token callbacks for Xiaomi, Huawei, Honor, OPPO, vivo, Meizu, FCM, ASUS, HarmonyOS, or other channels.
Check whether app notification permission is enabled. For Android 8.0 and later, also check notification channel configuration.
If click actions, custom ringtones, badges, notification styles, or similar features are used, confirm that client configuration matches server-side fields.

Vendor Channels

If the device does not use a vendor channel, troubleshoot in this order:

Confirm in Device Query that the corresponding vendor token exists.
Check vendor console configuration, package name, signature, AppID, AppKey, AppSecret, and related settings.
Check whether distribution, distribution_fcm, and distribution_customize under options.third_party_channel match expectations.
Check vendor quota and QPS, especially for vendors with quota query support such as Xiaomi, OPPO, and vivo.
Check message classification fields such as options.classification, channel_id, importance, category, notify_level, and template fields.
Confirm that the message content complies with vendor classification rules. Avoid using system-message classification for marketing content.

iOS Troubleshooting

For iOS notification delivery, focus on APNs environment, certificates, and device tokens.

Confirm that the certificate or Token Authentication configuration is valid and that the Bundle ID matches the app.
Confirm that the development or production environment is correct. When using the API, specify the APNs environment with options.apns_production.
Confirm that the user has granted notification permission and that the device token has been registered and synchronized to JPush.
If notification display statistics are required, confirm that the iOS Service Extension and display-statistics API are integrated.
If message overwrite is used, check whether options.apns_collapse_id is generated consistently for the same business event.
If clicking the notification does not open the expected page, check the client notification click callback and jump parameters.

HarmonyOS Troubleshooting

For HarmonyOS channels, check the following:

Whether SDK initialization, AppKey, package name, and permissions are configured correctly.
Whether the corresponding HarmonyOS Registration ID can be obtained.
If vendor notification capabilities are used, check fields under notification.hmos, such as category, test_message, and receipt_id.
If a delivery strategy is configured, check whether options.third_party_channel.hmos.distribution matches expectations.
Use the Report API to view metrics such as hmos_hmpns_sent, hmos_hmpns_received, hmos_msg_sent, and hmos_msg_received.

Common Scenarios

A Single Device Does Not Receive Messages

Send a test message directly to the Registration ID.
Use Message Query with the Message ID and Registration ID to view the lifecycle.
Use Device Query to confirm whether the device belongs to the current AppKey, whether it is online, whether notification permission is enabled, and whether the vendor token exists.
For an offline Android device, first confirm whether the vendor channel is available. If only the JPush channel is used, offline devices cannot receive the message.
For iOS, confirm the APNs environment, certificate, and user notification permission.

Some Users Do Not Receive Messages

Compare device model, OS version, app version, SDK version, notification permission, and vendor token between users who received the message and users who did not.
Check whether the issue affects only one vendor, one platform, or one app version.
Check whether tag, alias, or segment conditions match only part of the intended audience.
Check vendor quota, QPS, and per-device daily limits for operational messages.
View loss analysis in Push Records and channel-level data in the Report API.

Operational Message Delivery Rate Fluctuates

Confirm whether the message is classified as an operational or marketing message.
Check per-user frequency control and vendor operational-message policies.
Avoid sending a large number of operational messages at the same time. Use scheduled, batched, and segmented delivery.
Do not disguise marketing, recommendation, or campaign messages as system messages, as this may affect vendor-channel stability.

Important Messages Are Not Delivered

Confirm whether important-message classification has been applied for and configured according to vendor rules.
Check whether options.classification=1 and vendor-specific classification fields are correct.
Set a proper time_to_live to avoid losing messages when devices are briefly offline.
For high-reach scenarios, configure SMS fallback so SMS can be sent if the push is not delivered in time.
Integrate delivery, non-delivery, and click callbacks to build a traceable closed loop.

Custom Messages Are Not Received

Custom messages usually depend on the device being online. If the device is offline, it may not receive them in time.
Only some vendors support delivering custom messages through vendor channels, and vendor capability restrictions still apply.
For scenarios where offline users still need to be reminded, use custom-message-to-vendor-notification capabilities.
Check whether the client custom message callback is implemented and whether foreground/background handling is consistent.

Troubleshooting Record Template

Record the following information for each troubleshooting case to support review and escalation to Jiguang support:

Information	Example
AppKey	Current app AppKey
Message ID	`msg_id` returned by the API or shown in Push Records
Registration ID	Current valid Registration ID of the target device
Platform/device model	Android / iOS / HarmonyOS, specific brand and OS version
SDK version	JPush SDK version integrated in the client
Push method	API / console / scheduled / A/B test
Push type	Notification / custom message / notification + custom message
Delivery strategy	JPush channel, vendor first, JPush first with vendor fallback, etc.
Lifecycle result	Success, failed stage, error code, error message
Device status	Online status, notification permission, vendor token, latest registration time

Pre-Launch Checklist

The msg_id is saved after a successful API request.
The client can obtain and report the latest Registration ID.
Android vendor tokens are obtained correctly, and vendor console configuration is correct.
iOS APNs environment, certificate, or Token Authentication is configured correctly.
HarmonyOS package name, permissions, and vendor parameters are configured correctly.
Targeting conditions such as tags, aliases, and Registration IDs match the business system.
Important messages have message classification, offline retention, and SMS fallback where needed.
Operational messages have frequency control, segmentation, and vendor operational-message policies configured.
Push Records, troubleshooting tools, Report API, or Callback API are integrated into the troubleshooting process.
A troubleshooting record template is ready so online issues can be located quickly.