Message and notification handling API (4.x)
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.
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
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 |
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 |
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 |
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.messageIdCPushMessage.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.appIdCPushMessage.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.titleCPushMessage.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.contentCPushMessage.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.traceInfoNotification 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 |
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 |
|
onNotificationClickedWithNoAction(...) |
Removed. Use |
|
onNotificationReceivedInApp(...) |
Removed. Use |
|
Auxiliary pop-up window |
Move the business logic to |
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).