Anleitung zur Konfiguration von Push-Benachrichtigungssymbolen

Dieses Dokument erklärt, wie Sie kleine Symbole in der Benachrichtigungsleiste, rechte Symbole sowie große Bilder konfigurieren.

📱 iOS Symbol-Konfiguration

Konfiguration des kleinen Symbols

Öffnen Sie Images.xcassets und wählen Sie AppIcon aus. Fügen Sie das iPhone Notification-Symbol mit folgenden Abmessungen hinzu:

• 40 x 40px
• 60 x 60px

Konfiguration des rechten Symbols / großen Bildes

✅ Unterstützte Versionen

Unterstützt ab iOS 10 sowie EngageLab iOS SDK ab Version 3.0.0.

🧑‍💻 Client-Konfiguration

1. Erstellen Sie eine Service Extension.
2. Fügen Sie die Datei mtpush-extension-ios-xxx.xcframework zu Ihrem Service Extension-Projekt hinzu.
3. Binden Sie die folgenden Frameworks ein:
   • libz.tbd
   • libresolv.tbd
4. Rufen Sie die Methode [mtpushSetAppkey:] auf, um den AppKey zu setzen (dieser muss mit dem bei der AppPush-Anwendung verwendeten AppKey übereinstimmen).
5. Im Callback [didReceiveNotificationRequest:] können Sie den Bild-Link abrufen. Beispielcode:

              
              - (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"];
  // sofern vorhanden
  if (attachmentPath) {
    // Herunterladen
    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-Konfiguration

Konfigurieren Sie die folgenden Felder unter ios:

Beispiel-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 Symbol-Konfiguration

✅ Unterstützte Versionen

Unterstützt ab EngageLab Android SDK Version 4.4.0.

📡 Kanalunterstützung

📝 Hinweise:

• OPPO: Wenn das Push-Ziel mehr als 20 beträgt und die ColorOS-Version größer als 5.0 ist, wird das erste Benachrichtigungsbild bei WLAN als großes Bild angezeigt.
• Xiaomi: Seit August 2023 werden dynamische Symbole und große Bilder beim Push nicht mehr unterstützt.

🎨 Konfiguration des kleinen Symbols

🧑‍💻 Client-Konfiguration

• Ist die Ressource res/drawable/mtpush_notification_icon im Projekt vorhanden, wird sie als Standard-Symbol verwendet.
• Fehlt diese Ressource, wird standardmäßig das App-Symbol genutzt.

Beispielkonfiguration für den FCM-Kanal:

              
              <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-Konfiguration

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

            

🖼️ Konfiguration des rechten Symbols / großen Bildes

🌐 Server-Feldbeschreibung

Beispiel-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

Probleme mit kleinen Symbolen

1. Wird das Symbol grau angezeigt?

• Ab Android 5.0 und targetSdkVersion ≥ 21 wird das kleine Benachrichtigungssymbol vom System mit einer Maskenfarbe belegt und erscheint grau. Verwenden Sie daher am besten konturierte, transparente Symbole ohne Schatten, Farbverläufe oder Hintergrund und benennen Sie diese Datei als mtpush_notification_icon. Ersetzen Sie die gleichnamigen Dateien im Verzeichnis res/drawable Ihres Projekts. Stellen Sie sicher, dass alle relevanten Symbol-Dateien (z. B. drawable-xxhdpi für verschiedene Dichten) im res-Verzeichnis einheitlich ersetzt werden. Nach korrekter Einrichtung zeigt das System ein konformes, graues Kontur-Symbol an und vermeidet Darstellungsprobleme.
• Auf bestimmten Systemen (z. B. OnePlus, Google Phones mit Android 10) kann dies nicht behoben werden.
• Xiaomi-Launcher können Symbole zwischenspeichern. Nach der Konfiguration wie oben das Gerät neu starten und erneut testen.
• Für Xiaomi: Unabhängig vom verwendeten Kanal (EngageLab oder Xiaomi) muss auf den nativen Stil umgestellt werden, damit die Änderung wirksam wird. Das Vorgehen finden Sie unten:

2. Symboländerung ohne Wirkung?

• Das System oder der Anbieterdienst kann Symbole zwischenspeichern (betrifft z. B. Xiaomi und Meizu).
• Es wird empfohlen, die App zu deinstallieren, das Gerät neu zu starten und dann die neue Version zu installieren.

Probleme mit rechtem Symbol / großem Bild

Symbol/Bild wird nicht angezeigt?

1. EngageLab-Kanal: Prüfen Sie, ob das Standard-Interface für den Benachrichtigungsleisten-Stil aufgerufen wurde. Entfernen Sie ggf. das Interface, deinstallieren Sie die App und testen Sie erneut.
2. APNs (iOS): Rechtes Symbol und großes Bild sind dasselbe Bild. Im Vordergrund wird beim Herunterziehen der Benachrichtigung das große Bild angezeigt, ansonsten nur das rechte Symbol.
3. FCM (Android): Vor dem Ausklappen wird das rechte Symbol angezeigt, nach dem Ausklappen erscheint das große Bild.