คู่มือการตั้งค่าไอคอนการแจ้งเตือน

เอกสารนี้มีเป้าหมายเพื่อแนะนำผู้ใช้เกี่ยวกับวิธีการตั้งค่าไอคอนเล็กในแถบการแจ้งเตือน, ไอคอนด้านขวา และรูปภาพขนาดใหญ่ alt text

📱 วิธีการตั้งค่าไอคอน iOS

การตั้งค่าไอคอนเล็ก

ไปที่ Images.xcassets-AppIcon และตั้งค่าไอคอน iPhone Notification ด้วยขนาดดังนี้:

  • 40 x 40px
  • 60 x 60px

alt text

การตั้งค่าไอคอนด้านขวา / รูปภาพขนาดใหญ่

✅ เวอร์ชันที่รองรับ

  • รองรับบน iOS 10 และสูงกว่าตั้งแต่ EngageLab iOS SDK v3.0.0

🧑‍💻 การตั้งค่าฝั่งไคลเอนต์

  1. สร้างบริการ Service Extension

  2. เพิ่มไฟล์ mtpush-extension-ios-xxx.xcframework ไปยังโปรเจค Service Extension

  3. เพิ่มเฟรมเวิร์กสองตัวดังนี้:

    • libz.tbd
    • libresolv.tbd
  4. เรียกใช้เมธอด [mtpushSetAppkey:] เพื่อกำหนดค่า AppKey (ตรวจสอบให้แน่ใจว่า AppKey ตรงกับ AppKey ที่ใช้เมื่อตั้งค่าแอปพลิเคชัน AppPush)

  5. ใน callback [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];
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

🌐 การตั้งค่าฝั่งเซิร์ฟเวอร์

กำหนดค่า mutable-content และ extras ภายใต้ ios:

ชื่อฟิลด์ ประเภท จำเป็น ฟิลด์หลัก คำอธิบาย
mutable-content boolean ไม่จำเป็น notification.ios เปิดใช้งานส่วนขยายการแจ้งเตือน ตั้งค่าเป็น true เพื่อรองรับ UNNotificationServiceExtension ของ iOS 10
extras JSON Object ไม่จำเป็น notification.ios ฟิลด์เพิ่มเติม คีย์ (เช่น 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 ✅ (รองรับโดยระบบ) ✅ (ยกเว้น Meizu) ✅ (รองรับโดยระบบ)
Xiaomi
Huawei ✅ (บริการ/ข้อมูล)
Honor ✅ (ไม่รองรับสำหรับการตลาด)
OPPO
FCM
Meizu
vivo

📝 หมายเหตุ:

  • OPPO: เมื่อเป้าหมายการแจ้งเตือนเกิน 20 และ ColorOS เวอร์ชัน > 5.0 การแจ้งเตือนแรกจะแสดงรูปภาพขนาดใหญ่ภายใต้ WiFi
  • Xiaomi: ตั้งแต่เดือนสิงหาคม 2023 การตั้งค่าไอคอนแบบไดนามิกและรูปภาพขนาดใหญ่ไม่ได้รับการรองรับในระหว่างการแจ้งเตือน

🎨 การตั้งค่าไอคอนเล็ก

🧑‍💻 การตั้งค่าฝั่งไคลเอนต์

  • หากโปรเจคมีทรัพยากร res/drawable/mtpush_notification_icon จะถูกใช้เป็นไอคอนเริ่มต้น
  • หากไม่มีทรัพยากรนี้ ไอคอนแอปพลิเคชันจะถูกใช้เป็นค่าเริ่มต้น

ตัวอย่างการกำหนดค่า FCM Channel:

<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.vendor สไตล์ไอคอนช่องทางผู้จำหน่าย ปัจจุบันรองรับเฉพาะ Huawei

ตัวอย่าง 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"
      }
    }
  }
}

            
โค้ดนี้โชว์เป็นหน้าต่างลอย

❓ คำถามที่พบบ่อย

ปัญหาเกี่ยวกับไอคอนเล็ก

1. แสดงเป็นสีเทา?

  • บน Android 5.0 และสูงกว่า หาก targetSdkVersion ของแอป ≥ 21 ระบบจะบังคับใช้สีมาสก์กับไอคอนเล็ก ทำให้แสดงเป็นสีเทา เพื่อให้มีความชัดเจนและดูดี แนะนำให้ใช้ไอคอนแบบโปร่งใสที่ไม่มีเงา, การไล่สี หรือพื้นหลัง และตั้งชื่อเป็น mtpush_notification_icon แทนที่ไฟล์ชื่อเดียวกันในไดเรกทอรี res/drawable ของโปรเจค นอกจากนี้ให้ตรวจสอบว่าไฟล์ไอคอนทั้งหมดที่เกี่ยวข้องกับการแจ้งเตือน (เช่น drawable-xxhdpi สำหรับความหนาแน่นต่างๆ) ในไดเรกทอรี res ถูกแทนที่ด้วยทรัพยากรไอคอนใหม่อย่างสม่ำเสมอ หลังจากตั้งค่าอย่างถูกต้อง ระบบจะแสดงไอคอนสีเทาที่สอดคล้องกัน หลีกเลี่ยงปัญหาไอคอนที่ผิดปกติหรือไม่ชัดเจน
  • เนื่องจากข้อจำกัดของระบบบางระบบ (เช่น โทรศัพท์ OnePlus, โทรศัพท์ Google ที่ใช้ Android 10) ไม่สามารถแก้ไขได้
  • ตัวเรียกใช้โทรศัพท์ Xiaomi อาจแคชไอคอน หลังจากตั้งค่าตามที่กำหนดข้างต้น ให้รีสตาร์ทโทรศัพท์และทดสอบอีกครั้ง
  • สำหรับโทรศัพท์ Xiaomi ไม่ว่าจะใช้ช่องทาง EngageLab หรือ Xiaomi ต้องเปลี่ยนเป็นสไตล์ดั้งเดิมเพื่อให้มีผล วิธีการเปลี่ยนดังนี้: alt text

2. การเปลี่ยนไอคอนไม่มีผล?

  • ระบบหรือบริการผู้จำหน่ายอาจแคชไอคอน (อาจเกิดขึ้นในโทรศัพท์ Xiaomi และ Meizu)
  • แนะนำให้ถอนการติดตั้งแอป, รีสตาร์ทโทรศัพท์ และติดตั้งเวอร์ชันใหม่อีกครั้ง

ปัญหาเกี่ยวกับไอคอนด้านขวา / รูปภาพขนาดใหญ่

ไอคอน/รูปภาพไม่แสดง?

  1. ช่องทาง EngageLab: ตรวจสอบว่าได้เรียกใช้ interface ตัวสร้างสไตล์แถบการแจ้งเตือนเริ่มต้นหรือไม่ หากใช่ ให้ลบ interface, ถอนการติดตั้งแอป และลองใหม่
  2. APNs (iOS): ไอคอนด้านขวาและรูปภาพขนาดใหญ่คือรูปภาพเดียวกัน ในโหมด foreground การดึงลงการแจ้งเตือนจะแสดงรูปภาพขนาดใหญ่ ในกรณีอื่นๆ จะแสดงเฉพาะไอคอนด้านขวา
  3. FCM (Android): ก่อนการขยายจะแสดงไอคอนด้านขวา; หลังการขยายจะแสดงรูปภาพขนาดใหญ่ alt text
icon
ติดต่อฝ่ายขาย