Panduan Konfigurasi Ikon Push

Dokumen ini bertujuan memandu pengguna dalam mengatur ikon kecil pada bar notifikasi, ikon sisi kanan, dan gambar besar.

📱 Cara Pengaturan Ikon iOS

Pengaturan Ikon Kecil

Masuk ke Images.xcassets-AppIcon dan atur ikon iPhone Notification dengan ukuran berikut:

• 40 x 40px
• 60 x 60px

Pengaturan Ikon Sisi Kanan / Gambar Besar

✅ Versi Didukung

• Didukung pada iOS 10 ke atas mulai EngageLab iOS SDK v3.0.0.

🧑‍💻 Pengaturan di Client

1. Buat layanan Service Extension.

2. Tambahkan file mtpush-extension-ios-xxx.xcframework ke proyek Service Extension Anda.

3. Tambahkan dua framework berikut:

   • libz.tbd
   • libresolv.tbd

4. Panggil metode [mtpushSetAppkey:] untuk mengatur AppKey (pastikan sama dengan AppKey yang digunakan saat membuat aplikasi AppPush).

5. Pada callback [didReceiveNotificationRequest:], ambil tautan gambar. Contoh kode:

              
              - (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"];
  // jika ada
  if (attachmentPath) {
    // unduh
    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];
}

            

🌐 Pengaturan di Server

Konfigurasikan field mutable-content dan extras di bawah ios:

Contoh JSON:

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

            

🤖 Cara Pengaturan Ikon Android

✅ Versi Didukung

Didukung mulai EngageLab Android SDK v4.4.0.

📡 Dukungan Channel

📝 Catatan:

• OPPO: Jika target push lebih dari 20 dan versi ColorOS > 5.0, notifikasi pertama akan menampilkan gambar besar saat menggunakan WiFi.
• Xiaomi: Mulai Agustus 2023, pengaturan ikon dinamis dan gambar besar tidak lagi didukung saat push.

🎨 Pengaturan Ikon Kecil

🧑‍💻 Pengaturan di Client

• Jika proyek memiliki resource res/drawable/mtpush_notification_icon, maka ikon tersebut akan digunakan sebagai ikon default.
• Jika resource ini tidak ada, ikon aplikasi akan digunakan sebagai default.

Contoh Konfigurasi Channel 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" />

            

🌐 Pengaturan di Server

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

            

🖼️ Pengaturan Ikon Sisi Kanan / Gambar Besar

🌐 Deskripsi Field Server

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

            

❓ FAQ

Permasalahan Ikon Kecil

1. Ikon tampil abu-abu?

• Pada Android asli 5.0 ke atas, jika targetSdkVersion aplikasi ≥ 21, sistem otomatis memberi warna masker pada ikon kecil notifikasi sehingga tampak abu-abu. Agar kontur dan keterbacaan baik, gunakan ikon hollow tanpa bayangan, gradasi, atau latar belakang, beri nama mtpush_notification_icon, lalu ganti file dengan nama yang sama di direktori res/drawable proyek. Pastikan semua file ikon terkait notifikasi (misal, drawable-xxhdpi untuk berbagai densitas) di direktori res telah diganti dengan resource ikon baru. Setelah pengaturan benar, sistem akan menampilkan ikon kontur abu-abu sesuai standar, menghindari masalah ikon tidak jelas.
• Karena pembatasan pada beberapa sistem (misal, ponsel OnePlus, Google dengan Android 10), hal ini tidak bisa diatasi.
• Launcher Xiaomi mungkin melakukan cache ikon. Setelah konfigurasi di atas, restart ponsel dan coba kembali.
• Untuk Xiaomi, baik channel EngageLab maupun channel Xiaomi, perlu beralih ke gaya native agar efektif. Cara beralih:

2. Perubahan ikon tidak efektif?

• Sistem atau layanan vendor dapat melakukan cache ikon (bisa terjadi pada Xiaomi dan Meizu).
• Disarankan uninstall aplikasi, restart ponsel, lalu install ulang versi terbaru.

Permasalahan Ikon Sisi Kanan / Gambar Besar

Ikon/Gambar tidak tampil?

1. Channel EngageLab: Pastikan builder gaya bar notifikasi default tidak dipanggil. Jika ya, hapus antarmuka tersebut, uninstall aplikasi, lalu coba kembali.
2. APNs (iOS): Ikon sisi kanan dan gambar besar menggunakan gambar yang sama. Pada foreground, dropdown notifikasi menampilkan gambar besar, sedangkan pada kondisi lain hanya ikon sisi kanan yang tampil.
3. FCM (Android): Sebelum diperluas, ikon sisi kanan yang tampil; setelah diperluas, gambar besar yang tampil.