Important Notification High-Delivery Best Practices

Important notifications are messages that are strongly related to users, time-sensitive, and expected to reach users as reliably as possible, such as order status, logistics updates, transaction reminders, account security alerts, system alerts, and service changes. Compared with ordinary operation notifications, important notifications focus more on timeliness, accuracy, low disturbance, and traceability.

Improving the delivery rate of important notifications should not rely on a single parameter. We recommend designing the full flow across client integration, message classification, delivery strategy, offline retention, fallback channels, and result tracking.

Recommended Flow

1. Integrate both the Jiguang channel and vendor channels on the client, and confirm that vendor channel tokens are returned normally.
2. Apply for and configure message classifications according to vendor rules, such as system messages, service and communication messages, and private messages.
3. When sending from the server, explicitly set the notification type, vendor classification fields, delivery strategy, and offline retention time.
4. Configure SMS fallback for strong-delivery scenarios, so SMS can be used when push does not arrive in time.
5. Integrate callbacks and statistics, then continuously optimize by delivery, non-delivery, click, and vendor-channel successful request metrics.

Scenario Guide

Client Integration Checklist

Reliable client channels are the foundation of high-delivery important notifications.

Android

• Integrate Jiguang Android SDK and, as needed, Xiaomi, Huawei, Honor, OPPO, vivo, Meizu, FCM, ASUS, HarmonyOS, and other vendor channels.
• Confirm that vendor parameters are configured correctly and that vendor tokens are obtained through logs or callbacks.
• If you use vendor message classification, notification channels, badges, custom sounds, or similar capabilities, create the corresponding channel on the client or complete vendor-side configuration in advance.
• If the app needs foreground notification display, click redirection, or command callbacks, complete the corresponding callback and redirection logic on the client.

iOS

• Confirm that the certificate or Token Authentication configuration is correct, and distinguish production from development environments.
• When sending iOS notifications from the server, use options.apns_production to specify the APNs environment. If not specified, the production environment is used by default.
• If you need APNs notification display statistics, integrate Service Extension and the display statistics API according to the iOS documentation.
• If the same business event keeps updating, use options.apns_collapse_id to update notifications with the same identifier in Notification Center.

HarmonyOS

• Integrate HarmonyOS SDK and complete package name, AppKey, permission, and vendor parameter configuration.
• If you use delivery strategies, options.third_party_channel.hmos.distribution can configure the delivery strategy for HarmonyOS notification messages and custom messages.

Message Classification and Vendor Quotas

Vendor channels classify notifications by message content and app type. Important notifications should use the corresponding important-message types according to vendor rules whenever possible, so they are not classified as operation messages and restricted by frequency or quota limits.

Recommended Practices

• For strongly related service, transaction, order, logistics, and account security messages, apply for system messages, service and communication messages, private messages, or equivalent vendor capabilities as required.
• When sending by API, prioritize options.classification, where 1 means system message and 0 means operation message.
• Huawei, Honor, Xiaomi, OPPO, vivo, and other vendors may also require fields such as channel_id, importance, category, notify_level, and template IDs. Follow vendor documentation and the Jiguang vendor message classification guide.
• Do not disguise marketing, campaign, or content recommendation messages as system messages. Otherwise, vendor review, quotas, or channel stability may be affected.

Key Reminders

• Vendor quota and QPS limits cannot be bypassed. Even VIP users must comply with vendor rules.
• When vendor quota is insufficient, some strategies switch to the Jiguang channel to maximize reach. If you force vendor-channel delivery and the quota is insufficient, the push may fail with a vendor-quota error.
• Operation messages should use per-user frequency control, segmentation, and operation-message strategies to avoid consuming important-notification resources.

Delivery Strategy Configuration

Android vendor channels are system channels and can receive pushes even when devices are offline. The Jiguang channel depends on a long connection and is suitable for online-device delivery. For important notifications, choose a suitable strategy based on business priority.

Recommended Strategies

• Default recommendation: use secondary_push, which uses the Jiguang channel first and then the vendor channel when Jiguang is offline.
• For VIP scenarios that require higher offline delivery: use first_ospush according to business needs, so devices successfully registered with vendor channels prefer vendor channels.
• For special capabilities that must use vendor channels: use ospush, but confirm that the corresponding vendor quota is sufficient; otherwise, delivery may fail.
• For FCM + domestic vendor combined devices, use distribution_fcm with fcm, pns, secondary_fcm_push, or secondary_pns_push.
• For HarmonyOS, use hmos.distribution to configure the delivery strategy.

