Custom Push Notification Click Events

This article describes the default behavior of IMLib and IMKit when handling user clicks on remote notifications, and how applications can customize the handling of remote push notification click events.

tip

This article only covers the handling of remote push notification click events. If you need to handle click events for IMKit's local notifications, please refer to Local Notification Click Event Handling. If you're unsure how to distinguish between local notifications and remote pushes, read the knowledge base article Understanding Real-time Messages, Local Notifications and Remote Push in IM Services (Android).

Implementing SDK Default Navigation Behavior

IMLib and IMKit handle remote push notification click events by default. When users click a notification, the SDK sends a corresponding implicit Intent. You need to configure an Intent-filter in your app's manifest file (AndroidManifest.xml) to receive the Intent and complete the default navigation action.

• Notification from a single contact: When users click one or multiple notifications from a single contact, the SDK by default navigates to the conversation Activity.
• Collapsed notifications from multiple contacts: When multiple contacts send multiple notifications, these notifications are displayed collapsed. When users click notifications from multiple contacts, the SDK by default navigates to the conversation list Activity.
• Push-only Notifications: When users click Push-only Notifications, the SDK also sends an implicit Intent. You can decide which Activity should receive this Intent.
• We recommend uniformly navigating to the conversation list page and calling RC's connection method before opening the conversation list page to ensure the latest pushed messages are visible when the page opens.

Navigating to the Corresponding Conversation Page

When users click one or multiple notifications from a single contact, the SDK by default sends an Intent to navigate to the conversation Activity.

Configure the following intent-filter in the conversation Activity in AndroidManifest.xml to navigate to the conversation Activity. If you've customized the conversation Activity, replace RongConversationActivity with your custom Activity's class name.

<activity
android:name="RongConversationActivity"
android:exported="true">
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <data
        android:host="${applicationId}"
        android:pathPrefix="/conversation"
        android:scheme="rong" />
</intent-filter>
</activity>

Navigating to the Conversation List Page

When multiple contacts send multiple notifications, these notifications are displayed collapsed. When users click notifications from multiple contacts, the SDK by default sends an Intent to navigate to the conversation list Activity.

Configure the following intent-filter in the conversation list Activity in AndroidManifest.xml to navigate to the current Activity. If you've customized the conversation list Activity, replace RongConversationListActivity with your custom Activity's class name.

<activity
android:name="RongConversationListActivity"
android:exported="true">
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <data
        android:host="${applicationId}"
        android:pathPrefix="/conversationlist"
        android:scheme="rong" />
</intent-filter>
</activity>

Handling Push-only Notification Click Navigation

Push-only Notifications initiated through RC are displayed independently. When users click Push-only Notifications, the SDK by default sends an Intent.

Configure the following in AndroidManifest.xml to navigate to your specified Activity.

<activity
android:name="CustomActivity"
android:exported="true"
android:launchMode="singleTask"
android:screenOrientation="portrait">

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />

    <data
        android:host="${applicationId}"
        android:pathPrefix="/push_message"
        android:scheme="rong" />
</intent-filter>
</activity>

Customizing Notification Click Navigation Behavior

If the default navigation behavior doesn't meet your requirements, you can modify the push notification click behavior through either of the following methods:

• Set PushEventListener and override the onNotificationMessageClicked method (recommended).
• Extend PushMessageReceiver and override the onNotificationMessageClicked method.

Setting PushEventListener

tip

• Starting from development version 5.2.1, all push types support using PushEventListener to customize notification click behavior.
• Starting from stable version 5.1.9.2, all push types support using PushEventListener to customize notification click behavior.
• Due to Android 12's notification trampoline restrictions, when your app's targetVersion ≥ 31, we recommend directly launching the Activity in the RongPushClient.setPushEventListener callback. Avoid using broadcasts or services for message distribution before launching the Activity.

You can set PushEventListener in the Application's onCreate method, override the onNotificationMessageClicked method to listen for and intercept push notification click events.

RongPushClient.setPushEventListener(
                new PushEventListener() {
                    @Override
                    public boolean preNotificationMessageArrived(
                            Context context,
                            PushType pushType,
                            PushNotificationMessage notificationMessage) {
                        // This callback only takes effect for passthrough messages. Return true to intercept, false to not intercept
                        return false;
                    }

                    @Override
                    public void afterNotificationMessageArrived(
                            Context context,
                            PushType pushType,
                            PushNotificationMessage notificationMessage) {
                        // This callback only takes effect for passthrough messages
                    }

                    @Override
                    public boolean onNotificationMessageClicked(
                            Context context,
                            PushType pushType,
                            PushNotificationMessage notificationMessage) {
                        // Users can define their own notification click event logic here. Return true to intercept, false to not intercept
                        return false;
                    }

                    @Override
                    public void onThirdPartyPushState(
                            PushType pushType, String action, long resultCode) {}
                });

Using PushMessageReceiver

You can also customize click events through the onNotificationMessageClicked method of PushMessageReceiver. This method has lower priority than PushEventListener.

tip

• Huawei and Oppo push click events cannot be customized through the PushMessageReceiver method.
• Due to Android 12's notification trampoline restrictions, when your app's targetVersion ≥ 31, we recommend directly launching the Activity in the PushMessageReceiver callback. Avoid using broadcasts or services for message distribution before launching the Activity.

1. Create CustomPushMessageReceiver by extending the PushMessageReceiver class.

   class CustomPushMessageReceiver extends PushMessageReceiver {
       ...
   }
   

2. Register the push broadcast receiver component in the main project's AndroidManifest.xml. Note to replace any existing PushMessageReceiver registration in AndroidManifest.xml.

     <receiver
               android:name="xxx.CustomPushMessageReceiver"
               android:exported="true">
               <intent-filter>
                   <action android:name="io.rong.push.intent.MESSAGE_ARRIVED" />
                   <action android:name="io.rong.push.intent.MESSAGE_CLICKED" />
                   <action android:name="io.rong.push.intent.THIRD_PARTY_PUSH_STATE" />
               </intent-filter>
           </receiver>

3. After registering the broadcast, override the onNotificationMessageClicked method in your CustomPushMessageReceiver class. Implement interception logic here and then handle the redirection.

   Parameter Description

   Parameter	Type	Required	Description
   context	Context	Yes	Context object
   pushType	PushType	Yes	Push type
   notificationMessage	PushNotificationMessage	Yes	Push message

   class CustomPushMessageReceiver extends PushMessageReceiver {
       @Override
       public boolean onNotificationMessageClicked(Context context, PushType pushType, PushNotificationMessage notificationMessage) {
           // Use pushType to determine the push platform
           // Huawei and Oppo push click events won't trigger this callback - handle them in respective activities by parsing intents
   
           if (pushType == PushType.XIAOMI) {
               // Implement your custom notification click handling
               return true; // Return true to indicate custom handling (SDK default won't execute)
           } else if (pushType == PushType.MEIZU) {
               // Implement your custom notification click handling
               return true;
           } else if (pushType == PushType.VIVO) {
               // Implement your custom notification click handling
               return true;
           } else if (pushType == PushType.GOOGLE_FCM) {
               // Implement your custom notification click handling
               return true;
           } else if (pushType == PushType.RONG) {
               // Implement your custom notification click handling
               return true;
           }
           return false;
       }
   }