推送图标配置指南
本文旨在指导用户如何设置通知栏小图标、右侧图标以及大图片。
📱 iOS 设置图标的方法
小图标设置
进入 Images.xcassets-AppIcon，设置 iPhone Notification 的图标，所需尺寸为：
40 x 40px60 x 60px
右侧图标 / 大图片设置
✅ 支持版本
- 自 EngageLab iOS SDK
v3.0.0起，支持 iOS 10 及以上系统。
🧑💻 客户端设置
创建一个 Service Extension 服务。
引入
mtpush-extension-ios-xxx.xcframework文件至您的Service Extension工程中。添加以下两个 Framework：
libz.tbdlibresolv.tbd
调用
[mtpushSetAppkey:]方法设置 AppKey（请确保与 AppPush 应用创建时的 AppKey 一致）。在
[didReceiveNotificationRequest:]回调中获取图片链接，代码示例如下：
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [NotificationService]", self.bestAttemptContent.title];
NSString * attachmentPath = self.bestAttemptContent.userInfo[@"my-attachment"];
//if exist
if (attachmentPath) {
//download
NSURL *fileURL = [NSURL URLWithString:attachmentPath];
[self downloadAndSave:fileURL handler:^(NSString *localPath) {
if (localPath) {UNNotificationAttachment * attachment = [UNNotificationAttachment attachmentWithIdentifier:@"myAttachment" URL:[NSURL fileURLWithPath:localPath] options:nil error:nil];
self.bestAttemptContent.attachments = @[attachment];
}
[self apnsDeliverWith:request];
}];
}else{[self apnsDeliverWith:request];
}
}
- (void)downloadAndSave:(NSURL *)fileURL handler:(void (^)(NSString *))handler {
NSURLSession * session = [NSURLSession sharedSession];
NSURLSessionDownloadTask *task = [session downloadTaskWithURL:fileURL completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
NSString *localPath = nil;
if (!error) {NSString * localURL = [NSString stringWithFormat:@"%@/%@", NSTemporaryDirectory(),fileURL.lastPathComponent];
if ([[NSFileManager defaultManager] moveItemAtPath:location.path toPath:localURL error:nil]) {localPath = localURL;}
}
handler(localPath);
}];
[task resume];
}
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [NotificationService]", self.bestAttemptContent.title];
NSString * attachmentPath = self.bestAttemptContent.userInfo[@"my-attachment"];
//if exist
if (attachmentPath) {
//download
NSURL *fileURL = [NSURL URLWithString:attachmentPath];
[self downloadAndSave:fileURL handler:^(NSString *localPath) {
if (localPath) {UNNotificationAttachment * attachment = [UNNotificationAttachment attachmentWithIdentifier:@"myAttachment" URL:[NSURL fileURLWithPath:localPath] options:nil error:nil];
self.bestAttemptContent.attachments = @[attachment];
}
[self apnsDeliverWith:request];
}];
}else{[self apnsDeliverWith:request];
}
}
- (void)downloadAndSave:(NSURL *)fileURL handler:(void (^)(NSString *))handler {
NSURLSession * session = [NSURLSession sharedSession];
NSURLSessionDownloadTask *task = [session downloadTaskWithURL:fileURL completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
NSString *localPath = nil;
if (!error) {NSString * localURL = [NSString stringWithFormat:@"%@/%@", NSTemporaryDirectory(),fileURL.lastPathComponent];
if ([[NSFileManager defaultManager] moveItemAtPath:location.path toPath:localURL error:nil]) {localPath = localURL;}
}
handler(localPath);
}];
[task resume];
}
此代码块在浮窗中显示
🌐 服务端设置
需在 ios 下配置 mutable-content 和 extras 字段：
| 字段名 | 类型 | 是否必填 | 父字段 | 说明 |
|---|---|---|---|---|
mutable-content |
boolean | 可选 | notification.ios |
启用通知扩展，需设为 true 以支持 iOS 10 的 UNNotificationServiceExtension |
extras |
JSON Object | 可选 | notification.ios |
附加字段，其中的 key（如 my-attachment）需与客户端代码一致 |
示例 JSON：
"notification": {
"ios": {
"alert": {
"title": "title",
"subtitle": "subtitle"
},
"mutable-content": true,
"extras": {
"my-attachment": "https://raw.githubusercontent.com/Tikon/imgRepo/master/ic_launcher.png"
}
}
}
"notification": {
"ios": {
"alert": {
"title": "title",
"subtitle": "subtitle"
},
"mutable-content": true,
"extras": {
"my-attachment": "https://raw.githubusercontent.com/Tikon/imgRepo/master/ic_launcher.png"
}
}
}
此代码块在浮窗中显示
🤖 Android 设置图标的方法
✅ 支持版本
自 EngageLab Android SDK v4.4.0 起支持。
📡 通道支持情况
| 通道 | 动态小图标 | 右侧图标 | 大图片 |
|---|---|---|---|
| EngageLab 通道 | ✅（系统支持） | ✅（魅族除外） | ✅（系统支持） |
| 小米 | ❌ | ❌ | ❌ |
| 华为 | ✅ | ✅（服务类/资讯类） | ❌ |
| 荣耀 | ❌ | ✅（营销类不支持） | ❌ |
| OPPO | ❌ | ✅ | ✅ |
| FCM | ❌ | ✅ | ✅ |
| 魅族 | ❌ | ❌ | ❌ |
| vivo | ❌ | ❌ | ❌ |
📝 说明：
- OPPO：当推送目标超过 20 个且 ColorOS 版本 > 5.0，连接 WiFi 状态下首条通知展示大图。
- 小米：自 2023 年 8 月起，不再支持推送时动态设置图标和大图。
🎨 小图标设置
🧑💻 客户端设置
- 若项目中存在
res/drawable/mtpush_notification_icon资源，则默认使用该图标。 - 若无此资源，则默认使用应用图标。
FCM 通道配置示例：
<meta-data
android:name="com.google.firebase.messaging.default_notification_icon"
android:resource="@drawable/mtpush_notification_icon" />
<meta-data
android:name="com.google.firebase.messaging.default_notification_color"
android:resource="@color/colorAccent" />
<meta-data
android:name="com.google.firebase.messaging.default_notification_icon"
android:resource="@drawable/mtpush_notification_icon" />
<meta-data
android:name="com.google.firebase.messaging.default_notification_color"
android:resource="@color/colorAccent" />
此代码块在浮窗中显示
🌐 服务端设置
| 字段名 | 类型 | 是否必填 | 父字段 | 说明 |
|---|---|---|---|---|
small_icon_uri |
string | 可选 | notification.android |
网络图标链接或图片资源路径，大小不超过 300k |
small_icon_uri |
string | 可选 | options.third_party_channel.厂商名 |
厂商通道图标样式，目前仅支持华为厂商 |
示例 JSON：
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp"
}
},
"options": {
"time_to_live": 60,
"third_party_channel": {
"huawei": {
"distribution": "pns_mtpush",
"small_icon_uri": "logog"
}
}
}
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp"
}
},
"options": {
"time_to_live": 60,
"third_party_channel": {
"huawei": {
"distribution": "pns_mtpush",
"small_icon_uri": "logog"
}
}
}
此代码块在浮窗中显示
🖼️ 右侧图标 / 大图片设置
🌐 服务端字段说明
| 字段名 | 类型 | 是否必填 | 父字段 | 说明 |
|---|---|---|---|---|
style |
int | 可选 | notification.android |
通知栏样式类型：默认 0，1=bigText，2=Inbox，3=bigPicture |
big_pic_path |
string | 可选 | notification.android |
当 style=3 时生效，可设置 URL 或本地路径 |
large_icon |
string | 可选 | notification.android |
右侧图标，网络图或 drawable 资源路径，大小不超过 300k |
示例 JSON：
{
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"large_icon": "logog",
"big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg",
"style": 3
}
},
"options": {
"third_party_channel": {
"huawei": {
"distribution": "ospush",
"large_icon": "logog"
}
}
}
}
{
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"large_icon": "logog",
"big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg",
"style": 3
}
},
"options": {
"third_party_channel": {
"huawei": {
"distribution": "ospush",
"large_icon": "logog"
}
}
}
}
此代码块在浮窗中显示
❓ FAQ
小图标相关问题
1. 显示为灰色？
- 在原生 Android 5.0 及以上系统中，若应用的 targetSdkVersion ≥ 21，系统会对通知小图标强制添加蒙版色处理，导致图标显示为灰色。为确保图标在显示时具有良好的轮廓和识别度，建议使用无阴影、无渐变、背景透明的镂空图标，并将其命名为 mtpush_notification_icon，替换项目中 res/drawable 目录下的同名文件。同时，请确保 res 目录下与通知图标相关的所有 icon 文件（如不同密度的 drawable-xxhdpi 等）均统一替换为新的图标资源。正确设置后，系统将显示符合要求的灰色轮廓图标，避免图标异常或不清晰的问题。
- 由于部分系统（一加手机、google 手机 android10 系统等）对图标有限制，目前无法处理。
- 小米手机的 launcher 可能有缓存，按照上述要求配置好后， 需重启手机后再测试。
- 小米手机无论走Engagelab 通道还是小米通道，都需要切换到原生样式才可以生效,切换方式如下：
2. 更换图标后无效？
- 系统或厂商服务可能缓存图标。（小米和魅族手机可能会出现此现象）
- 建议卸载应用并重启手机后再重新安装新版本。
右侧图标 / 大图片相关问题
图标/图片无法显示？
- EngageLab 通道：请检查是否调用了设置默认通知栏样式的构建类接口。如调用过，请删除该接口，卸载 App 后重试。
- APNs（iOS）：右侧图标和大图片是同一张图，前台时通知下拉展示大图片，其它情况仅显示右侧图标。
- FCM（Android）：展开前为右侧图标，展开后展示大图。
