高阶配置接口（4.x）-阿里云帮助中心

调用前准备

先完成 PushServiceFactory.init，再获取 CloudPushService。PushServiceFactory 位于 com.alibaba.sdk.android.push.noonesdk，以下接口属于 com.alibaba.sdk.android.push.CloudPushService。

以下 Java 和 Kotlin 示例为业务方法内的代码片段。context 表示有效的 Android Context；R.drawable.notification_large 和 R.drawable.notification_small 为应用自行准备的 drawable 资源，请替换为实际资源 ID。

设置通知大图标

设置 SDK 创建通知时使用的大图标 Bitmap，不改变状态栏小图标。

所属类：CloudPushService。

接口定义

void setNotificationLargeIcon(Bitmap icon);

参数说明

参数	类型	是否必填	说明
icon	Bitmap	否	通知大图标。传入非空 Bitmap 设置自定义图标；传 null 清除该自定义 Bitmap，后续通知按默认图标规则处理。

返回值与回调：void，无返回值，也不提供设置结果回调。配置用于后续创建的通知，不会重新绘制已展示的通知。

未设置时，SDK 尝试使用应用 drawable 目录中的 alicloud_notification_largeicon 资源。服务端指定的通知图片可能优先于此设置。请准备适合通知展示的资源。

代码示例

Java

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

Kotlin

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

设置通知状态栏小图标

设置 SDK 创建通知时使用的状态栏小图标资源 ID，不改变通知大图标。

所属类：CloudPushService。

接口定义

void setNotificationSmallIcon(int iconId);

参数说明

参数	类型	是否必填	说明
iconId	int	是	应用 drawable 小图标资源 ID。传 0 取消该自定义资源 ID，后续通知按默认小图标规则处理。

返回值与回调：void，无返回值，也不提供设置结果回调。配置用于后续创建的通知，不会重新绘制已展示的通知。

未设置时，SDK 尝试读取 drawable/alicloud_notification_smallicon；无法获取时再使用应用图标。自定义通知样式中的图标设置也可能影响最终结果。

代码示例

Java

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

Kotlin

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

设置免打扰时段

设置每天的免打扰时间段，在该时段过滤 SDK 处理的通知与消息。

所属类：CloudPushService。

接口定义

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

参数说明

参数	类型	是否必填	说明
startHour	int	是	免打扰开始小时，24 小时制，取值 0～23，使用设备本地时间。
startMinute	int	是	免打扰开始分钟，取值 0～59。
endHour	int	是	免打扰结束小时，24 小时制，取值 0～23，使用设备本地时间。
endMinute	int	是	免打扰结束分钟，取值 0～59。
callback	CommonCallback	是	设置结果回调，必须提供非空对象；成功和失败含义见下文。

返回值与回调：void，无同步返回值。设置成功调用 onSuccess(String response)，4.0.0 的 response 为 "success"；时间参数超出范围或未完成初始化时调用 onFailed(String errorCode, String errorMessage)，分别返回错误码和失败原因。设置成功表示本地免打扰配置已生效。消息送达结果请通过推送回执和设备接收情况验证。

设置后自动启用免打扰。支持跨午夜时段，例如 22:00～次日 07:00；多次调用以最后一次设置为准。全天免打扰可设置 00:00～23:59。免打扰优先于 showNotificationNow，作用于 ACCS 自有通道的通知和消息，对厂商通道通知无效。

4.0.0 的该设置为进程内状态，如需在应用重启后继续生效，请根据应用保存的业务配置重新设置。

代码示例

Java

CommonCallback callback = new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        // 本地免打扰配置成功；4.0.0 的 response 为 "success"。
    }
    @Override
    public void onFailed(String errorCode, String errorMessage) {
        // 记录错误码并按业务需要处理失败，不输出敏感数据。
    }
};
PushServiceFactory.getCloudPushService()
        .setDoNotDisturb(22, 0, 7, 0, callback);

Kotlin

val callback = object : CommonCallback {
    override fun onSuccess(response: String?) {
        // 本地免打扰配置成功；4.0.0 的 response 为 "success"。
    }
    override fun onFailed(errorCode: String?, errorMessage: String?) {
        // 按业务需要处理失败。
    }
}
PushServiceFactory.getCloudPushService()
    .setDoNotDisturb(22, 0, 7, 0, callback)

关闭免打扰

关闭先前通过 setDoNotDisturb 启用的免打扰模式，恢复按正常流程处理后续通知与消息。

所属类：CloudPushService。

接口定义

