Vendor Message Classification and Quota Management Best Practices

Android vendor channels generally classify notification messages and apply different reminder styles, total push quotas, per-device receiving limits, and QPS limits to different message types. Properly using message classification and quota strategies can improve the delivery rate of important messages and prevent operation messages from consuming key resources or being restricted by vendors.

This document is for developers using JPush with Xiaomi, Huawei, Honor, OPPO, vivo, Meizu, FCM, ASUS, HarmonyOS, and other channels. It helps you understand message classification, quota deduction, delivery strategies, and troubleshooting.

Core Principles

• Determine the business type first, then choose vendor classification fields. Do not set system-message fields only because you want a higher delivery rate.
• For user-related messages that users need to know in time, apply for important-message classifications according to vendor rules.
• For content recommendations, campaigns, platform announcements, and similar messages, use operation or marketing message classifications and configure frequency control.
• When sending by API, prioritize options.classification to identify the message type and avoid conflicts between vendor fields.
• For vendors such as Xiaomi and OPPO that support skip_quota, do not treat it as a way to bypass vendor limits. It only controls whether Jiguang-side quota judgment and deduction are skipped; vendor limits still apply.
• Before forcing vendor-channel delivery, confirm that the vendor quota is sufficient. Otherwise, a quota-insufficient error may be returned directly.

Classification Quick Reference

Note: This table maps vendor classification concepts for easier understanding. Actual values and application methods must follow vendor official rules, the Jiguang vendor message classification guide, and your app review results.

API Field Priority

options.classification

options.classification is the core field used by Jiguang to adapt Android vendor message classification:

• 0: operation message, default value.
• 1: system message.
• This field has the highest priority and overrides some vendor subfields, such as options.third_party_channel.vivo.classification and options.third_party_channel.honor.importance.
• Jiguang does not judge or calibrate the message type specified by developers. Make sure the value matches the actual business content.

Vendor Subfields

Different vendors may require additional subfields:

• channel_id: notification classification or notification channel identifier for Xiaomi, Huawei, OPPO, and other vendors.
• importance: smart notification classification for Huawei and Honor.
• category: message scenario identifier for Huawei, vivo, OPPO, and other vendors.
• notify_level: OPPO notification reminder level. It usually needs to be used together with category.
• mi_template_id / mi_template_param: Xiaomi private-message template delivery.
• push_mode: vivo formal push or test push identifier.
• skip_quota: currently effective only for Xiaomi and OPPO. It indicates whether Jiguang-side quota judgment and deduction are skipped.

Quota and QPS Management

Jiguang Platform Limits

Non-VIP apps support vendor channels, but each push request has an upper limit on the number of users that can use vendor channels. Requests that exceed the vendor-channel quota do not necessarily mean the message cannot be delivered. Jiguang switches to the Jiguang channel according to device status and available strategies.

If your business has higher requirements for offline delivery rate, real-time delivery, or large-scale push, evaluate VIP service for more stable vendor-channel resources.

Vendor System Limits

Each vendor has its own quota and QPS limits:

• When vendor quota is exceeded, Jiguang tries to deliver through the Jiguang channel.
• When vendor QPS is exceeded, Jiguang slows down delivery according to vendor limits to reduce message loss caused by QPS limits.
• Vendor system limits cannot be bypassed. Even VIP users must follow vendor rules.

Operation Message Limits

Operation messages are usually subject to per-device daily receiving limits. Xiaomi public messages, OPPO public messages, vivo operation messages, and Huawei/Honor information and marketing messages all need to be controlled according to vendor rules.

Recommendations:

• Enable the vendor operation message strategy in the console and configure the per-user daily operation message limit.
• The vendor operation message limit should be less than or equal to Jiguang's per-device push frequency limit.
• For marketing messages, use tags, user properties, segmentation, scheduling, and frequency control instead of occupying important-message classifications.

Recommended Configuration Flow

1. Sort business message types and distinguish important messages from operation messages.
2. Apply for important-message classifications, private-message channels, self-classification permissions, channels, or templates according to vendor requirements.
3. Complete vendor channel SDK integration on the client and ensure that the corresponding notification channel, channel, or category has been created or approved.
4. Configure vendor parameters, vendor operation message strategies, and necessary frequency control rules in the console.
5. When sending by API, set options.classification and add corresponding vendor fields.
6. Select the third_party_channel delivery strategy according to the business goal.
7. Continuously monitor through push records, statistics APIs, callback APIs, and vendor quota queries.

