Message and notification handling API (4.x)

Updated at:

This document describes how to use Android SDK 4.x to receive messages, handle notification arrival, click, and removal events, and selectively intercept notification displays.

Note

This document applies to Mobile Push Android SDK 4.x. The interfaces and examples are based on the released version 4.0.0. For applications using SDK 3.x, refer to the corresponding 3.x API documentation.

Choose a callback method

Important

In Android SDK 4.x, the callback functionality of MessageReceiver and AliyunMessageIntentService is as follows:

  • ACCS proprietary channel and FCM: Full business callbacks are supported, including receiving messages (onMessage), notification arrivals (onNotification), notification clicks (onNotificationOpened), and notification removals (onNotificationRemoved).

  • Other Android vendor channels (excluding FCM): Only onNotificationOpened (notification click) is supported. Other callbacks, such as receiving messages, notification arrivals, and notification removals, are not triggered.

MessageReceiver and AliyunMessageIntentService provide the same business callbacks, so you can choose either one. By default, MessageReceiver is used. After you call setPushIntentService, the SDK dispatches events to the specified service instead of MessageReceiver.

Callback

Applicable scope

onMessage

Triggered by a passthrough message from the ACCS proprietary channel or FCM.

onNotification

Triggered by a notification from the ACCS proprietary channel or FCM. Your application can also use this callback to intercept the notification display.

onNotificationOpened

Triggered when a user clicks an SDK-displayed notification or a system notification from a vendor channel that has a correctly configured auxiliary pop-up window.

onNotificationRemoved

Triggered when a notification from the ACCS proprietary channel or the FCM channel is removed. Other Android vendor channels only provide the onNotificationOpened callback for clicks.

First, complete the SDK initialization and registration. The FCM adapter forwards the payload from data messages to the Mobile Push SDK for processing. For system notification clicks from vendors such as Xiaomi, Huawei, Honor, OPPO, vivo, and Meizu, you must still correctly configure the intermediate Activity and server-side auxiliary pop-up window parameters. In SDK 4.x, click handling is unified in onNotificationOpened, which replaces onSysNoticeOpened.

The following callback examples are written in a class that extends MessageReceiver or AliyunMessageIntentService. You must also implement other required callbacks. The SDK passes the callback parameters. In the parameter tables, "No" in the "Required" column means the value can be null, so you must perform a null check before using it.

Method 1: MessageReceiver

Extend MessageReceiver and implement the four business callbacks. Replace the class name with your application's actual class name. The Kotlin example performs null checks for nullable data.

import android.content.Context;
import com.alibaba.sdk.android.push.MessageReceiver;
import com.alibaba.sdk.android.push.notification.CPushMessage;
import java.util.Map;

public class MyMessageReceiver extends MessageReceiver {
    @Override
    public void onMessage(Context context, CPushMessage message) {
        // Passthrough message from the SDK. Not automatically displayed as a notification.
    }
    @Override
    public void onNotification(Context context, String title, String summary,
                               Map<String, String> extraMap) {
        // Notification arrival from the SDK, regardless of whether the app displays it.
    }
    @Override
    public void onNotificationOpened(Context context, String title, String summary,
                                     Map<String, String> extraMap) {
        // Handles clicks on both SDK-displayed and correctly integrated vendor system notifications.
        // You can get extra parameters from extraMap. Perform a null check before use.
    }
    @Override
    public void onNotificationRemoved(Context context, String messageId) {
        // An SDK-displayed notification was removed. messageId is the message ID.
    }
}
import android.content.Context
import com.alibaba.sdk.android.push.MessageReceiver
import com.alibaba.sdk.android.push.notification.CPushMessage

class MyMessageReceiver : MessageReceiver() {
    override fun onMessage(context: Context, message: CPushMessage) {
        // Handles passthrough messages from the SDK.
    }
    override fun onNotification(
        context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
    ) {
        // Handles notification arrivals from the SDK.
    }
    override fun onNotificationOpened(
        context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
    ) {
        // Handles all notification clicks. Get extra parameters from extraMap.
    }
    override fun onNotificationRemoved(context: Context, messageId: String?) {
        // Handles notification removals.
    }
}

Register the receiver within the application node of your AndroidManifest.xml file. The example .MyMessageReceiver must be replaced with the fully qualified or resolvable relative class name used in your application.

<receiver
    android:name=".MyMessageReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
        <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
        <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
    </intent-filter>
</receiver>

