Advanced configuration APIs (4.x)

Updated at:

This document describes how to configure notification icons, do not disturb mode, clear notifications, listen for image download failures, and manage compatibility settings for Android SDK 4.x.

Important

The notification configuration APIs in this document apply only to notifications delivered through the ACCS proprietary channel and do not affect notifications from third-party channels.

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

Before you begin

Initialize PushServiceFactory before you obtain the CloudPushService. PushServiceFactory is located in com.alibaba.sdk.android.push.noonesdk, and the following APIs are part of com.alibaba.sdk.android.push.CloudPushService.

The following Java and Kotlin examples are code snippets for your business methods. context represents a valid Android Context. R.drawable.notification_large and R.drawable.notification_small are drawable resources that you must provide in your application. Replace them with your actual resource IDs.

Set the large notification icon

Sets the large icon bitmap that the SDK uses when creating notifications. This does not change the status bar small icon.

Class: CloudPushService.

API definition

void setNotificationLargeIcon(Bitmap icon);

Parameters

Parameter

Type

Required

Description

icon

Bitmap

No

The large notification icon. Pass a non-null Bitmap to set a custom icon. Pass null to clear this custom bitmap; the SDK will then use the default icon for subsequent notifications.

Return value and callback: void. This method returns void and has no result callback. The configuration applies to subsequently created notifications and does not redraw notifications that are already displayed.

If this is not set, the SDK attempts to use the alicloud_notification_largeicon resource from your app's drawable directory. A server-side notification image may take precedence over this setting. Ensure you provide resources suitable for notification display.

Code example

Bitmap icon = BitmapFactory.decodeResource(
        context.getResources(), R.drawable.notification_large);
PushServiceFactory.getCloudPushService().setNotificationLargeIcon(icon);
val icon = BitmapFactory.decodeResource(context.resources, R.drawable.notification_large)
PushServiceFactory.getCloudPushService().setNotificationLargeIcon(icon)

Set the status bar small icon

Sets the resource ID of the status bar small icon that the SDK uses when creating notifications. This does not change the large notification icon.

Class: CloudPushService.

API definition

void setNotificationSmallIcon(int iconId);

Parameters

Parameter

Type

Required

Description

iconId

int

Yes

The resource ID of a small icon in your app's drawable directory. Pass 0 to clear this custom resource ID; the SDK will then use the default small icon for subsequent notifications.

Return value and callback: void. This method returns void and has no result callback. The configuration applies to subsequently created notifications and does not redraw notifications that are already displayed.

If you do not set a small icon, the SDK first attempts to read drawable/alicloud_notification_smallicon. If this resource cannot be found, the app's launcher icon is used. The icon settings in a custom notification style may also affect the final result.

Code example

PushServiceFactory.getCloudPushService()
        .setNotificationSmallIcon(R.drawable.notification_small);
PushServiceFactory.getCloudPushService()
    .setNotificationSmallIcon(R.drawable.notification_small)

Set a do not disturb period

Sets a daily do not disturb period, during which the SDK filters the notifications and messages it processes.

Class: CloudPushService.

API definition

void setDoNotDisturb(int startHour, int startMinute,
        int endHour, int endMinute, CommonCallback callback);

Parameters

Parameter

Type

Required

Description

startHour

int

Yes

The start hour of the do not disturb period in 24-hour format. The value must be between 0 and 23. This is based on the device's local time.

startMinute

int

Yes

The start minute of the do not disturb period. The value must be between 0 and 59.

endHour

int

Yes

The end hour of the do not disturb period in 24-hour format. The value must be between 0 and 23. This is based on the device's local time.

endMinute

int

Yes

The end minute of the do not disturb period. The value must be between 0 and 59.

callback

CommonCallback

Yes

The callback for the result. You must provide a non-null object. For details on success and failure cases, see the description below.

Return value and callback: void. This method does not have a synchronous return value. If the operation is successful, the onSuccess(String response) callback is invoked, where response is "success" in version 4.0.0. If the time parameters are out of range or initialization is not complete, the onFailed(String errorCode, String errorMessage) callback is invoked with an error code and message. A successful call indicates that the local do not disturb configuration has taken effect. To verify message delivery, check delivery receipts and device reception status.

The do not disturb mode is automatically enabled after this method is called. It supports periods that cross midnight, such as from 22:00 to 07:00 the next day. If you call this method multiple times, only the last setting is applied. To enable do not disturb for the entire day, set the period from 00:00 to 23:59. This setting has a higher priority than showNotificationNow and applies only to notifications and messages from the ACCS proprietary channel, not to those from third-party channels.

In version 4.0.0, this setting is not persisted across application restarts. To maintain the do not disturb period, you must save the configuration and re-apply it each time the application starts.

Code example

CommonCallback callback = new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        // Local do not disturb setting applied. In version 4.0.0, the response is "success".
    }
    @Override
    public void onFailed(String errorCode, String errorMessage) {
        // Record the error code and handle the failure as required by your business logic. Do not log sensitive data.
    }
};
PushServiceFactory.getCloudPushService()
        .setDoNotDisturb(22, 0, 7, 0, callback);
val callback = object : CommonCallback {
    override fun onSuccess(response: String?) {
        // Local do not disturb setting applied. In version 4.0.0, the response is "success".
    }
    override fun onFailed(errorCode: String?, errorMessage: String?) {
        // Handle the failure as required by your business logic.
    }
}
PushServiceFactory.getCloudPushService()
    .setDoNotDisturb(22, 0, 7, 0, callback)

