Push Notification Service Overview

RC's push notification service is an integral part of its instant messaging solution, supporting various remote push functionalities.

Push Notification Service Capabilities

The primary capabilities of the push notification service include:

Multi-Vendor Adaptation: The push notification service has integrated with Xiaomi Push, Huawei Push, Honor Push, Meizu Push, OPPO Push, vivo Push, and FCM Push, enabling remote push notifications through various vendor channels.
Offline Message Push: When a user is offline, the server can trigger remote push notifications via third-party vendor push channels to deliver notifications to the user's device, ensuring that instant messages are promptly notified even when the app is closed. For more details, see Offline Push Notification.
Push-only Notification: Directly sending remote push notifications to the client via the server API is referred to as push-only notification. Push-only notifications do not contain any conversation messages and will only appear in the system notification bar, regardless of whether the client app is in the foreground. Users cannot view the content of push-only notifications in any chat session. For more details, see Push-only Notification.
Custom Push Notification: Developers can customize the content of push notifications, including the title, icon, and description, to suit different application scenarios.
Multi-Language Adaptation: Supports multi-language push notifications through push templates. The server matches the corresponding language content from the specified push template based on the push language reported by the app user via the client.
Push Notification Statistics and Analysis: RC may provide tools for push notification statistics and analysis, helping developers understand push effectiveness and optimize push strategies.

Offline Push Notification

Assuming a user is logged in on only one device, if the user actively disconnects (disconnect()) or the app is killed by the user or the system, RC considers the user offline on that client. When offline, the user can receive notifications for one-to-one chat messages, group chat messages, system messages, and ultra group messages through third-party push vendors or RC's built-in push service.

If the notification is sent by a third-party push service, it is usually displayed directly by the system in the notification panel, alerting the user of the received message.
If the notification is sent via RC's built-in push channel (RongPush), it is typically constructed by the SDK calling the system API. Note that RongPush is not viable on most domestic devices. It is recommended to integrate third-party push services.

When the user clicks the push notification and re-establishes an IM connection with the RC server, the SDK will behave as follows:

Automatically receive offline messages for one-to-one and group chats^?. The server caches unread offline messages for up to 7 days by default.
Automatically receive the last message in the ultra group conversation during the offline period. The app needs to pull the historical messages from the offline period.

tip

When the app is in the background but active, the user is still considered online, and the SDK can receive conversation messages in real-time. During this process, no push service is used, so the user's device will not receive notifications from any push service. If using IMLib, the app needs to call the system API to create and display local notifications. If using Global IM UIKit, the SDK will call the system API to create and display local notifications by default.

Push-only Notification

RC supports directly sending remote push notifications to the client via the server API, referred to as push-only notification^?. Push-only notifications do not contain any conversation messages and will only appear in the system notification bar, regardless of whether the client app is in the foreground. Users cannot view the content of push-only notifications in any chat session.

Push-only notifications are always delivered through the push channel, thus relying on the app integrating third-party push services or enabling RongPush in the client.

If the notification is sent by a third-party push service, it is usually displayed directly by the system in the notification panel, alerting the user of the received message.
If the notification is sent via RC's built-in push channel (RongPush), it is typically constructed by the SDK calling the system API. Note that RongPush is not viable on most domestic devices. It is recommended to integrate third-party push services.

Push-only notifications can only be sent via the server API, such as:

Currently, push-only notifications cannot be sent via the Console (only some old accounts retain this capability).

Situations Where Push Notifications Are Unavailable or Restricted

Due to the design characteristics of chatroom services, users only receive chatroom messages when they are online. Therefore, chatroom messages do not support offline push notifications.
The client has called the logout method, or has set push notifications to be disallowed during disconnect, or has set the enablePush parameter in the SDK's initialization configuration to false, requesting RC to disable the push service for the current device. In this case, the user cannot receive notifications through any push channel.
Even if all mobile devices of the user are offline, as long as the user is still online on the Web/PC, RC considers the user online and will not send push notifications to mobile devices by default. If needed, you can adjust the Web/PC Online Mobile Push switch in the Console's Basic Features page.
Even if the user's mobile device should receive push notifications, the RC server will not send push notifications to all logged-in mobile devices but only to the last logged-in device.
The frequency and quantity limits of third-party push services have been triggered. To improve the end-user push experience, some third-party push services (e.g., Huawei, vivo) have imposed quantity and frequency controls on push message categories. It is recommended to fully understand the third-party's management rules.
Due to the large volume of messages in ultra groups, to control the frequency of offline push notifications, by default, only one push notification is generated per minute for a single user's single ultra group channel. By default, push notifications are triggered only when two regular messages accumulate. @ messages are not subject to this limit. For adjustments, see Enabling Ultra Group Services.