For network requests or other long-running operations within the onReceive callback, delegate them to an asynchronous task in your application.

Method 2: AliyunMessageIntentService

Extend the SDK's AliyunMessageIntentService to receive callbacks as a service. Delegate long-running operations in the callbacks to asynchronous tasks. For UI operations, switch to the main thread.

import android.content.Context;
import com.alibaba.sdk.android.push.AliyunMessageIntentService;
import com.alibaba.sdk.android.push.notification.CPushMessage;
import java.util.Map;

public class MyMessageIntentService extends AliyunMessageIntentService {
    @Override
    public void onMessage(Context context, CPushMessage message) {
        // Passthrough message from the SDK. Not automatically displayed as a notification.
    }
    @Override
    public void onNotification(Context context, String title, String summary,
                               Map<String, String> extraMap) {
        // Notification arrival from the SDK, regardless of whether the app displays it.
    }
    @Override
    public void onNotificationOpened(Context context, String title, String summary,
                                     Map<String, String> extraMap) {
        // Handles clicks on both SDK-displayed and correctly integrated vendor system notifications.
        // You can get extra parameters from extraMap. Perform a null check before use.
    }
    @Override
    public void onNotificationRemoved(Context context, String messageId) {
        // An SDK-displayed notification was removed. messageId is the message ID.
    }
}
import android.content.Context
import com.alibaba.sdk.android.push.AliyunMessageIntentService
import com.alibaba.sdk.android.push.notification.CPushMessage

class MyMessageIntentService : AliyunMessageIntentService() {
    override fun onMessage(context: Context, message: CPushMessage) {
        // Handles passthrough messages from the SDK.
    }
    override fun onNotification(
        context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
    ) {
        // Handles notification arrivals from the SDK.
    }
    override fun onNotificationOpened(
        context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
    ) {
        // Handles all notification clicks. Get extra parameters from extraMap.
    }
    override fun onNotificationRemoved(context: Context, messageId: String?) {
        // Handles notification removals.
    }
}

Register the service within the application node of your AndroidManifest.xml file.

<service
    android:name=".MyMessageIntentService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
        <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
        <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
    </intent-filter>
</service>

setPushIntentService: Specify message handling service

Specify a service class that extends AliyunMessageIntentService to receive message and notification events from the SDK.

Method signature

void setPushIntentService(Class intentService);

Parameters

Parameter

Type

Required

Description

intentService

Class

No

The service class that extends AliyunMessageIntentService and is registered in AndroidManifest.xml. Pass null to revert to dispatching events through MessageReceiver.

Return value: None (void). This method does not perform push registration or provide a result callback.

Call this method as early as possible in Application.onCreate() after init(), and before calling register(). This configuration must be reapplied each time the application starts.

Code example

PushServiceFactory.getCloudPushService()
        .setPushIntentService(MyMessageIntentService.class);
PushServiceFactory.getCloudPushService()
    .setPushIntentService(MyMessageIntentService::class.java)

Passthrough message callback

void onMessage(Context context, CPushMessage message);

The SDK passes the passthrough message to your application for processing and does not automatically display a notification. context is the component context, and message contains the message data.

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The component context the SDK uses to dispatch events. For UI operations, use a valid Activity context.

message

CPushMessage

Yes

The passthrough message object delivered in this callback. The message in the code examples refers to this parameter.

Return value: None (void). The application processes the message content. This callback does not automatically create a notification.

Code example

@Override
public void onMessage(Context context, CPushMessage message) {
    String content = message.getContent();
    if (content != null) {
        // Parse the message content according to your application's protocol.
        // Delegate long-running operations to an asynchronous task.
    }
}
override fun onMessage(context: Context, message: CPushMessage) {
    val content = message.content
    if (content != null) {
        // Parse the message content according to your application's protocol.
    }
}

CPushMessage method

Description

getMessageId()

Returns the message ID.

getAppId()

Returns the app ID.

getTitle()

Returns the message title.

getContent()

Returns the message content.

getTraceInfo()

Returns the information required for statistical reporting. Preserve it with the original message and do not modify it.

If your application creates its own notification from a passthrough message, use the statistical reporting interfaces for self-created notifications. Pass the original CPushMessage object when the notification is clicked or removed.

CPushMessage.getMessageId: Get message ID

Reads the message ID from the message parameter of the onMessage callback.

Method signature

public String getMessageId();

Parameters: None.

Return value: The server-side message ID, used to correlate push messages. This is not the same as the integer notification ID used by Android's NotificationManager. The return type is String.