API Example

The following example shows where to configure fields for an important order-status notification. Actual vendor field values must follow your application results.

          {
  "platform": "android",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "android": {
      "alert": "Your order has shipped",
      "title": "Order status update",
      "channel_id": "order_status"
    }
  },
  "options": {
    "classification": 1,
    "third_party_channel": {
      "xiaomi": {
        "distribution": "secondary_push",
        "channel_id": "your_xiaomi_private_channel_id",
        "mi_template_id": "your_xiaomi_template_id",
        "mi_template_param": "{\"order_no\":\"202607280001\"}"
      },
      "huawei": {
        "distribution": "secondary_push",
        "importance": "NORMAL",
        "category": "TRAVEL"
      },
      "honor": {
        "distribution": "secondary_push",
        "importance": "NORMAL"
      },
      "oppo": {
        "distribution": "secondary_push",
        "channel_id": "your_oppo_private_channel_id",
        "category": "ORDER",
        "notify_level": 16
      },
      "vivo": {
        "distribution": "secondary_push",
        "classification": 1,
        "category": "TODO"
      }
    }
  }
}

        

Common Misunderstandings

Misunderstanding 1: Setting All Messages as System Messages

System messages, private messages, and service and communication messages usually have clear scenario boundaries. Setting marketing, campaign, or content recommendation messages as system messages may cause vendor review failures, channel restrictions, or reduced future push stability.

Misunderstanding 2: Passing Only classification Without Applying for Vendor Classification

classification is an important field for Jiguang-side vendor classification adaptation, but some vendors also require channels, self-classification permissions, templates, or categories to be applied for in advance. Without vendor-side configuration, pushes may still fail or be classified as ordinary messages.

Misunderstanding 3: Treating skip_quota as Bypassing Vendor Limits

skip_quota only indicates whether Jiguang-side quota judgment and deduction are skipped, and currently only applies to Xiaomi and OPPO. Vendor quota, QPS, and per-device quantity limits still exist.

Misunderstanding 4: Forcing ospush Without Checking Quota

ospush forces delivery through the vendor channel. If the specified vendor quota is insufficient, the push request may fail with a vendor-quota-insufficient error. For large-scale pushes, query quota first or use a safer delivery strategy.

Misunderstanding 5: Sending Test Messages Without Test Identifiers

Some vendors provide dedicated parameters for test messages. For example, vivo push_mode=1 means test push, while Jiguang test_model means test-mode push to test devices. They have different meanings and should be selected according to the scenario.

Troubleshooting Recommendations

When the delivery rate of important messages is abnormal or vendor errors are returned, troubleshoot in this order:

1. Check whether the vendor channel is integrated successfully and whether the vendor token is obtained normally.
2. Check whether the message content matches the scenario requirements for system messages, private messages, or service messages.
3. Check whether options.classification matches each vendor subfield.
4. Check whether vendor channels, templates, self-classification permissions, and categories have been approved.
5. Check whether vendor quota, per-device daily quantity limits, or QPS limits are triggered.
6. Check whether distribution, distribution_fcm, and distribution_customize match the message type.
7. Review push records, statistics APIs, callback APIs, and vendor backend quota data.

Recommended Configuration Checklist

Before sending, confirm the following:

• Important messages and operation messages have been distinguished.
• Vendor classification application and client notification channel configuration are complete.
• The API request sets an accurate options.classification.
• Vendor fields such as channel_id, importance, category, notify_level, and template fields comply with vendor rules.
• Operation messages have per-user frequency control and vendor operation message strategy configured.
• Vendor quota and QPS are understood before large-scale push.
• Quota is confirmed before forcing vendor-channel delivery.
• Push records, statistics, and callbacks are integrated for continuous troubleshooting.

Related Documents

• Vendor Message Classification Usage Guide
• Vendor Quota and QPS Limits
• Vendor Channel SDK Integration Guide
• Notification Delivery Strategy
• Important Notification High-Delivery Best Practices
• Push API v3
• Callback API
• Statistics API