tip

The user must have successfully connected at least once on the device to receive push notifications.

Push Channel Selection Strategy

When multiple channels are configured in the app, to enhance user experience and improve push delivery rates, the RC client SDK intelligently selects the optimal push channel based on the app's configuration.

The detailed enabling strategy is as follows:

Push Channel	Configuration Requirement	ROM Requirement
Huawei	The app is configured with Huawei Push	The current device is Huawei ROM
Honor	The app is configured with Honor Push	The current device is Honor ROM and was released after November 30, 2023.
OPPO	The app is configured with OPPO Push	The current device is one of the following ROMs: OPPO, realme, OnePlus
vivo	The app is configured with vivo Push	The current device is vivo ROM
Meizu	The app is configured with Meizu Push	The current device is Meizu ROM
FCM	The app is configured with FCM Push	The client's outgoing IP is abroad
RongPush	Default push channel	When other channel enabling strategies are not met and RongPush is available, RongPush is used by default

tip

Additional Notes on FCM

When both native system push and FCM are configured, the specific push channel used depends on the app's configuration order. For example, on a Xiaomi phone with both Xiaomi Push and FCM Push configured, when the user is abroad:

If Xiaomi Push is configured before FCM in the app layer, Xiaomi Push will be used.
If FCM is configured before Xiaomi Push in the app layer, FCM will be used.

Using the Push Notification Service

To use RC's push notification service, the app needs to complete the client push integration steps and configure the ApplicationId and third-party vendor push channel settings in the RC Console.

Configuring ApplicationId in the RC Console

When sending push data to third-party push channels, the RC server requires the app's application identifier^? (Android application ID). You need to configure this in the RC Console.

Access the Push settings page in the RC Console.
1. If you have multiple RC apps, ensure you switch to the correct app in the App dropdown at the top of the page.
2. New apps are created with a default application identifier. You can create more application identifiers, up to 5. Each application identifier can be configured for push, and push configurations are not shared between application identifiers.
Next to the application identifier, click Configure Push, and fill in your Android application ID in the Android > ApplicationId field.

Each Android app has a unique application ID (applicationId), similar to a Java package name, such as com.example.myapp. This ID serves as a unique identifier for your app on devices and in the Google Play Store.

The application ID is defined by the applicationId property in the module's build.gradle file, as shown below:
```
android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}
```
If you have not configured applicationId in build.gradle, the applicationId defaults to the app's package name. For more information on application ID and package name, refer to the Android Official Documentation.

You also need to provide credentials for calling third-party push service APIs and other personalized configurations supported by third-party vendor push channels in the Console. For specific configuration methods, refer to the documentation for integrating each vendor's push service in the client.

Client Integration Solutions

To utilize third-party vendor push capabilities, you must integrate third-party push SDKs into the client.

RC currently supports two client integration solutions:

RC Push 2.0 Integration Solution (Requires IMLib SDK ≧ 5.6.0): RC encapsulates third-party vendor push channel SDKs into plugins, facilitating quick integration and configuration. This solution is suitable for IMLib, Global IM UIKit, or other RC Android client SDKs that depend on IMLib.
RC Push (Legacy) Integration Solution: The app directly integrates the vendor's push client SDK but must meet the version requirements of the RC IM SDK for third-party vendor push SDKs. This solution is more suitable for RC client SDKs that depend on IMLib, Global IM UIKit, or other versions earlier than 5.4.6.

tip

In addition to third-party vendor push services, RC also provides its own push channel (RongPush). RongPush is a stable and reliable long-connection channel maintained between the RC client SDK and the RC push service. It is the default push capability of the SDK and does not require additional third-party libraries. Due to restrictions by domestic phone manufacturers, RongPush is not viable on most domestic devices. It is recommended to integrate third-party push channels simultaneously.

Disabling Push Notifications on the Current Device

The IM SDK enables push notifications by default. To completely disable push notifications on the current device, you can call the logout method when disconnecting, or set the enablePush parameter in the SDK's initialization configuration to false after the first installation, requesting RC to disable the push service for the current device. In this case, the current device will not receive notifications through any push channel.

IMLib

Global Chat UIKit