In the example, message is the parameter from the onMessage callback. Retain the original object for later use in statistical reporting for self-created notifications.

Code example

String messageId = message.getMessageId();
val messageId = message.messageId

CPushMessage.getAppId: Get app ID

Reads the app ID from the message parameter of the onMessage callback.

Method signature

public String getAppId();

Parameters: None.

Return value: The app ID carried by the message. The return type is String.

In the example, message is the parameter from the onMessage callback. Retain the original object for later use in statistical reporting for self-created notifications.

Code example

String appId = message.getAppId();
val appId = message.appId

CPushMessage.getTitle: Get message title

Reads the message title from the message parameter of the onMessage callback.

Method signature

public String getTitle();

Parameters: None.

Return value: The title of the passthrough message. The value may be null. The return type is String.

In the example, message is the parameter from the onMessage callback. Retain the original object for later use in statistical reporting for self-created notifications.

Code example

String title = message.getTitle();
val title = message.title

CPushMessage.getContent: Get message content

Reads the message content from the message parameter of the onMessage callback.

Method signature

public String getContent();

Parameters: None.

Return value: The content of the passthrough message. The content format is defined by the sender and your application. The return type is String.

In the example, message is the parameter from the onMessage callback. Retain the original object for later use in statistical reporting for self-created notifications.

Code example

String content = message.getContent();
val content = message.content

CPushMessage.getTraceInfo: Get statistical information

Reads the statistical information from the message parameter of the onMessage callback.

Method signature

public String getTraceInfo();

Parameters: None.

Return value: The raw information used by the SDK for statistical reporting. Preserve and pass this along with the original message. The return type is String.

In the example, message is the parameter from the onMessage callback. Retain the original object for later use in statistical reporting for self-created notifications.

Code example

String traceInfo = message.getTraceInfo();
val traceInfo = message.traceInfo

Notification arrival callback

The SDK invokes this callback when it handles a notification arrival. Whether the notification is displayed in the system notification bar depends on display logic and system settings.

void onNotification(Context context, String title, String summary,
        Map<String, String> extraMap);

Parameter

Type

Required

Description

context

Context

Yes

The component context the SDK uses to dispatch events. For UI operations, use a valid Activity context.

title

String

No

The notification title.

summary

String

No

The notification content.

extraMap

Map<String, String>

No

The parsed notification extra parameters. The keys for custom parameters are defined by the sender; there is no standard key for navigation logic.

In SDK 4.x, the onNotification callback is always triggered, even if showNotificationNow returns false or a custom style is configured to prevent foreground display. To show the notification, your app must also have the necessary system permissions and a configured notification channel.

Return value: None (void). This callback indicates that the notification data has arrived.

Code example

@Override
public void onNotification(Context context, String title, String summary,
                           Map<String, String> extraMap) {
    String businessId = extraMap == null ? null : extraMap.get("businessId");
    if (businessId != null) {
        // "businessId" is a custom extra parameter defined by the sender.
        // Update application data based on your business requirements.
    }
}
override fun onNotification(
    context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
) {
    val businessId = extraMap?.get("businessId")
    if (businessId != null) {
        // "businessId" is a custom extra parameter defined by the sender.
    }
}

Control notification display

boolean showNotificationNow(Context context, Map<String, String> map);

Return true to let the SDK create and display the notification. Return false to prevent the display, allowing your application to handle the business logic in onNotification. The map parameter contains the raw notification data from the SDK. Custom extra parameters are in a JSON string within the ext field and must be parsed by your application. The default implementation considers foreground display settings for custom styles. DND rules take precedence over this method.

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The context used by the SDK when creating the notification.

map

Map<String, String>

Yes

The top-level Map of the SDK's raw notification data. Custom extra parameters are contained within a JSON string under the ext key and are not flattened into the top-level map.

Return value: boolean. Returns true to allow the SDK to continue building and displaying the notification; returns false to intercept the SDK's notification display. You can call super.showNotificationNow to retain the default foreground display rules.

The following example intercepts the notification only if the conversationId from the business extra parameters matches the current session. conversationId is a custom example key defined by the application. If the value is null or a JSON parsing error occurs, the logic falls back to the SDK's default behavior. The extraMap in onNotification and onNotificationOpened contains parsed business parameters and is different from the top-level map provided here.

