图标设置最佳实践_移动研发平台(EMAS)-阿里云帮助中心

前言

本文旨在提供全面的图标设置最佳实践指南，帮助开发人员在不同平台正确配置通知图标。

前提条件

请先确保已在EMAS控制台完成项目和应用的创建，若尚未完成，请详见快速入门。
已阅读接入对应SDK，具体请参见Android SDK接入、iOS SDK集成、HarmonyOS SDK接入。

Android

图片示例

CleanShot 2025-04-18 at 10

支持版本

阿里云自有通道从 SDK3.6.0版本开始支持，厂商通道图标从 SDK3.7.0版本开始支持。

通道支持情况

通道	动态设置小图标	右侧图标	大图片

通道	动态设置小图标	右侧图标	大图片
阿里云自有通道	支持	支持	支持
小米	不支持	不支持	不支持
华为	支持	支持	不支持
荣耀	不支持	支持	不支持
oppo	不支持	不支持	不支持
FCM	不支持	支持	不支持
魅族	不支持	不支持	不支持
vivo	不支持	不支持	不支持

说明

小米从 2023.08 开始，官方在新设备/系统已经不再支持推送时动态设置小图标、右侧图标、大图片功能。

技术实现方案

小图标

客户端

默认行为

优先级机制
SDK会首先尝试使用项目中名为 R.drawable.alicloud_notification_smallicon 的资源文件作为通知栏小图标。
备用方案
若未找到上述资源，SDK将自动使用应用启动图标（即AndroidManifest.xml中配置的应用图标）作为通知小图标。

自定义配置

如果您希望使用自定义的小图标，可以通过调用 setNotificationSmallIcon 接口进行设置。示例代码如下：

CloudPushService cloudPushService = PushServiceFactory.getCloudPushService();
cloudPushService.setNotificationSmallIcon(R.drawable.custom_notification_icon);

说明

自定义图标需符合系统规范（建议尺寸：24x24dp，支持深色/浅色主题适配）
调用需在推送服务初始化后生效
若同时存在 alicloud_notification_smallicon 资源和显式设置，以显式设置的图标为准

右侧图标/大图片

服务端

通过服务端下发指定参数实现右侧图标和大图片展示

参数	类型	必填	含义	说明

参数

类型

必填

含义

说明

AndroidImageUrl

string

否

右侧图标 URL

当前支持：

华为 EMUI（仅长文本模式、Inbox 模式下适用）。
荣耀 Magic UI（仅长文本模式下适用）。
自有通道：安卓 SDK3.5.0 及以上。

示例：https://example.com/large_icon.png

AndroidBigPictureUrl

string

否

大图片URL

大图模式下的图片 URL，当前支持：自有通道：安卓 SDK3.6.0 及以上。

示例：https://example.com/large_icon.png

代码示例如下：

PushRequest pushRequest = new PushRequest();
pushRequest.setAndroidImageUrl("https://example.com/large_icon.png");
pushRequest.setAndroidBigPictureUrl("https://example.com/large_icon.png");

iOS

图片示例

小图标

进入Xcode工程的 Images.xcassets-AppIcon目录，找到 iPhone Notification 对应的图标槽位进行配置

说明

根据 iOS 设备的屏幕分辨率，小图标的尺寸要求如下：

标准分辨率（@1x）：20×20像素（已逐步淘汰，仅支持旧机型）
Retina分辨率（@2x）：40×40像素（iPhone 4S及后续非Pro机型）
高分辨率（@3x）：60×60像素（iPhone 6 Plus/X/11等高分辨率机型）

请确保图标符合苹果设计指南：

图标需为纯色背景或透明PNG格式
避免文字或渐变效果
保持图标边缘与背景的清晰区分

右侧图标/大图片

支持版本

从 iOS SDK 1.9.5，iOS 10 开始支持

客户端

1. 集成Notification Service Extension

打开 Xcode，在菜单中选择 File -> New -> Target -> Notification Service Extension：
进行命名，点击Finish完成创建：
创建完成后在目录下Xcode会自动生成NotificationService的模板

2. 实现核心逻辑

