Push Icon Configuration Guide

This document provides instructions for setting up small notification icons, right-side icons, and large images for push notifications.

📱 iOS Icon Configuration

Small Icon Setup

Go to Images.xcassets-AppIcon and configure the iPhone Notification icon. Required sizes:

• 40 x 40px
• 60 x 60px

Right-side Icon / Large Image Setup

✅ Supported Versions

• Supported on iOS 10 and above with EngageLab iOS SDK v3.0.0 and later.

🧑‍💻 Client-side Setup

1. Create a Service Extension target.

2. Import the mtpush-extension-ios-xxx.xcframework file into your Service Extension target.

3. Add the following two frameworks:

   • libz.tbd
   • libresolv.tbd

4. Call [mtpushSetAppkey:] to set the AppKey (must match the one used when creating the AppPush application).

5. In the [didReceiveNotificationRequest:] callback, retrieve the image URL. Example code:

              
              - (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];
}

            

🌐 Server-side Configuration

You need to configure the mutable-content and extras fields under ios:

Example JSON:

              
              "notification": {
  "ios": {
    "alert": {
      "title": "title",
      "subtitle": "subtitle"
    },
    "mutable-content": true,
    "extras": {
      "my-attachment": "https://raw.githubusercontent.com/Tikon/imgRepo/master/ic_launcher.png"
    }
  }
}

            

🤖 Android Icon Configuration

✅ Supported Versions

Supported from EngageLab Android SDK v4.4.0 onward.

📡 Channel Support Overview

📝 Notes:

• OPPO: If more than 20 users are targeted and ColorOS > 5.0, the first push notification shows a large image on Wi-Fi.
• Xiaomi: As of August 2023, no longer supports dynamically setting icons and images via push.

🎨 Small Icon Setup

🧑‍💻 Client-side Setup

• If res/drawable/mtpush_notification_icon exists in the project, it will be used by default.
• If not, the app’s launcher icon is used.

FCM Channel Example:

              
              <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" />

            

🌐 Server-side Configuration

Example 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"
    }
  }
}

            

🖼️ Right-side Icon / Large Image Setup

🌐 Server-side Fields

Example 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"
      }
    }
  }
}

            

❓ FAQ

Small Icon Issues

1. Why is the icon greyed out?

• On stock Android 5.0 and above, if your app's targetSdkVersion ≥ 21, the system will apply a mask color overlay to notification icons, which may cause them to appear grey. To ensure the icon displays clearly with defined contours, it's recommended to use an icon with no shadow, no gradient, and a transparent background, and name it mtpush_notification_icon. Replace the file in your project’s res/drawable directory with this icon. Also make sure to update all other icon assets under res (such as drawable-xxhdpi, etc.) to ensure consistency. When properly configured, the system will render the icon as a grey outline with the correct shape, avoiding display issues.

• Due to limitations on some systems (e.g., OnePlus phones and Google devices running Android 10), icon customization may not be supported or may not take effect.

• On Xiaomi devices, the launcher may cache icons. After completing the above configuration, you must restart the device before testing.

• Whether Xiaomi devices use the EngageLab channel or Xiaomi's own push channel, they must be switched to the native notification style for the icons to display correctly. Here’s how to switch:

2. Why does the new icon not take effect?

• The system or OEM push service may cache icons.
• Try uninstalling the app, rebooting the device, then reinstalling.

Right-side Icon / Large Image Issues

Why aren't icons or images displaying?

1. EngageLab Channel: Check whether the default notification builder interface is being called. If so, remove it and reinstall the app.
2. APNs (iOS): The right-side icon and large image are the same. The image appears only when pulling down in foreground mode; otherwise, only the icon shows.
3. FCM (Android): Initially shows the right-side icon; large image appears when notification is expanded.