即时通信 IM 自定义右侧通知图片

一、厂商通道支持说明

由于不同手机系统的限制，仅部分厂商通道支持自定义通知图片，支持情况如下：

注意：说明：

二、图片规格要求

三、接入说明

AndroidiOSHarmonyOSREST 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 + groupIDV2TIMManager.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);}

八、步骤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" } }}

九、为什么图片不展示？