Advanced configuration APIs (4.x)
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.
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 |
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 |
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 |
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 |
|
void onDownloadBigPictureFailed(String error) |
Triggered when the notification's big picture fails to download. The |
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 |
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).