推播圖標配置指引
本文旨在指導用戶如何設置通知欄小圖標、右側圖標以及大圖片。
📱 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 |
string | 可選 | notification.android |
網絡圖標鏈接或圖片資源路徑，大小不超過 300k |
small_icon_uri |
string | 可選 | options.third_party_channel.廠商名 |
廠商通道圖標樣式，目前僅支援華為廠商 |
示例 JSON：
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"small_icon": "logo"
}
},
"options": {
"time_to_live": 60,
"third_party_channel": {
"huawei": {
"distribution_new": "pns_mtpush",
"small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp"
}
}
}
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"small_icon": "logo"
}
},
"options": {
"time_to_live": 60,
"third_party_channel": {
"huawei": {
"distribution_new": "pns_mtpush",
"small_icon_uri": "https://res.engagelab.net/oversea/e/website/2025/_nuxt/app-push.II1rRaB5.webp"
}
}
}
此代碼塊在浮窗中顯示
🖼️ 右側圖標 / 大圖片設置
🌐 服務端字段說明
| 字段名 | 類型 | 是否必填 | 父字段 | 說明 |
|---|---|---|---|---|
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": "logo",
"big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg",
"style": 3
}
},
"options": {
"third_party_channel": {
"huawei": {
"distribution_new": "pns_mtpush",
"large_icon": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg"
}
}
}
}
{
"notification": {
"android": {
"alert": "Hi, Push!",
"title": "Send to Android",
"large_icon": "logo",
"big_pic_path": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg",
"style": 3
}
},
"options": {
"third_party_channel": {
"huawei": {
"distribution_new": "pns_mtpush",
"large_icon": "https://scpic.chinaz.net/files/pic/pic9/201311/apic2098.jpg"
}
}
}
}
此代碼塊在浮窗中顯示
❓ 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）：展開前為右側圖標，展開後展示大圖。
