Skip to main content

Local Notification

Global IM UIKit has implemented the creation and display behavior of local notifications, making it easier for developers to quickly build applications.

What is Local Notification​

Local notification refers to notifications created and sent directly by Global IM UIKit or the application client by calling system interfaces when the app is running in the foreground or background.

tip

The content displayed in the iOS notification bar is divided into "local notification" and "remote push notification". This article only describes the handling of local notifications. If you are not sure how to distinguish between local notification and remote push notification, you can read the knowledge base document Understanding Real-Time Messages, Local Notifications, and APNs Remote Push Notifications in Instant Messaging.

Usage​

Global IM UIKit's local notification already supports the following scenarios:

  • When the app is in the foreground and no chat UI is open (not chatting with anyone), the default behavior is to ring but not display a notification upon receiving a new message.

  • When the app just enters the background (still in an active background state): After the app enters the background, the SDK's long connection can survive for up to 2 minutes, after which it will actively disconnect. Within 2 minutes of entering the background, Global IM UIKit can still receive new messages through the long connection channel (recall messages will also generate recall signaling messages). Upon receiving a new message, Global IM UIKit will by default create and display a notification, i.e., a local notification.

    After the app enters an inactive state in the background (e.g., killed by the system), Global IM UIKit disconnects from the server. If the app has integrated APNs push service, push notifications can be received at this time. Push notifications are created and displayed directly by the system and do not fall under the local notifications described in this article.

When displaying a local notification in the notification bar, Global IM UIKit needs to show user or group information in the notification title. This information must be provided to Global IM UIKit by the application through the implementation of a user information proxy.

For details on how to implement the user information proxy, see User Information.

Important

If Global IM UIKit cannot obtain user or group information when it needs to display a local notification, the message will not trigger a local notification.

Customization​

Disable Foreground Notification Sound​

When the app is in the foreground, the message alert sound is played by default. You can disable all foreground message alert sounds by setting the global configuration property enableMessageAlertSound to NO.

RCIMKitConfig.shared.enableMessageAlertSound = NO;

Disable Background Local Notification​

When the app is in the background and the connection is maintained, local notifications are sent by default. You can disable all background message local notifications by setting the global configuration property enableMessageLocalNotification to NO.

RCIMKitConfig.shared.enableMessageLocalNotification = NO;

Handling Local Notification Events​

Before triggering a message sound or local notification, Global IM UIKit will check whether it needs to be executed through a callback method. Developers can implement the message local notification delegate method, which will carry the newly received message. If you need to handle the message yourself, return NO, and the SDK will no longer play the sound or display the default local notification prompt for this message.

@protocol RCLocalNotificationDelegate <NSObject>

/// Whether to send a local notification for a new message
/// When a new message is received, if the new message triggers a local notification, this method will be called first
/// - Parameter message: The newly received message
- (BOOL)shouldPostLocalNotificationForMessage:(RCMessage *)message;

/// Whether to play a sound for a new message
/// When a new message is received, if the new message triggers a sound, this method will be called first
/// - Parameter message: The newly received message
- (BOOL)shouldPlaySoundForMessage:(RCMessage *)message;

@end
Last updated on