在didReceiveNotificationRequest回调方法中，处理通知弹出前的动作。示例代码如下：

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    // Modify the notification content here...
    
    // 修改通知标题，方便查看通知显示效果
    self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
    
    // 获取通知中自定义KV字段，此处取key为`attachment`的value，为阿里云logo图片的Url地址
    // 控制台 or OpenAPI推送时需要设定iOSExtParameters，其中携带`attachment`KV
    NSString *picUrlString = self.bestAttemptContent.userInfo[@"attachment"];
    if (picUrlString) {
        NSString *picPath = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents"] stringByAppendingPathComponent:@"notice_media.png"];
        // 下载图片到本地
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDownloadTask *downloadTask = [session downloadTaskWithURL:[NSURL URLWithString:picUrlString] completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
            if (error) {
                self.bestAttemptContent.body = [error description];
            } else {
                NSFileManager *fm = [NSFileManager defaultManager];
                // 图片存储到指定picPath位置
                [fm moveItemAtPath:location.path toPath:picPath error:nil];
                // 创建通知附件
                UNNotificationAttachment *attachment = [UNNotificationAttachment attachmentWithIdentifier:@"pic" URL:[NSURL URLWithString:[@"file://" stringByAppendingString:picPath]] options:nil error:&error];
                if (error) {
                    self.bestAttemptContent.body = [error description];
                } else if (attachment) {
                    // 添加通知附件到通知
                    self.bestAttemptContent.attachments = @[attachment];
                }
                // 弹出修改后的通知
                self.contentHandler(self.bestAttemptContent);
            }
        }];
        [downloadTask resume];
    } else {
        // 若没有指定资源Url，从本地获取资源添加到通知中
        NSString *picLocalPath = [[NSBundle mainBundle] pathForResource:@"aliyun-logo-local" ofType:@"png"];
        if (picLocalPath) {
            NSError *error;
            UNNotificationAttachment *attachment = [UNNotificationAttachment attachmentWithIdentifier:@"pic" URL:[NSURL URLWithString:[@"file://" stringByAppendingString:picLocalPath]] options:nil error:&error];
            if (error) {
                self.bestAttemptContent.body = [error description];
            } else if (attachment) {
                // 添加附件到通知
                self.bestAttemptContent.attachments = @[attachment];
            }
        }
        // 弹出修改后的通知
        self.contentHandler(self.bestAttemptContent);
    }
}

说明

携带图片的推送通知详情请参考iOS Demo Notification Service Extension

服务端

图片展示需要在服务端下发时配置指定参数。

参数	类型	必填	含义	说明

参数

类型

必填

含义

说明

iOSMutableContent

boolean

否

iOS 通知处理扩展标记（iOS 10+）。

如果设为 true，则 APNs 推送的通知在弹出前，可先到达 Extension 进行处理。静默通知时，必须设为 true。

iOSExtParameters

string

否

iOS 通知的扩展属性。

iOS10+可以在此指定富媒体推送通知的资源 Url：{"attachment": "https://xxxx.xxx/notification_pic.png"} 。该参数要以 JSON map 的格式传入，否则会解析出错。

代码示例如下：

PushRequest pushRequest = new PushRequest();
pushRequest.setIOSMutableContent(true);
pushRequest.setIOSExtParameters("{\"attachment\": \"https://xxxx.xxx/notification_pic.png\"} ");

HarmonyOS

图片示例

CleanShot 2025-04-18 at 10

支持版本

厂商通道图标从 SDK版本 v3.8.2 开始支持。

通道支持情况

通道	动态设置小图标	右侧图标	大图片

通道	动态设置小图标	右侧图标	大图片
鸿蒙	不支持	支持	不支持

右侧图标

服务端

通过服务端下发指定参数实现右侧图标展示。

参数	类型	必填	含义	说明

参数

类型

必填

含义

说明

HarmonyImageUrl

string

否

通知右侧大图标 URL，URL 使用的协议必须是 HTTPS 协议。

详情参见鸿蒙官网Notification.image

支持图片格式为 png、jpg、jpeg、heif、gif、bmp，图片长*宽<25000 像素。

代码示例如下：

PushRequest pushRequest = new PushRequest();
pushRequest.setHarmonyImageUrl("https://example.com/xxx.png");