API Example

          {
  "platform": "android",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "android": {
      "alert": "Your order is being delivered",
      "title": "Order status update",
      "channel_id": "order_status"
    }
  },
  "options": {
    "classification": 1,
    "time_to_live": 86400,
    "third_party_channel": {
      "xiaomi": {
        "distribution": "secondary_push",
        "channel_id": "your_xiaomi_channel_id"
      },
      "huawei": {
        "distribution": "secondary_push",
        "importance": "NORMAL",
        "category": "TRAVEL"
      },
      "honor": {
        "distribution": "secondary_push",
        "importance": "NORMAL"
      },
      "oppo": {
        "distribution": "secondary_push",
        "channel_id": "your_oppo_channel_id"
      },
      "vivo": {
        "distribution": "secondary_push",
        "classification": 1,
        "category": "TODO"
      },
      "hmos": {
        "distribution": "secondary_push"
      }
    }
  }
}

        

Note: The vendor classification fields in this example only show where to configure them. Actual values must follow your app type, vendor review result, and vendor message classification rules.

Offline Retention and Validity Control

Important notifications need to balance "maximum reach" and "avoiding expired disturbance".

• options.time_to_live sets offline message retention time. The default is 86400 seconds (1 day).
• Regular users can retain offline messages for up to 3 days; VIP users can retain them for up to 10 days.
• Setting it to 0 means offline messages are not retained, and only currently online users can receive them.
• For order, logistics, and system reminder messages, set retention time according to business validity.
• For messages that should not be displayed after expiration, add status validation to the landing page or business API.

SMS Fallback

For strong-delivery scenarios, if users do not receive push within the configured time, SMS fallback can be used.

Recommended scenarios:

• Verification, transaction, account security, and order exception notifications that must reach users.
• Scenarios where the app may be killed, notifications may be disabled, the device may be disconnected, or the user may be offline for a long time.
• Scenarios where push is preferred for cost reasons, but final delivery is still required after push failure.

Configuration recommendations:

• Send push first, then configure the SMS fallback delay time.
• Set the delay according to business urgency. Strong real-time scenarios can use shorter delays; ordinary reminders can use longer delays.
• SMS content must comply with SMS template and signature review requirements.
• Before using SMS fallback, enable SMS service and bind users' mobile numbers.

Custom Message to Vendor Notification

If your business uses custom messages to carry internal protocols, but you still want users to be reminded when the app long connection is offline, use custom-message-to-vendor-notification.

Recommended scenarios:

• IM, to-do, ticket, alert, and similar businesses that originally rely on custom messages.
• The app should process custom messages when online, but users should receive a system notification when offline.
• Android, iOS, and HarmonyOS devices all need higher delivery reach.

Usage recommendations:

• Use the message section for business custom message content.
• Use notification_3rd as the vendor notification fallback content when offline.
• This capability only takes effect for users with enabled vendor channels.
• Keep notification content, click redirection, vendor classification, and offline retention time consistent with the original business message.

Result Tracking and Troubleshooting

Important notifications need a closed loop across sending, delivery, clicks, and non-delivery.

Recommended integrations:

• Push statistics API: view target and success counts by Jiguang channel, Android vendor channel, and other dimensions.
• Message status query: troubleshoot delivery status for a single message across a group of devices.
• Callback API: integrate delivery, click, non-delivery, and push-success callback data.
• Console push records: troubleshoot task configuration, sending status, and vendor return results.

Recommended troubleshooting order:

1. Check whether the client has successfully registered with the Jiguang channel and vendor channels.
2. Check whether the target users, aliases, tags, and registrationIDs match.
3. Check whether message classification, vendor fields, and delivery strategy comply with vendor rules.
4. Check vendor quota, QPS, frequency control, notification permission, and offline retention time.
5. Review push records, statistics APIs, and callback data to identify whether the issue is request failure, vendor failure, non-delivery, or no user click.

Recommended Configuration Checklist

Before sending important notifications, confirm the following:

• The Jiguang channel and target vendor channels are integrated and verified.
• Important-message classification has been applied for according to vendor rules, and fields such as channel_id, importance, and category are configured.
• The API request sets an accurate options.classification.
• time_to_live is configured according to business validity.
• A suitable third_party_channel delivery strategy is selected.
• SMS fallback is configured for strong-delivery scenarios.
• Status-update notifications consider message override, and expired or mistaken notifications consider message recall.
• Push statistics, callbacks, or console troubleshooting flow has been integrated.

Related Documents

• Vendor Channel SDK Integration Guide
• Vendor Quota and QPS Limits
• Vendor Message Classification Usage Guide
• Notification Delivery Strategy
• SMS Fallback Service
• Message Override and Recall
• Push API v3
• Callback API
• Statistics API