帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>推送服务（Push）>快速接入>高级功能>自定义右侧通知图片

自定义右侧通知图片

最近更新时间：2026-09-15 11:17:15
我的收藏

本页目录：

通知图片是展示在系统通知栏中的图像内容，用于强化消息的视觉表达，提升用户点击意愿。图片通常展示在通知右侧，部分通道展开后可显示为大图。本文主要介绍各厂商通道对自定义通知图片的支持情况以及如何实现该功能。

效果示例



厂商通道支持说明

由于不同手机系统的限制，仅部分厂商通道支持自定义通知图片，支持情况如下：
设备类型
是否支持自定义通知图片
iOS
支持。折叠展示为右侧小图标，展开展示为大图。
华为
支持。展示为右侧小图标。
荣耀
支持。展示为右侧小图标。
小米
不展示图片，仅展示标题与内容。
vivo
不展示图片，仅展示标题与内容。
OPPO
不展示图片，仅展示标题与内容。
魅族
不展示图片，仅展示标题与内容。
HarmonyOS
支持。展示为右侧小图标。
Google FCM
支持。折叠展示为大图标，展开展示为大图。
说明：
接口中没有统一的 Android 图片字段，Android 端需按厂商分别设置。
在不支持的通道上设置图片字段不会报错，字段会被忽略，通知正常展示。

图片规格要求

设备类型
大小上限
推荐尺寸
支持格式
iOS
10 MB
—
JPEG、GIF、PNG
华为
512 KB
40dp × 40dp，圆角 8dp
JPG、JPEG、PNG
荣耀
100 KB
160px × 160px，圆角 32px
JPG、JPEG、PNG
HarmonyOS
—
长 × 宽 < 25000 像素
PNG、JPG、JPEG、HEIF、GIF、BMP
Google FCM
1 MB
—
JPG、JPEG、PNG
注意：
图片链接必须使用 HTTPS 协议，HTTP 链接会被系统拦截，图片不展示。
图片必须公网可访问，内网地址或需鉴权的地址会下载失败。
超出大小上限的图片会被压缩或显示不全。各通道限制差异较大（荣耀 100 KB、iOS 10 MB），建议按通道分别准备图片。

接入说明

Android
iOS
HarmonyOS
REST API

支持厂商

华为、荣耀、Google FCM。小米、vivo、OPPO、魅族通道不支持。

配置方法

Android 端无需额外配置，发送离线推送时通过 V2TIMOfflinePushInfo 设置对应厂商字段即可。
V2TIMOfflinePushInfo pushInfo = new V2TIMOfflinePushInfo();
pushInfo.setTitle("推送标题");
pushInfo.setDesc("推送内容");

pushInfo.setAndroidHuaWeiImage("https://example.com/image_512kb.png");
pushInfo.setAndroidHonorImage("https://example.com/image_100kb.png");
pushInfo.setAndroidFCMImage("https://example.com/image_1mb.png");
pushInfo.setIOSImage("https://example.com/image_1mb.png");

// 创建文本消息
V2TIMMessage message = V2TIMManager.getMessageManager().createTextMessage("你好");

// 发送消息，单聊填对端 userID，群聊填 null + groupID
V2TIMManager.getMessageManager().sendMessage(
        message,
        "接收方 userID",                      // 单聊填对端 userID，群聊填 null
        null,                                 // 群聊填 groupID，单聊填 null
        V2TIMMessage.V2TIM_PRIORITY_DEFAULT,
        false,                                // onlineUserOnly，必须为 false
        pushInfo,
        new V2TIMSendCallback<V2TIMMessage>() {
            @Override
            public void onProgress(int progress) { }

            @Override
            public void onSuccess(V2TIMMessage msg) {
                // 发送成功
            }

            @Override
            public void onError(int code, String desc) {
                // 发送失败，code 为错误码
            }
        });
各通道大小限制不同，不建议所有字段使用同一个图片链接，否则可能因超限导致部分通道不展示。
iOS 需要通过 Notification Service Extension 在客户端下载图片，共三步。

步骤1：开启 mutable-content

登录腾讯云控制台，进入 推送服务 Push > 基础配置 > iOS 证书 > 编辑，开启 mutable-content 属性。
注意：
未开启该属性时，Notification Service Extension 不会被触发，图片不会展示。

步骤2：集成 Notification Service Extension

在 Xcode 中选择 File > New > Target > Notification Service Extension，创建后在生成的 NotificationService.m 中实现图片下载：
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                   withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // 图片链接固定存放在 userInfo 的 image 字段
    NSString *imageURLString = self.bestAttemptContent.userInfo[@"image"];
    NSURL *imageURL = imageURLString.length > 0 ? [NSURL URLWithString:imageURLString] : nil;
    if (!imageURL) {
        self.contentHandler(self.bestAttemptContent);
        return;
    }

    [self downloadImageWithURL:imageURL completion:^(NSString *localPath) {
        if (localPath.length > 0) {
            // 附件必须使用本地文件路径，不能直接使用网络链接
            UNNotificationAttachment *attachment =
                [UNNotificationAttachment attachmentWithIdentifier:@"image"
                                                              URL:[NSURL fileURLWithPath:localPath]
                                                          options:nil
                                                            error:nil];
            if (attachment) {
                self.bestAttemptContent.attachments = @[attachment];
            }
        }
        self.contentHandler(self.bestAttemptContent);
    }];
}