Disable do not disturb mode

Disables the do not disturb mode previously enabled by calling setDoNotDisturb, resuming normal processing of subsequent notifications and messages.

Class: CloudPushService.

API definition

void closeDoNotDisturbMode();

Parameters: None.

Return value and callback: void. This method has no return value or result callback.

In a new process, do not disturb mode is off by default. Call closeDoNotDisturbMode when you need to disable an enabled do not disturb mode.

Code example

PushServiceFactory.getCloudPushService().closeDoNotDisturbMode();
PushServiceFactory.getCloudPushService().closeDoNotDisturbMode()

Clear notifications

Clears all displayed notifications managed by the SDK. This does not close the push channel or stop the reception of subsequent notifications.

Class: CloudPushService.

API definition

void clearNotifications();

Parameters: None.

Return value and callback: void. This method has no return value or result callback.

This method clears notifications managed by the SDK but does not control notifications created by third-party channels. If your business logic requires canceling a specific, self-created notification, save its Android notification ID and manage it using the system's notification APIs.

Code example

PushServiceFactory.getCloudPushService().clearNotifications();
PushServiceFactory.getCloudPushService().clearNotifications()

Listen for image download failures

Sets a listener to detect download failures for notification large icons and big pictures, allowing you to diagnose the cause of the failure.

Class: CloudPushService.

API definition

void setLargeIconDownloadListener(OnLargeIconDownloadListener listener);

Parameters

Parameter

Type

Required

Description

listener

DownloadUtil.OnLargeIconDownloadListener

No

A listener that reports image download failures. Pass null to remove it. If this method is called multiple times, only the last listener set is used.

Return value and callback: void. This method does not return a result. When an image download fails, the corresponding callback in the table below is triggered. Both callback methods return void.

OnLargeIconDownloadListener, located in com.alibaba.sdk.android.push.util.DownloadUtil, receives events for notification image download failures. To get notification arrival status, use the onNotification callback.

Callback

Description

void onDownloadLargeIconFailed(String error)

Triggered when the notification's large icon fails to download. The error parameter contains a string with the failure reason, such as an HTTP error or exception message. This string can be null.

void onDownloadBigPictureFailed(String error)

Triggered when the notification's big picture fails to download. The error parameter contains a string with the failure reason, such as an HTTP error or exception message. This string can be null.

Code example

PushServiceFactory.getCloudPushService().setLargeIconDownloadListener(
        new DownloadUtil.OnLargeIconDownloadListener() {
            @Override public void onDownloadLargeIconFailed(String error) {
                // Record the failure reason as required by your business logic.
            }
            @Override public void onDownloadBigPictureFailed(String error) {
                // Handle the big picture download failure as required by your business logic.
            }
        });
PushServiceFactory.getCloudPushService().setLargeIconDownloadListener(
    object : DownloadUtil.OnLargeIconDownloadListener {
        override fun onDownloadLargeIconFailed(error: String?) {
            // Handle the large icon download failure as required by your business logic.
        }
        override fun onDownloadBigPictureFailed(error: String?) {
            // Handle the big picture download failure as required by your business logic.
        }
    }
)

Configure sound with a notification channel

The following example uses the Android system API to configure notification sounds. This configuration is independent of the CloudPushService interface and the icon and do not disturb settings described earlier.

On Android 8.0 (API level 26) and higher, notification sounds are managed by the system's Notification Channels. Create a Notification Channel in your app and ensure that the AndroidNotificationChannel in your push request matches the channel ID. After you create a channel, the actual sound is determined by both the channel's configuration and the user's system settings. Re-creating a channel with the same ID does not override the user's settings for that channel.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    NotificationChannel channel = new NotificationChannel(
            "push_default", "Message Notifications", NotificationManager.IMPORTANCE_DEFAULT);
    Uri sound = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION);
    AudioAttributes attributes = new AudioAttributes.Builder()
            .setUsage(AudioAttributes.USAGE_NOTIFICATION)
            .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
            .build();
    channel.setSound(sound, attributes);
    NotificationManager manager = context.getSystemService(NotificationManager.class);
    manager.createNotificationChannel(channel);
}
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    val channel = NotificationChannel(
        "push_default", "Message Notifications", NotificationManager.IMPORTANCE_DEFAULT
    )
    val sound = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION)
    val attributes = AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_NOTIFICATION)
        .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
        .build()
    channel.setSound(sound, attributes)
    context.getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
}

Compatibility APIs

API definition

Status and usage

void setNotificationSoundFilePath(String filePath)

Deprecated, but the signature is retained. On Android 8.0 and higher, use a Notification Channel to configure sounds. This method is not recommended for new integrations.

void setNotificationShowInGroup(boolean inGroup)

Deprecated. Version 4.0.0 retains the local notification grouping configuration, which is false by default. For new implementations, we recommend configuring server-side grouping parameters according to the notification grouping guide and manage client-side and server-side grouping rules consistently.

Version 4.x no longer provides PushControlService. APIs such as isConnected, reconnect, reset, and connection status listeners have also been removed. These features are available only in older SDK versions.

Related documents

For integration instructions, see Integrate the Android SDK (4.x).

If you are using version 3.x, see Advanced configuration APIs (3.x).