Understand real-time messages, local notifications, and APNs remote notifications in Chat Server

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 Chat 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 Chat 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 Chat 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 Chat UI, Chat UI 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 Chat SDK, receiving a new message triggers the Chat SDK message listener method (note: Chat SDK 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 Chat 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 Chat SDK/Chat UI 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 Chat 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 Chat SDK message listener method:

- (void)onMessageReceived:(NCMessage *)message
                     left:(int32_t)left
                  offline:(BOOL)offline
               hasPackage:(BOOL)hasPackage {
}

Local notifications

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

Refer to the Chat UI 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 | NC Developer Documentation