// 下载图片并移动到临时目录
- (void)downloadImageWithURL:(NSURL *)url completion:(void (^)(NSString *localPath))completion {
    NSURLSessionDownloadTask *task = [[NSURLSession sharedSession]
        downloadTaskWithURL:url
          completionHandler:^(NSURL *location, NSURLResponse *response, NSError *error) {
        NSString *localPath = nil;
        if (!error && location) {
            NSString *fileName = url.lastPathComponent.length > 0 ? url.lastPathComponent : @"push_image";
            NSString *tmpPath = [NSTemporaryDirectory() stringByAppendingPathComponent:fileName];
            [[NSFileManager defaultManager] removeItemAtPath:tmpPath error:nil];
            if ([[NSFileManager defaultManager] moveItemAtPath:location.path toPath:tmpPath error:nil]) {
                localPath = tmpPath;
            }
        }
        completion(localPath);
    }];
    [task resume];
}

// 下载超时兜底，系统限制约 30 秒
- (void)serviceExtensionTimeWillExpire {
    self.contentHandler(self.bestAttemptContent);
}
注意：
图片链接固定从 userInfo 的 image 字段获取，请勿自定义 key。
Extension 执行时限约 30 秒，图片过大可能下载超时导致图片不展示。

步骤3：发送时设置图片

发送离线推送时通过 V2TIMOfflinePushInfo 设置对应厂商字段即可。
V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];
pushInfo.title = @"推送标题";
pushInfo.desc = @"推送内容";
pushInfo.iOSImage = @"https://example.com/image.png";   // 必须 HTTPS

// 创建文本消息
V2TIMMessage *message = [[V2TIMManager sharedInstance] createTextMessage:@"你好"];

// 发送消息
[[V2TIMManager sharedInstance] sendMessage:message
                                  receiver:@"接收方 userID"  // 单聊填对端 userID，群聊填 nil
                                   groupID:nil               // 群聊填 groupID，单聊填 nil
                                  priority:V2TIM_PRIORITY_DEFAULT
                            onlineUserOnly:NO                // 必须为 NO，否则不走离线推送
                           offlinePushInfo:pushInfo
                                  progress:nil
                                      succ:^{
                                          // 发送成功
                                      }
                                      fail:^(int code, NSString *desc) {
                                          // 发送失败，code 为错误码
                                      }];
无需额外配置，发送时设置 V2TIMOfflinePushInfo 即可。
import { V2TIMManager, V2TIMMessage, V2TIMOfflinePushInfo } from '@tencentcloud/imsdk';

const pushInfo: V2TIMOfflinePushInfo = {
  title: '推送标题',
  desc: '推送内容',
  HarmonyImage: 'https://example.com/image.png',   // 必须 HTTPS
};

// 创建文本消息
const message: V2TIMMessage =
  V2TIMManager.getMessageManager().createTextMessage('你好');

// 发送消息
const res = V2TIMManager.getMessageManager().sendMessage(message, {
  receiver: '接收方 userID',   // 单聊填对端 userID，群聊不填
  groupID: '',                 // 群聊填 groupID，单聊不填
  onlineUserOnly: false,       // 必须为 false，否则不走离线推送
  offlinePushInfo: pushInfo,
});

res.promise
  .then(() => {
    // 发送成功
  })
  .catch((err) => {
    // 发送失败，err.code 为错误码
  });
说明：
HarmonyOS 限制的是图片像素总量而非文件大小，需满足长 × 宽 < 25000 像素。例如 158 × 158 = 24964，符合要求；160 × 160 = 25600，超出限制。
通过服务端发送推送时，在 OfflinePushInfo 中设置对应字段：
{
  "OfflinePushInfo": {
    "PushFlag": 0,
    "Title": "推送标题",
    "Desc": "推送内容",
    "AndroidInfo": {
      "HuaWeiImage": "https://example.com/image_512kb.png",
      "HonorImage": "https://example.com/image_100kb.png",
      "GoogleImage": "https://example.com/image_1mb.png"
    },
    "ApnsInfo": {
      "Image": "https://example.com/image.png",
      "MutableContent": 1
    },
    "HarmonyInfo": {
      "Image": "https://example.com/image.png"
    }
  }
}

常见问题

为什么图片不展示？

现象
原因
所有通道均不展示
图片链接非 HTTPS，或公网无法访问。可用浏览器直接打开链接验证。
仅荣耀不展示
图片超出 100 KB 限制。
仅华为不展示
图片超出 512 KB 限制。
仅 iOS 不展示
控制台未开启 mutable-content，或未集成 Notification Service Extension。
小米、vivo、OPPO、魅族不展示
属正常现象，这些通道不支持通知图片。
图片被裁切或显示不全
尺寸不符合推荐规格，请参考 图片规格要求 调整。
中国站