Skip to main content

Push Notification Service Overview

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

Push Service Capabilities​

The primary capabilities of the push service include:

  1. Multi-vendor Adaptation: The push service integrates with Xiaomi Push, Huawei Push, Honor Push, Meizu Push, OPPO Push, vivo Push, and FCM Push, enabling remote push notifications through various vendor channels.
  2. Offline Message Push: When users are offline, the server can trigger remote push notifications via third-party vendor channels to deliver alerts to user devices, ensuring IM messages reach users even when the app is closed. See Offline Push Notifications for details.
  3. Push-only Notification: Direct server-to-client remote push notifications without message content, called Push-only Notifications. These notifications never appear in chat sessions and are always displayed in the system notification panel, regardless of whether the app is in the foreground. See Push-only Notification for details.
  4. Custom Push Notifications: Developers can customize push notification content, including titles, icons, and descriptions, to suit different application scenarios.
  5. Multi-language Support: Supports multi-language push notifications through templates. The server matches push content to the user's reported language preference from specified templates.
  6. Push Analytics: RongCloud provides push notification statistics and analysis tools to help developers optimize push strategies.

Offline Push Notifications​

When a user is only logged in on one device and either disconnects actively (disconnect()) or has the app terminated by the system/user, RongCloud considers the client offline. In this state, one-to-one messages, group messages, system messages, and ultra group messages can be delivered via third-party push services or RongCloud's built-in push service.

  • Third-party push services typically display system-level notifications in the notification panel.
  • RongPush (RongCloud's native push) constructs notifications via system APIs. Note: RongPush has limited survival rates on most Chinese devices. Third-party push integration is recommended.

After reconnecting to RongCloud servers by clicking a push notification, the SDK will:

  • Automatically receive offline one-to-one and group messages? (cached for 7 days by default).
  • Receive the last ultra group message, requiring apps to manually fetch historical messages.
tip

When apps are backgrounded but active, users remain online and receive messages in real-time without push notifications. IMLib requires manual local notification creation, while IMKit handles this automatically.

Push-only Notification​

RongCloud supports direct server-to-client remote push notifications without message content (Push-only Notifications?). These always appear in the system notification panel and never in chat sessions.

Push-only Notifications require either third-party push integration or RongPush activation:

  • Third-party services display system notifications directly.
  • RongPush constructs notifications via system APIs (limited reliability in China).

Supported server APIs:

Console-based Push-only Notifications are deprecated (only available for legacy accounts).

Push Limitations​

  1. Chatroom messages don't support offline pushes due to their online-only design.
  2. Users who call logout, disable pushes during disconnect, or set enablePush=false won't receive any notifications.
  3. Mobile devices won't receive pushes if users are online via Web/PC (configurable in Console).
  4. Only the last logged-in mobile device receives push notifications.
  5. Third-party push rate limits may apply (e.g., Huawei/vivo frequency controls).
  6. Ultra groups limit pushes to 1 per channel per user per minute (2+ messages trigger pushes; @mentions exempt).
tip

Devices must successfully connect at least once to receive pushes.

Push Channel Selection Strategy​

When multiple channels are configured, RongCloud SDK intelligently selects the optimal push channel based on device conditions:

ChannelConfiguration RequirementROM Requirement
HuaweiHuawei Push configuredHuawei ROM
HonorHonor Push configuredHonor ROM (devices released after Nov 30, 2023)
OPPOOPPO Push configuredOPPO/realme/OnePlus ROM
vivovivo Push configuredvivo ROM
MeizuMeizu Push configuredMeizu ROM
FCMFCM Push configuredOverseas IP
RongPushDefaultFallback when other channels are unavailable
tip

FCM vs. Native Push: When both are configured, the first-configured channel takes priority (e.g., Xiaomi Push before FCM on Xiaomi devices abroad uses Xiaomi Push).

Using Push Services​

To enable push services, apps must complete client-side integration and configure ApplicationId + vendor-specific settings in RongCloud Console.

Configuring ApplicationId in Console​

RongCloud servers require Android Application IDs when sending push data to third-party channels. Configure this in Console:

  1. Navigate to Application Identifier page (under IM Service > Service Management):

    • Switch to the correct app if managing multiple.
    • Each app supports up to 5 identifiers (push configurations aren't shared between them).

  2. Click Configure Push next to an identifier and enter your Android Application ID under Android > ApplicationId.

    Application IDs (e.g., com.example.myapp) uniquely identify apps on devices and Google Play. Defined in build.gradle:

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

    Unconfigured applicationId defaults to the package name. See Android docs for details.

Additional third-party push credentials and configurations are required. Refer to vendor-specific integration guides.

Client Integration Solutions​

Third-party push SDK integration is mandatory. RongCloud offers two approaches:

  • Push 2.0 Integration (requires IMLib ≥5.6.0): RongCloud's pre-packaged vendor push plugins for streamlined integration (IMLib/IMKit compatible).
  • Legacy Push Integration: Direct vendor SDK integration with version requirements. For IMLib/IMKit versions below 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 RC client SDKs and RC push services. As a default push capability of the SDK, it provides basic push functionality without requiring additional third-party library integration. Due to restrictions imposed by Chinese smartphone manufacturers, RongPush cannot maintain persistent connections on most domestic device models. We recommend integrating third-party push channels simultaneously.

Disabling Push Notifications for Current Device​

The IM SDK enables push notifications by default. To completely disable push notifications on the current device, you can either:

  1. Call the logout method when disconnecting, or
  2. Set the enablePush parameter to false in the SDK initialization configuration after first installation

This will request RC services to disable push notifications (for the current device) and completely deregister the user's login information from RC servers. In this case, the current device won't receive any notifications through any push channel.

Last updated on