Understand real-time messages, local notifications, and APNs remote notifications in IM services

Technical guides
,
1

Not all notifications in the client’s notification bar are remote notifications. This article explains the relationship between IM connection status, app alive status, local notifications, and remote notifications.

IM connection status between SDK and RC server

To distinguish between real-time messages and remote notifications, first understand IM connection states:

  • Connected: After the app calls the SDK’s connection method, the SDK establishes a long connection with the RC server for sending and receiving messages—this is the IM connection channel. When the SDK receives a message through this channel, it triggers the message listener method.

  • Disconnected: If the IM connection channel is down, real-time messages can’t reach the user’s device via the IM long connection. In this case, new messages rely on Apple’s push notification service (APNs) to notify the device.

    The IM connection channel may disconnect due to:

    • The app’s main process being killed or reclaimed.
    • The app actively calls the SDK’s disconnect method.
    • The connection method isn’t called, or the IM connection isn’t established properly.
    • The current logged-in user is banned.
    • The user’s Token expires or is invalidated.
    • The user logs in on another device, causing them to be logged out on the current device (affected by the App Key’s multi-device login restrictions).

App states

To understand the scope of real-time messages, local notifications, and remote notifications, distinguish between iOS app states: foreground, background active, and background suspended.

  1. Foreground status: The app is running in the foreground (assuming the SDK has established a proper IM connection with the RC server), and the user is actively using the app.

  2. Background active status: When the app moves to the background, the system may restrict network access or process execution, causing the connection to break. However, the timing of this disconnection varies by system. If the IM connection remains after moving to the background, the app can receive real-time messages through the IM connection. If the app integrates the IMKit SDK, IMKit will handle displaying a notification in the notification bar upon receiving a new message—this is called a “local notification.” If the app integrates the IMLib SDK, receiving a new message triggers the IMLib message listener method (note: IMLib doesn’t implement local notifications in this scenario).

  3. Background suspended state: After being in the background for over 2 minutes, the app enters the suspended state. The SDK actively disconnects the IM connection, and the app loses its IM connection with the RC server. When the IM connection channel is down, new messages rely on Apple’s APNs remote notification service to notify the device. APNs notifications are displayed directly in the notification bar via the iOS system and don’t depend on IMLib/IMKit implementation.

In the latter two states, if the app returns to the foreground and re-establishes the IM connection, the SDK can retrieve messages from the RC server.

Real-time messages in IM

Whether the app is in the foreground or background, if a message is received through the IM connection, the SDK always triggers the message listener callback method.

Here’s an example of the IMKit message listener method:

/**  
 Callback method for receiving messages  

 @param message The currently received message  
 @param nLeft The number of remaining unread messages, left>=0  
 @param offline Whether it’s an offline message  
 @param hasPackage The SDK pulls messages from the server in batches (packages). The existence of a package means there are still messages on the remote server that haven’t been pulled by the SDK.  
 */  
- (void)onRCIMReceived:(RCMessage *)message  
                  left:(int)nLeft  
               offline:(BOOL)offline  
            hasPackage:(BOOL)hasPackage;

Local notifications

Local notifications are created and sent directly by IMKit or the app client using system APIs when the app is running in the foreground or background. The IMKit SDK has built-in local notification functionality. When the app is in the background and receives a new message, IMKit will display a notification in the notification panel by default, this is a local notification.

Refer to the IMKit 5.X developer documentation: Local notifications

Remote notifications

After integrating a third-party push service, the app can receive notifications of new messages through the vendor’s push channel when the IM connection channel is down.

Refer to the developer documentation: Integrate APNs Remote Notifications | RC Developer Documentation