Custom Message to Vendor Notification Best Practices

Custom messages usually depend on the long connection between the app and JPush. When the app long connection is offline on Android, iOS, or HarmonyOS devices, custom messages cannot be delivered in time. For important custom messages such as IM, to-do, ticket, alert, and order-status messages, you can use the custom-message-to-vendor-notification capability to send a fallback notification through vendor channels when users are offline.

This guide is based on the notification_3rd capability in Push API v3 and helps you design a stable flow where online devices receive custom messages and offline devices receive vendor notifications.

Suitable Scenarios

This capability requires the corresponding vendor channel capability to be enabled. Contact Jiguang business or technical support to confirm permissions.

Core Principles

• message carries business data, while notification_3rd carries the notification content shown to offline users.
• Use v2 for new integrations by setting options.notification_3rd_ver to "v2".
• notification_3rd is effective only for users with vendor channels enabled.
• notification and notification_3rd cannot both contain content. Otherwise, the request returns an error.
• notification_3rd can be passed only when the message section contains content.
• Do not package general marketing content as important custom messages. Follow vendor classification and operational-message frequency control rules.
• The landing page opened from the notification must validate the latest business state, so users do not see incorrect results from expired notifications.

v2 and v1

For new integrations, use v2 to avoid protocol changes when expanding to more platforms later.

Recommended Integration Flow

1. Integrate the JPush SDK on the client and confirm that Registration ID can be obtained.
2. For Android and HarmonyOS, integrate required vendor channels and confirm vendor token callbacks.
3. For iOS, confirm APNs certificate or Token Authentication, Bundle ID, and production/development environment.
4. Define the business message protocol on the server and place it in message.msg_content or message.extras.
5. Define offline notification title, content, click action, and extras in notification_3rd.
6. Set options.notification_3rd_ver="v2" in the API request.
7. Configure options.classification, time_to_live, vendor classification fields, and delivery strategy based on business importance.
8. Verify online and offline device behavior through Push Records, Message Query, Report API, and Callback API.

API Example

The following example shows a to-do reminder. When the app is online, it receives and processes the custom message. When the app long connection is offline, the user is reminded through a vendor notification.

          {
  "platform": "all",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "message": {
    "msg_content": "new_todo",
    "extras": {
      "todo_id": "todo_202607280001",
      "action": "open_todo_detail"
    }
  },
  "notification_3rd": {
    "android": {
      "alert": "You have a new to-do item",
      "title": "To-do reminder",
      "channel_id": "todo_reminder",
      "intent": {
        "url": "intent:#Intent;component=com.example.app/com.example.app.TodoDetailActivity;S.todo_id=todo_202607280001;end"
      },
      "extras": {
        "todo_id": "todo_202607280001"
      }
    },
    "ios": {
      "alert": "You have a new to-do item",
      "sound": "default",
      "badge": "+1",
      "thread-id": "todo",
      "extras": {
        "todo_id": "todo_202607280001"
      }
    },
    "hmos": {
      "alert": "You have a new to-do item",
      "title": "To-do reminder",
      "intent": {
        "url": "scheme://todo/detail?todo_id=todo_202607280001"
      },
      "category": "IM",
      "test_message": false,
      "extras": {
        "todo_id": "todo_202607280001"
      }
    }
  },
  "options": {
    "notification_3rd_ver": "v2",
    "classification": 1,
    "time_to_live": 86400
  }
}

        

The classification, channel, category, and intent values in the example only show field locations. Use values based on your app, vendor approval result, and client page configuration.

Client Design Recommendations

Online Processing

• After receiving a custom message, the client should process it according to the business protocol instead of relying on notification display.
• Use a business ID to deduplicate the same event, such as conversation ID, ticket ID, order ID, or alert ID.
• If an in-app reminder has already been shown while online, still validate the state when the user later opens an offline notification.

Offline Notification Click

• For Android API pushes, configure intent; otherwise, clicking the notification may not open a target page.
• OPPO and FCM channels have special requirements for click parameters. Configure them according to the Android notification click guide.
• For iOS, use extras, thread-id, and related fields to carry business parameters and notification grouping.
• For HarmonyOS, use intent.url and extras to carry jump and business parameters.
• The landing page must query the latest state by business ID. Do not rely only on notification content.

Message Classification and Frequency Control

Custom messages converted to vendor notifications are eventually displayed as notifications, so notification rules still apply:

• User-related messages such as orders, to-dos, tickets, and account security can apply for vendor classification as system or service messages.
• Content recommendations, campaigns, marketing, and platform announcements should be treated as operational messages.
• For Android API pushes, set options.classification first. 1 means system message, and 0 means operational message.
• If the fallback notification is an operational message, configure both JPush frequency control and vendor operational-message policies.
• If the message content is continuously updated, combine Android override_msg_id or iOS apns_collapse_id to reduce duplicate notifications.

Troubleshooting

If the custom message or fallback notification does not behave as expected, troubleshoot in this order:

1. Check whether the Push API returns success and save the msg_id.
2. Check that the request contains only message and notification_3rd, without notification.
3. Check whether options.notification_3rd_ver is set to "v2".
4. Check whether the target device has the vendor channel enabled and registered successfully.
5. Use Device Query to confirm Registration ID, online status, notification permission, and vendor token.
6. Use Message Query to view the lifecycle for Message ID and Registration ID.
7. Check whether click parameters match the client Activity, deeplink, or page route.
8. Use Report API and Callback API to observe delivery, non-delivery, and click data.

Related Documents

• Push API v3 - notification_3rd
• Push API v3
• Notification Delivery Strategy
• Android Notification Click Action
• iOS Notification Click Action
• Vendor Message Classification Guide
• Vendor Quota and QPS Limits
• Push Troubleshooting Best Practices