Guide de configuration des icônes de notification push

Ce document vise à guider les utilisateurs sur la manière de configurer les petites icônes de la barre de notification, les icônes à droite et les grandes images.

📱 Méthodes de configuration des icônes iOS

Configuration de la petite icône

Accédez à Images.xcassets-AppIcon et définissez l'icône iPhone Notification avec les dimensions suivantes :

• 40 x 40px
• 60 x 60px

Configuration de l'icône à droite / grande image

✅ Versions prises en charge

• Pris en charge sur iOS 10 et supérieur à partir du SDK iOS EngageLab v3.0.0.

🧑‍💻 Configuration côté client

1. Créez un Service Extension.

2. Ajoutez le fichier mtpush-extension-ios-xxx.xcframework à votre projet Service Extension.

3. Ajoutez les deux frameworks suivants :

   • libz.tbd
   • libresolv.tbd

4. Appelez la méthode [mtpushSetAppkey:] pour définir l'AppKey (assurez-vous qu'elle correspond à l'AppKey utilisée lors de la création de l'application AppPush).

5. Dans le callback [didReceiveNotificationRequest:], récupérez le lien de l'image. Exemple de code ci-dessous :

              
              - (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"];
  //si existe
  if (attachmentPath) {
    //télécharger
    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];
}

            

🌐 Configuration côté serveur

Configurez les champs mutable-content et extras sous ios :

Exemple JSON :

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

            

🤖 Méthodes de configuration des icônes Android

✅ Versions prises en charge

Pris en charge à partir du SDK Android EngageLab v4.4.0.

📡 Prise en charge des canaux

📝 Remarques :

• OPPO : Lorsque la cible de push dépasse 20 et que la version ColorOS > 5.0, la première notification affiche une grande image en WiFi.
• Xiaomi : Depuis août 2023, la configuration de l'icône dynamique et de la grande image n'est plus prise en charge lors du push.

🎨 Configuration de la petite icône

🧑‍💻 Configuration côté client

• Si le projet contient la ressource res/drawable/mtpush_notification_icon, elle sera utilisée comme icône par défaut.
• Si cette ressource est absente, l'icône de l'application sera utilisée par défaut.

Exemple de configuration pour le canal 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" />

            

🌐 Configuration côté serveur

Exemple JSON :

              
              "notification": {
  "android": {
    "alert": "Hi, Push!",
    "title": "Envoyer vers 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"
    }
  }
}

            

🖼️ Configuration de l'icône à droite / grande image

🌐 Description des champs côté serveur

Exemple JSON :

              
              {
  "notification": {
    "android": {
      "alert": "Hi, Push!",
      "title": "Envoyer vers 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

Problèmes liés à la petite icône

1. Affichée en gris ?

• Sur Android natif 5.0 et supérieur, si la targetSdkVersion de l'application ≥ 21, le système applique automatiquement une couleur de masque sur les petites icônes de notification, les rendant grises. Pour garantir une bonne visibilité et reconnaissance, il est recommandé d'utiliser des icônes évidées sans ombre, dégradé ou fond, et de les nommer mtpush_notification_icon, en remplaçant le fichier du même nom dans le dossier res/drawable du projet. Assurez-vous également que tous les fichiers d'icônes liés à la notification (par exemple drawable-xxhdpi pour différentes densités) dans le dossier res soient uniformément remplacés par les nouvelles ressources. Après une configuration correcte, le système affichera une icône grise conforme, évitant les problèmes d'icône anormale ou floue.
• En raison des restrictions de certains systèmes (ex : téléphones OnePlus, téléphones Google sous Android 10), cela ne peut pas être résolu.
• Les lanceurs Xiaomi peuvent mettre en cache les icônes. Après configuration comme indiqué ci-dessus, redémarrez le téléphone et testez à nouveau.
• Pour les téléphones Xiaomi, que ce soit via le canal EngageLab ou Xiaomi, il est nécessaire de passer au style natif pour que cela prenne effet. La méthode de changement est la suivante :

2. Le changement d'icône n'est pas effectif ?

• Le système ou le service du fournisseur peut mettre en cache les icônes (cela peut se produire sur les téléphones Xiaomi et Meizu).
• Il est recommandé de désinstaller l'application, de redémarrer le téléphone, puis de réinstaller la nouvelle version.

Problèmes liés à l'icône à droite / grande image

Icône/image non affichée ?

1. Canal EngageLab : Vérifiez si l'interface de création de style de barre de notification par défaut a été appelée. Si oui, supprimez l'interface, désinstallez l'application et réessayez.
2. APNs (iOS) : L'icône à droite et la grande image sont la même image. Au premier plan, le menu déroulant de notification affiche la grande image, dans les autres cas seule l'icône à droite est affichée.
3. FCM (Android) : Avant l'expansion, l'icône à droite est affichée ; après expansion, la grande image est affichée.