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

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

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

📱 การตั้งค่าไอคอน iOS

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

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

• 40 x 40px
• 60 x 60px

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

✅ รุ่นที่รองรับ

• รองรับใน iOS 10 ขึ้นไปโดยใช้ SDK iOS ของ EngageLab v3.0.0 และเวอร์ชันหลังจากนั้น

🧑‍💻 การตั้งค่าฝั่งลูกค้า

1. สร้าง Service Extension target

2. นำเข้าไฟล์ mtpush-extension-ios-xxx.xcframework ไปยัง Service Extension target ของคุณ

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

   • libz.tbd
   • libresolv.tbd

4. เรียก [mtpushSetAppkey:] เพื่อตั้งค่า AppKey (ต้องตรงกับที่ใช้เมื่อสร้างแอปพลิเคชัน AppPush)

5. ในคอลแบ็ค [didReceiveNotificationRequest:] ดึง URL ของภาพ ตัวอย่างโค้ด:

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

            

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

คุณต้องตั้งค่า mutable-content และ extras ในส่วนของ ios:

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

✅ รุ่นที่รองรับ

รองรับตั้งแต่ SDK Android ของ EngageLab v4.4.0 เป็นต้นไป

📡 ภาพรวมการรองรับช่องทาง

📝 หมายเหตุ:

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

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

🧑‍💻 การตั้งค่าฝั่งลูกค้า

• หาก 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" />

            

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

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

            

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

🌐 ฟิลด์เซิร์ฟเวอร์

ตัวอย่าง JSON:

              
              {
  "notification":

            

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

ปัญหาไอคอนเล็ก

1. ทำไมไอคอนแสดงเป็นสีเทา?

• ใน Android 5.0 และเวอร์ชันที่สูงกว่า หาก targetSdkVersion ≥ 21 ระบบจะใช้สีมาสก์กับไอคอนการแจ้งเตือน ซึ่งอาจทำให้ไอคอนแสดงเป็นสีเทา เพื่อให้ไอคอนแสดงชัดเจน แนะนำให้ใช้ไอคอนที่ ไม่มีเงา ไม่มีการไล่สี และพื้นหลังโปร่งใส และตั้งชื่อว่า mtpush_notification_icon แทนที่ไอคอนนี้ในไดเรกทอรี res/drawable ของโปรเจกต์ และอัปเดตทรัพยากรไอคอนอื่น ๆ ในไดเรกทอรี res (เช่น drawable-xxhdpi) เพื่อให้สอดคล้องกัน หลังจากตั้งค่าอย่างถูกต้อง ระบบจะเรนเดอร์ไอคอนเป็นโครงร่างสีเทาเพื่อหลีกเลี่ยงปัญหา

• เนื่องจากข้อจำกัดของบางระบบ (เช่น โทรศัพท์ OnePlus และอุปกรณ์ Google ที่รัน Android 10) อาจไม่รองรับหรือไม่สามารถปรับแต่งไอคอนได้

• บนอุปกรณ์ Xiaomi ตัวเปิดอาจแคชไอคอน หลังจากตั้งค่าข้างต้น ต้อง รีสตาร์ทอุปกรณ์ ก่อนทดสอบ

• ไม่ว่าจะใช้อุปกรณ์ Xiaomi ผ่านช่องทาง EngageLab หรือช่องทางการแจ้งเตือนของ Xiaomi เอง ต้องเปลี่ยนเป็นรูปแบบการแจ้งเตือนแบบเนทีฟ เพื่อให้ไอคอนแสดงอย่างถูกต้อง วิธีเปลี่ยนมีดังนี้:

2. ทำไมไอคอนใหม่ไม่แสดงผล?

• ระบบหรือบริการแจ้งเตือน OEM อาจแคชไอคอน
• ลองถอนการติดตั้งแอปพลิเคชัน รีสตาร์ทอุปกรณ์ แล้วติดตั้งใหม่อีกครั้ง

ปัญหาไอคอนด้านขวา / ภาพขนาดใหญ่

ทำไมไอคอนหรือภาพไม่แสดง?

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