Push notifications overview

The push notification service is part of the instant messaging solution and supports a variety of remote push notification capabilities.

Push service capabilities

The key capabilities of the push notification service include:

1. Multi-vendor support: The push service integrates with Huawei Push and FCM Push, and supports triggering remote push notifications through each channel.
2. Offline message push: When a user is offline, the server can trigger remote push notifications and deliver them to the user's device through third-party vendor push channels — ensuring that IM messages reach the user even when the app is closed. See Offline Message Push Notifications below.
3. Customizable push notifications: Developers can customize push notification content, including the title, icon, and description, to suit different use cases.
4. Multi-language support: Push template functionality enables multilingual push notifications. The server matches push content in the appropriate language from a specified push template based on the push language reported by the client on behalf of the app user.
5. Push notification analytics: Provides statistics and analytics tools for push notifications to help developers understand push performance and optimize push strategies.

Offline message push notifications

Assume a user is logged in on a single device. If the user actively disconnects (disconnect()) or the application is killed by the user or the system, the server considers the user offline on that client. While offline, the server can notify the client of received one-to-one messages, group messages, system messages, and community channel messages through configured third-party vendor push channels.

• If a third-party vendor push service delivers the notification, the OS typically pops it up directly as a system notification in the notification panel, alerting the user to the new message.

After the user clicks a push notification and re-establishes the IM connection with the server, the SDK behaves as follows:

• Automatically receives offline one-to-one and group messages^? accumulated during the offline period. The server caches unread offline messages for 7 days by default.
• Automatically receives the last message in each Community Channel from the offline period; the application must fetch the full message history for the offline period itself.

tip

When the application is in the background but still active, the user remains online, the SDK continues to receive channel messages in real time, and no push service is used during message delivery — so the user's device will not receive any push notifications. By default, the SDK calls the system API to create and display a local notification; if you need to customize this behavior, the application can call the system API directly to create and display a local notification.

Situations where push notifications are not sent or are restricted

• Due to the nature of open channel functionality, open channel messages are only received while the user is online in the open channel. Therefore, open channel messages do not support offline push notifications.
• If the client calls NCEngine.disconnect(disablePush = true) to fully log out and disable push, or sets the enablePush initialization parameter to false to request that the server disable push for the current device, the user's login state is fully deregistered on the server. In this case, the user cannot receive notifications through any push channel.
• Even if all of a user's mobile devices are offline, as long as the user is still active on the Web or PC client, the server considers the user online and does not send push notifications to mobile devices by default. If needed, you can toggle Send to mobiles when web/PC online under Chat > Chat settings > Offline Push on the console's Chat settings page.
• Even when a user's mobile device should receive a push notification, the server does not send push notifications to all devices the user has ever logged in on — only to the most recently logged-in device.
• Third-party vendor push services have rate and volume limits. To improve the end-user push experience, some push services (such as Huawei) impose volume and frequency restrictions on push message categories. Familiarize yourself with the specific rules of third-party providers.
• Because community channels can have a high volume of ordinary messages, the default behavior limits push frequency: at most 1 push notification per user per community channel per minute. Ordinary messages only trigger a push after 2 accumulate. @ mentions are exempt from this limit.

tip

A user must successfully connect on a device at least once before that device can receive push notifications.

Push channel selection strategy

When multiple third-party vendor channels are configured, the client SDK intelligently selects the optimal push channel based on the app configuration to improve delivery rates and user experience.

The selection strategy is as follows:

Push Channel	Configuration Requirement	ROM Requirement
Huawei	App has configured Huawei push	Current device runs Huawei ROM
FCM	App has configured FCM push	Client's outbound IP is outside China

tip

Additional note about FCM

When both Huawei push and FCM are configured, the specific channel used depends on the configuration order in the application layer and the device's network environment.

Using the push service

To use the push notification service, your application must complete the client-side push integration steps and configure the ApplicationId and third-party vendor push channel settings in the console.

Configure the ApplicationId in the console

When the server sends push data to a third-party push channel, it needs the app's application identifier^? (Android application ID). You must configure this in the console.

1. Go to the console's Application Identifier page.

   1. If you have multiple apps, make sure you select the correct app from the App dropdown at the top of the page.
   2. A newly created app comes with one application identifier by default. You can create up to 5. Each identifier can have its own push configuration; push settings are not shared between identifiers.

2. Next to the application identifier, click Set Push, then fill in your Android application ID under Android > ApplicationId.

   Every Android app has a unique application ID (applicationId), similar to a Java package name — for example, com.example.myapp. This ID uniquely identifies your app on the device and in the Google Play Store.

   The application ID is defined by the applicationId property in the module's build.gradle file:

   Groovy

   android {
       defaultConfig {
           applicationId "com.example.myapp"
           minSdkVersion 21
           targetSdkVersion 24
           versionCode 1
           versionName "1.0"
       }
       ...
   }

   If you have not configured applicationId in build.gradle, it defaults to the app's package name. For more information about the relationship between application ID and package name, see the Android Developer documentation.

You also need to provide the credentials for calling the third-party push service API, as well as any additional vendor-specific configurations supported by the push channel. For details, refer to the push integration documentation for each vendor.

Client integration options

To use third-party vendor push capabilities, you must integrate the third-party push SDK on the client side.

Two client integration options are available:

• Push 2.0 integration: Wraps third-party vendor push channel SDKs as plugins for fast integration and configuration. Applicable to the Android client SDK.
• Legacy push integration: The application integrates the vendor's push client SDK directly. The SDK version must meet the requirements specified by the IM SDK.

Disable push on the current device

Push is enabled in the SDK by default. To completely disable push on the current device, call NCEngine.disconnect(disablePush = true) when disconnecting, or set the enablePush initialization parameter to false on first install to request that the server disable push for the current device and fully deregister the user's login state. Once disabled, the current device cannot receive notifications through any push channel.

kotlin

// Disconnect while keeping push enabled (default)
NCEngine.disconnect()

// Disconnect and disable push (full logout)
NCEngine.disconnect(disablePush = true)

Java

// Disconnect while keeping push enabled (default)
NCEngine.disconnect();

// Disconnect and disable push (full logout)
NCEngine.disconnect(true);