void closeDoNotDisturbMode();

参数说明：无。

返回值与回调：void，无返回值和结果回调。

新进程中免打扰模式默认关闭。需要关闭已启用的免打扰模式时，请调用 closeDoNotDisturbMode。

代码示例

Java

PushServiceFactory.getCloudPushService().closeDoNotDisturbMode();

Kotlin

PushServiceFactory.getCloudPushService().closeDoNotDisturbMode()

清除通知

清除 SDK 管理的已展示通知，不关闭推送通道，也不停止接收后续通知。

所属类：CloudPushService。

接口定义

void clearNotifications();

参数说明：无。

返回值与回调：void，无返回值和结果回调。

清除 SDK 管理的通知，不控制厂商通道创建的通知。若业务需要精确取消某条自行创建的通知，请保存其 Android 通知 ID 并通过系统通知 API 管理。

代码示例

Java

PushServiceFactory.getCloudPushService().clearNotifications();

Kotlin

PushServiceFactory.getCloudPushService().clearNotifications()

监听大图标和大图下载失败

设置通知大图标和大图的下载失败监听器，用于感知图片下载失败原因。

所属类：CloudPushService。

接口定义

void setLargeIconDownloadListener(OnLargeIconDownloadListener listener);

参数说明

参数	类型	是否必填	说明
listener	DownloadUtil.OnLargeIconDownloadListener	否	图片下载失败监听对象。传 null 取消监听；重复设置时以后一次传入的监听器为准。

返回值与回调：void，无设置结果返回值。图片下载失败时触发下表对应回调；两个回调方法均返回 void。

OnLargeIconDownloadListener 位于 com.alibaba.sdk.android.push.util.DownloadUtil，用于接收通知图片下载失败事件。通知到达情况请通过 onNotification 回调获取。

回调	说明
void onDownloadLargeIconFailed(String error)	通知大图标下载失败。error 为 String 类型的失败原因，可能来自 HTTP 错误或异常信息；允许为 null。
void onDownloadBigPictureFailed(String error)	通知大图下载失败。error 为 String 类型的失败原因，可能来自 HTTP 错误或异常信息；允许为 null。

代码示例

Java

PushServiceFactory.getCloudPushService().setLargeIconDownloadListener(
        new DownloadUtil.OnLargeIconDownloadListener() {
            @Override public void onDownloadLargeIconFailed(String error) {
                // 按业务需要记录失败原因。
            }
            @Override public void onDownloadBigPictureFailed(String error) {
                // 按业务需要处理大图下载失败。
            }
        });

Kotlin

PushServiceFactory.getCloudPushService().setLargeIconDownloadListener(
    object : DownloadUtil.OnLargeIconDownloadListener {
        override fun onDownloadLargeIconFailed(error: String?) {
            // 按业务需要处理大图标下载失败。
        }
        override fun onDownloadBigPictureFailed(error: String?) {
            // 按业务需要处理大图下载失败。
        }
    }
)

通过 Notification Channel 配置声音

以下是 Android 系统 API 的独立配置示例，不是 CloudPushService 接口。它只演示通知渠道的声音配置，与前述图标、免打扰配置分别生效。

Android 8.0 及以上的通知声音由系统通知渠道管理。请在应用中创建通知渠道，并使推送请求中的 AndroidNotificationChannel 与渠道 ID 一致。渠道创建后，实际声音由渠道配置和用户的系统设置共同决定，重复创建同一渠道不会覆盖用户设置。

Java

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    NotificationChannel channel = new NotificationChannel(
            "push_default", "消息通知", 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);
}

Kotlin

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    val channel = NotificationChannel(
        "push_default", "消息通知", 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)
}

兼容接口

接口定义	4.0.0 状态与使用边界
void setNotificationSoundFilePath(String filePath)	已废弃，签名仍保留。Android 8.0 及以上请使用 Notification Channel 配置声音；不作为新接入推荐方式。
void setNotificationShowInGroup(boolean inGroup)	已废弃，4.0.0 中仍保留本地通知分组配置，默认 false。新方案优先按通知分组使用说明配置服务端分组参数，并统一管理客户端与服务端的分组规则。

4.x 不再提供 PushControlService，不能调用 isConnected、reconnect、reset 或连接状态监听接口；这些内容仅适用于相应的旧版 SDK。

调用前准备

设置通知大图标

设置通知状态栏小图标

设置免打扰时段

关闭免打扰

清除通知

监听大图标和大图下载失败

通过 Notification Channel 配置声音

兼容接口

相关文档