Skip to main content

Local Notification

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

What is a Local Notification​

A local notification refers to a notification (Notification) created and sent by Global IM UIKit or the application client directly calling the system interface when the app is running in the foreground or background. Global IM UIKit has already implemented the local notification feature internally. When the app receives a new message in the background, Global IM UIKit will pop up a notification reminder in the notification panel by default, which is a local notification.

tip

The content displayed in the Android notification bar is divided into "local notifications" and "remote notifications." This article only describes the handling of local notifications. If you are unsure how to distinguish between local notifications and remote notifications, please refer to the knowledge base document How to Understand Real-Time Messages, Local Notifications, and Remote Notifications in Instant Messaging Business.

Usage​

Global IM UIKit's local notifications already support the following scenarios:

  • When the app has just entered the background (still in an active state), Global IM UIKit can still receive new messages through the long connection channel (recall messages will also generate recall signal messages). After receiving a new message, Global IM UIKit will create and pop up a notification by default, which is a local notification. Clicking this notification will jump to the conversation page.

    After the app enters an inactive state in the background (e.g., killed by the system), Global IM UIKit will disconnect from the server. If the app has integrated a third-party push service, push notifications can be received at this time. Offline push notifications from third-party vendors are generally created and popped up directly by the push vendor and do not fall under the local notifications described in this article.

  • When the app is in the foreground and no conversation page is open (not chatting with anyone), the default behavior upon receiving a new message is to ring and vibrate, but no notification will pop up. This can be modified to silent or only pop up a notification via setForegroundOtherPageAction.

Setting Local Notification Categories​

Starting from September 15, 2023, Huawei's push service will implement grayscale control over local notifications based on the "Huawei Message Classification Standard." This mainly includes the classification management of local notifications sent by apps and the frequency control of marketing messages. If an app does not apply for Huawei's self-classification rights, all local notifications sent will be treated as marketing messages (limited to 2 or 5 per day).

To avoid local notifications sent by Global IM UIKit directly calling Huawei device system interfaces from failing to pop up, the app should ensure that it has applied for the necessary self-classification rights from Huawei. Starting from version 5.6.4, Global IM UIKit internally sets the category of local notifications to CATEGORY_MESSAGE by default, and the application does not need to call an API for additional settings.

You can modify the default local notification category using the Global IM UIKit global configuration after initialization:

ConfigCenter.getNotificationConfig().setCategoryNotification(Notification.CATEGORY_MESSAGE);

Setting Foreground Local Notification Ringtone and Vibration​

For controlling the ringtone and vibration behavior of local notifications, you can dynamically modify them through the Global IM UIKit global configuration.

/** Whether to vibrate */
ConfigCenter.getNotificationConfig().setVibrateInForeground(true)
/** Whether to have a ringtone */
ConfigCenter.getNotificationConfig().setSoundInForeground(false)

Custom Handling of Local Notifications​

The app can intercept notifications before they are displayed. Global IM UIKit supports intercepting and modifying the Message before continuing to pop up the local notification.

If more custom effects are needed, it is recommended to fully intercept and have the application take over and pop up the local notification itself.

Intercepting Local Notifications​

After setting the interceptor, you can prevent Global IM UIKit from popping up local notifications and handle them customarily as needed.

ConfigCenter.getNotificationConfig().setNotificationInterceptor(new NotificationInterceptor() {
    /**
    * Whether to intercept this local notification, generally used for custom display of local notifications.
    *
    * @param message The message corresponding to the local notification
    * @return Whether to intercept. true intercepts the local notification, and the SDK will not pop up the notification, requiring the user to handle it. false does not intercept, and the SDK will display the local notification.
    */
    @Override
    public boolean isNotificationIntercepted(Message message) {
        ...
        return true; //true, intercept the local notification, and the SDK will no longer handle the local notification logic.
    }

    /**
    * Whether it is a high-priority message. High-priority messages are not controlled by global silent time and conversation Do Not Disturb, such as @ messages.
    *
    * @param message The received message
    * @return Whether it is a high-priority message
    */
    @Override
    public boolean isHighPriorityMessage(Message message) {
        return false;
    }
    /**
     * Callback before registering the default channel. This method can be used to intercept and modify the configuration in the default channel, and return the modified channel.
     *
     * @param defaultChannel The default notification channel
     * @return The modified notification channel.
     */
    @Override
    public NotificationChannel onRegisterChannel(NotificationChannel defaultChannel) {
        return defaultChannel;
    }

    /**
    * Callback when setting the local notification PendingIntent.
    * The application layer can use this method to change the settings in the PendingIntent to customize the click behavior of the local notification.
    * When clicking the local notification, the SDK will jump to the corresponding conversation page by default.
    * @param pendingIntent The SDK's default PendingIntent
    * @param intent        The intent carried in the pendingIntent.
    *                      The following information can be obtained through the intent:
    *                      intent.getStringExtra(RouteUtils.CONVERSATION_TYPE);
    *                      intent.getStringExtra(RouteUtils.TARGET_ID);
    *                      intent.getIntExtra(RouteUtils.MESSAGE_ID, -1);;
    * @return The PendingIntent that needs to be configured in the local notification.
    */
    @Override
    public PendingIntent onPendingIntent(PendingIntent pendingIntent, Intent intent) {
        Intent intentNew = new Intent(getApplicationContext(), MainActivity.class); //Custom jump to the conversation list
        PendingIntent pendingIntent1 = PendingIntent.getActivity(getApplicationContext(), 1, intentNew, PendingIntent.FLAG_UPDATE_CURRENT);
        return pendingIntent1;
    }

});

Customizing Local Notification Click Events​

When clicking a local notification, Global IM UIKit will jump to the corresponding conversation page by default. You can customize the jump event when clicking. Use it in the onPendingIntent callback of the notification interception mentioned above.

@Override
public PendingIntent onPendingIntent(PendingIntent pendingIntent, Intent intent) {
    Intent intentNew = new Intent(getApplicationContext(), MainActivity.class); //Custom jump to the conversation list
    PendingIntent pendingIntent1 = PendingIntent.getActivity(getApplicationContext(), 1, intentNew, PendingIntent.FLAG_UPDATE_CURRENT);
    return pendingIntent1;
}
Last updated on