推播圖示設定指南

本文旨在指導使用者如何設定通知欄小圖示、右側圖示以及大圖片。 alt text

📱 iOS 圖示設定方式

小圖示設定

進入 Images.xcassets-AppIcon，設定 iPhone Notification 的圖示，所需尺寸為：

40 x 40px
60 x 60px

alt text

右側圖示 / 大圖片設定

✅ 支援版本

自 EngageLab iOS SDK v3.0.0 起，支援 iOS 10 及以上系統。

🧑‍💻 客戶端設定

建立一個 Service Extension 服務。
將 mtpush-extension-ios-xxx.xcframework 檔案引入您的 Service Extension 專案中。
新增以下兩個 Framework：
- libz.tbd
- libresolv.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 (attachmentPath) { 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 (attachmentPath) {
    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" />

此代碼塊在浮窗中顯示

🌐 伺服器端設定

欄位名稱	類型	是否必填	父欄位	說明
`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 目錄下與通知圖示相關的所有資源檔（如各種密度的 drawable-xxhdpi 等）也一併更新為新圖示。正確設定後，系統將顯示符合要求的灰色輪廓圖示，避免圖示異常或模糊。
由於部分系統（如一加手機、Google 手機上的 Android 10 等）對圖示存在限制，目前無法處理此問題。
小米手機的桌面啟動器（launcher）可能會快取圖示。請依照上述要求正確配置圖示後，重新啟動手機再進行測試。
無論小米手機使用 EngageLab 通道或小米原生通道，都需切換至原生通知樣式才可生效，切換方式如下：

2. 更換圖示後無效？

系統或廠商服務可能快取圖示。
建議卸載應用並重啟手機後，再安裝新版應用。

右側圖示 / 大圖片相關問題

圖示/圖片無法顯示？

EngageLab 通道：請確認是否呼叫了設定預設通知欄樣式的建構類接口，如有請刪除該接口，並卸載 App 後重試。
APNs（iOS）：右侧圖示與大圖片為同一張圖，前景模式下通知下拉顯示大圖，其它情況僅顯示右侧圖示。
FCM（Android）：展開前為右側圖示，展開後顯示大圖片。