@Override
public boolean showNotificationNow(Context context, Map<String, String> map) {
    String ext = map.get("ext");
    if (ext != null) {
        try {
            String conversationId = new org.json.JSONObject(ext)
                    .optString("conversationId", "");
            if (!conversationId.isEmpty()
                    && conversationId.equals(getVisibleConversationId())) {
                return false;
            }
        } catch (org.json.JSONException ignored) {
            // Invalid extra parameters do not affect the default display logic.
        }
    }
    return super.showNotificationNow(context, map);
}
private String getVisibleConversationId() {
    return ""; // Replace with the ID of the currently viewed conversation. An empty string means no conversation is being viewed.
}
override fun showNotificationNow(context: Context, map: Map<String, String>): Boolean {
    val ext = map["ext"]
    if (ext != null) {
        try {
            val conversationId = org.json.JSONObject(ext).optString("conversationId", "")
            if (conversationId.isNotEmpty() && conversationId == getVisibleConversationId()) {
                return false
            }
        } catch (ignored: org.json.JSONException) {
            // Invalid extra parameters do not affect the default display logic.
        }
    }
    return super.showNotificationNow(context, map)
}
private fun getVisibleConversationId(): String = "" // Replace with the current conversation ID in your app.

Notification click callback

void onNotificationOpened(Context context, String title, String summary,
        Map<String, String> extraMap);

In SDK 4.x, extraMap is a Map<String, String>, not a JSON string; the data may be null. Clicks on proprietary channel notifications with no configured action also trigger this callback, so you no longer need to implement onNotificationClickedWithNoAction. Clicks on vendor channel notifications are routed to this same callback after being parsed by a correctly configured intermediate Activity.

When page navigation is required, handle it using your application's routing logic and current page state. Use a valid Activity to handle UI operations.

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The component context the SDK uses to dispatch events. For UI operations, use a valid Activity context.

title

String

No

The notification title.

summary

String

No

The notification content.

extraMap

Map<String, String>

No

The parsed notification extra parameters. The keys for custom parameters are defined by the sender; there is no standard key for navigation logic.

Return value: None (void). Implement your application's click-handling logic here. If page navigation is already configured in the SDK or on the server, avoid duplicate navigation.

Code example

@Override
public void onNotificationOpened(Context context, String title, String summary,
                                 Map<String, String> extraMap) {
    String businessId = extraMap == null ? null : extraMap.get("businessId");
    if (businessId != null) {
        // Handle the click according to your app's business logic.
        // "businessId" is not a fixed SDK field.
    }
}
override fun onNotificationOpened(
    context: Context, title: String?, summary: String?, extraMap: Map<String, String>?
) {
    val businessId = extraMap?.get("businessId")
    if (businessId != null) {
        // Handle the click according to your app's business logic.
    }
}

Notification removal callback

void onNotificationRemoved(Context context, String messageId);

When a notification is removed, this callback returns the server-side message ID. It is not the same as the integer notification ID used by Android's NotificationManager and cannot be used interchangeably.

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The component context the SDK uses to dispatch the removal event.

messageId

String

No

The server-side message ID corresponding to the removed notification. Perform a null check before use.

Return value: None (void). This callback is triggered when a user removes a notification that was displayed by the SDK. It does not indicate the removal status of system notifications from vendor channels.

Code example

@Override
public void onNotificationRemoved(Context context, String messageId) {
    if (messageId != null) {
        // Clean up notification records saved by the application based on the message ID.
    }
}
override fun onNotificationRemoved(context: Context, messageId: String?) {
    if (messageId != null) {
        // Clean up notification records saved by the application based on the message ID.
    }
}

Migration and verification

3.x usage

4.x usage

onNotificationOpened(..., String extraMap)

Changed to Map<String, String>. Perform a null check before use.

onNotificationClickedWithNoAction(...)

Removed. Use onNotificationOpened for all cases.

onNotificationReceivedInApp(...)

Removed. Use onNotification for all cases.

Auxiliary pop-up window onSysNoticeOpened

Move the business logic to onNotificationOpened in your Receiver/Service.

Test each scenario: passthrough messages; notification arrival in the foreground and background for the proprietary channel; display interception; notification clicks for both proprietary and vendor channels; notification removal; and the service dispatch configuration after an app restart. To troubleshoot, check the SDK logs using the EMAS_PUSH tag and filter by the relevant module. Your application's log tags do not need to be the same as the SDK's tags.

Related documents

For the integration process, see Android SDK Integration (4.x).

For applications using SDK 3.x, see Message and Notification Handling Interfaces (3.x).