Einrichten von Pushwoosh InboxKit für iOS

Verfügbar seit iOS SDK 7.0.40.

Pushwoosh InboxKit liefert einen modernen UIKit-Inbox-Bildschirm zusätzlich zum bestehenden Inbox-Backend. Sechs Standard-Zellenlayouts decken die gängigen Content-Card-Formen ab – von einfachen Bannern bis hin zu Bilderkarussells, Inline-Videos und Apple Wallet-Pässen – Inline-CTA-Buttons handhaben die häufigsten Interaktionen, und die gesamte Oberfläche ist für Subclassing offen, falls Sie ein maßgeschneidertes Aussehen benötigen.

Standard-InboxKit-Feed mit Banner-, beschrifteten, klassischen, Karussell-, Video- und Apple Wallet-Karten.

Wann sollte man InboxKit verwenden

Verwenden Sie InboxKit für jede neue iOS-Integration. Es ist der empfohlene Ersatz für das ältere Objective-C-Modul PushwooshInboxUI.

InboxKit bietet Ihnen:

Sechs integrierte Zellentypen – Banner, beschriftet, klassisch, Karussell, Video und Apple Wallet – werden pro Nachricht über displayType in der Payload ausgewählt oder per Code über attributes.forceCellKind erzwungen. Siehe Karten-Typen für die vollständige Liste. (Die Apple Wallet-Karte ist nur für iOS verfügbar.)
Inline-CTA-Buttons mit einem typisierten PushwooshInboxButtonAction-Enum (openURL, dismiss, markRead, custom). Das SDK behandelt die ersten drei automatisch; Ihr Delegate leitet custom an Ihre eigene Logik weiter.
Anpinn-Unterstützung: Nachrichten mit actionParams["pinned"] == true schweben an den Anfang des Feeds und zeigen ein Anpinn-Symbol an.
Wischen zum Löschen, Ziehen zum Aktualisieren, automatisches als gelesen markieren beim Verschwinden – alles umschaltbar über PushwooshInboxKitAttributes.
Persistenter Speicher: Löschungen und Gelesen-Status überleben einen Prozessneustart, auch wenn der Netzwerkaufruf noch nicht bestätigt wurde.
Eine offene PushwooshInboxCell-Basisklasse für vollständig benutzerdefinierte Layouts.

Der Serververtrag bleibt unverändert – dasselbe Pushwoosh-Inbox-Backend, Payloads und Dashboard-Tools funktionieren wie zuvor.

Wählen Sie Ihre Integrationsmethode

InboxKit mit Swift Package Manager einrichten – empfohlen für neue Projekte.
InboxKit mit CocoaPods einrichten – für Projekte, die bereits CocoaPods verwenden.

Karten-Typen

InboxKit wählt pro Nachricht ein Zellenlayout aus. Der Standard-Resolver liest displayType aus der Push-Payload – platzieren Sie es im data-Objekt, das das SDK unter actionParams liefert. Wenn displayType fehlt, greift der Resolver auf eine Heuristik zurück: Bild + kein Titel → Banner, Bild + Titel + Text → beschriftet, ansonsten klassisch. Um ein Layout für den gesamten Feed per Code zu erzwingen, setzen Sie attributes.forceCellKind.

Jedes Rich-Layout wird elegant zurückgestuft: Wenn ein obligatorisches Feld fehlt oder fehlerhaft ist, fällt die Karte auf classic zurück, anstatt einen leeren Platzhalter darzustellen (und ein WARN wird mit dem Grund protokolliert). classic ist der letzte Fallback und rendert, was auch immer die Nachricht enthält; es wird erwartet, dass der Nachrichten-Editor Titel, Text und Symbol ausfüllt.

`displayType`	Layout	Erforderliches Payload-Feld	Fällt zurück auf
`banner`	Bild über die gesamte Breite, kein Text	Bild (`inbox_image` oder `data.image`)	`classic`, wenn kein Bild vorhanden ist
`captioned`	Bild oben, Titel + Text darunter	Bild (`inbox_image` oder `data.image`), Nachricht `title` und `content`	`classic`, wenn Bild, Titel oder Text fehlt
`classic`	Farbiger Initial-Avatar + Titel + Text	— (Titel, Text und Symbol erwartet)	—
`carousel`	Wischbare Galerie mit mehreren Bildern	Nachricht `title` und `content`, `data.carousel` (1–5 Folien)	`classic`, wenn keine Folien oder kein Titel/Text vorhanden sind
`video`	Poster mit Wiedergabe-Symbol, Vollbild-Player bei Tippen	`data.video` (`url` + optional `poster`)	`classic`, wenn kein Deskriptor vorhanden ist
`wallet`	”Zu Apple Wallet hinzufügen”-Button (nur iOS)	`data.wallet` (`.pkpass` URL)	`classic`, wenn keine Pass-URL vorhanden ist

InboxKit Banner-Karte — **Banner-Karte**

InboxKit beschriftete Karte — **Beschriftete Karte**

InboxKit klassische Karte — **Klassische Karte**

InboxKit Karussell-Karte — **Karussell-Karte**

InboxKit Apple Wallet-Karte — **Apple Wallet-Karte**

Banner-, beschriftete und klassische Karten werden durch die Standard-Nachrichtenfelder (Bild, Titel, Text) sowie das optionale buttons-Array gesteuert – siehe Inline-CTA-Buttons hinzufügen. Die Karussell-, Video- und Apple Wallet-Karten enthalten zusätzliche strukturierte Daten in data, die unten dokumentiert sind.

Karussell-Karte

Ein Karussell rendert mehrere Bilder aus einer einzigen Nachricht – eine wischbare Galerie mit optionalen Bildunterschriften pro Folie und Zielen beim Tippen. Die Folien befinden sich in data.carousel. Jede Folie benötigt ein image; title (überlagerte Bildunterschrift) und url (Deep Link, der beim Tippen geöffnet wird) sind optional. Eine Folie ohne Bild wird verworfen; ein Tippen auf eine Folie ohne url fällt auf die Standard-Zeilenaktion der Nachricht zurück. Es werden maximal 5 Folien angezeigt – zusätzliche Folien werden verworfen (eine Folie ohne Bild verbraucht keinen Platz). Der Nachrichtentitel (title) und der Inhalt (content) sind für dieses Layout obligatorisch; ohne sie wird die Karte auf classic zurückgestuft.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "New arrivals",
      "content": "Swipe through this week's drops",
      "inbox_days": 7,
      "data": {
        "displayType": "carousel",
        "carousel": [
          { "image": "https://cdn.example.com/inbox/1.jpg", "title": "New in", "url": "myapp://product/1" },
          { "image": "https://cdn.example.com/inbox/2.jpg", "title": "On sale", "url": "myapp://product/2" },
          { "image": "https://cdn.example.com/inbox/3.jpg" }
        ]
      },
      "platforms": [1]
    }]
  }
}

Video-Karte

Eine Video-Karte zeigt ein Posterbild mit einem Wiedergabe-Symbol; ein Tippen darauf öffnet einen Vollbild-Player (Ton an, auch wenn der Stummschalter aktiviert ist). Der Deskriptor befindet sich in data.video: url ist erforderlich und muss ein http/https-Stream oder eine Datei sein; poster ist ein optionales Vorschaubild.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Watch the reveal",
      "content": "Tap to play",
      "inbox_days": 7,
      "data": {
        "displayType": "video",
        "video": {
          "url": "https://cdn.example.com/inbox/clip.mp4",
          "poster": "https://cdn.example.com/inbox/poster.jpg"
        }
      },
      "platforms": [1]
    }]
  }
}

Apple Wallet-Karte

Die Apple Wallet-Karte zeigt ein optionales Hero-Image, einen Titel und einen Text über dem offiziellen Zu Apple Wallet hinzufügen-Button. Ein Tippen auf den Button lädt die .pkpass-Datei herunter und präsentiert das Systemblatt zum Hinzufügen von Pässen. Verwenden Sie es, um Gutscheine, Kundenkarten, Tickets oder Bordkarten direkt aus dem Posteingang zu liefern. Die Karte ist nur für iOS / Mac Catalyst verfügbar – auf anderen Plattformen wird die Nachricht als klassische Karte gerendert.

Die Pass-URL befindet sich in data.wallet, entweder als reiner String oder als Objekt mit einem pass-Feld. Ein optionales data.image fügt das Hero-Image hinzu. Der Button verbirgt sich automatisch, wenn keine Pass-URL vorhanden ist oder das Gerät keine Pässe hinzufügen kann.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Your loyalty card is ready",
      "content": "Add it to Apple Wallet in one tap",
      "inbox_days": 7,
      "data": {
        "displayType": "wallet",
        "image": "https://cdn.example.com/inbox/loyalty.png",
        "wallet": "https://passes.example.com/v1/passes/pass.com.example.loyalty/abc123?token=…"
      },
      "platforms": [1]
    }]
  }
}

Das Ergebnis wird an Ihren Delegate gemeldet:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didAddWalletPassFor message: PWInboxMessageProtocol) {
        // Der Pass befindet sich jetzt im Wallet des Benutzers – zeigen Sie bei Bedarf eine Bestätigung an.
    }

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didFailToAddWalletPassFor message: PWInboxMessageProtocol,
                  error: Error?) {
        // Download fehlgeschlagen – zeigen Sie eine Wiederholung an, protokollieren Sie usw.
    }
}

Beide Callbacks sind optional (sie haben standardmäßig leere Implementierungen). Wenn ein Benutzer das Systemblatt abbricht, ist dies weder ein Erfolg noch ein Fehlschlag, daher wird in diesem Fall kein Callback ausgelöst.

Barrierefreiheit

InboxKit-Zellen sind von Haus aus VoiceOver-fähig. Banner-, beschriftete und klassische Karten legen ihren Titel, Text und ihr Datum über die zugrunde liegenden Labels offen, und Inline-CTA-Buttons lesen ihre eigenen Titel vor. Die Rich-Karten fügen explizite Semantik hinzu:

Video – das Poster wird als einzelnes Button-Element mit der Bezeichnung „Video abspielen“ (Eigenschaften .button + .startsMediaSession) bereitgestellt, sodass VoiceOver es als Mediensteuerung anstelle eines einfachen Bildes ankündigt.
Karussell – jede Folie ist ein Button-Element, dessen Barrierefreiheits-Label die Bildunterschrift der Folie ist, oder „Folie“, wenn keine vorhanden ist. Der Seitenindikator kündigt die aktuelle Position als „n von gesamt“ an.
Apple Wallet – der Zu Apple Wallet hinzufügen-Button ist Apples Standard-PKAddPassButton, der sein eigenes lokalisiertes VoiceOver-Label trägt.

Für UI-Tests und Automatisierung sind zwei stabile accessibilityIdentifier gesetzt: inboxkit.video.play auf dem Video-Poster und inboxkit.wallet.add auf dem Wallet-Button.

Benutzerdefinierte Daten aus einer Nachricht lesen

Damit ein Push im Posteingang erscheint, muss die createMessage-Anfrage der Messages API inbox_image, inbox_date oder inbox_days enthalten – ohne eines dieser Felder wird der Push als reguläre Benachrichtigung zugestellt und erreicht niemals den Posteingangs-Feed. Freiform-benutzerdefinierte Daten gehören unter den data-Schlüssel, den das SDK als u-Parameter an den Client liefert:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Summer sale",
      "content": "30% off everything — limited time only",
      "inbox_image": "https://cdn.example.com/inbox/summer.png",
      "inbox_days": 7,
      "data": {
        "displayType": "captioned",
        "promo_id": "SUMMER2026",
        "screen": "promo_details"
      },
      "platforms": [1]
    }]
  }
}

Das SDK stellt dieses Objekt in der Posteingangsnachricht über actionParams zur Verfügung. Lesen Sie es aus dem Delegate, wenn der Benutzer auf die Zeile oder einen Inline-CTA tippt:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didSelect message: PWInboxMessageProtocol) -> Bool {
        guard let params = message.actionParams as? [String: Any] else { return true }

        // Das benutzerdefinierte `data`-Objekt kommt unter dem Schlüssel „u“ an –
        // entweder als verschachteltes Dictionary oder als JSON-kodierter String,
        // je nachdem, wie die Payload im Vorfeld erstellt wurde.
        let custom: [String: Any]? = {
            if let dict = params["u"] as? [String: Any] { return dict }
            if let raw = params["u"] as? String,
               let bytes = raw.data(using: .utf8),
               let parsed = try? JSONSerialization.jsonObject(with: bytes) as? [String: Any] {
                return parsed
            }
            return nil
        }()

        if let promoId = custom?["promo_id"] as? String {
            navigateToPromo(promoId)
            return false   // wir haben das Tippen behandelt; das SDK sollte die Standardaktion nicht ausführen
        }
        return true
    }
}

Dieselbe actionParams["u"]-Suche funktioniert innerhalb von inboxKit(_:didTapButton:onMessage:) für Inline-CTA-Buttons. Für die typisierten CTA-Fälle (openURL, dismiss, markRead) führt das SDK bereits die Standardaktion aus – geben Sie true zurück, um dieses Verhalten beizubehalten, oder false, um es zu unterdrücken und Ihre eigene auszuführen.

Inline-CTA-Buttons hinzufügen

Eine Nachricht kann bis zu drei Inline-Call-to-Action-Buttons enthalten. Buttons befinden sich neben anderen benutzerdefinierten Daten innerhalb von data als buttons-Array. Das SDK rendert sie automatisch in den beschrifteten und klassischen Zellen:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "New promo card",
      "content": "Tap a button to claim or save",
      "inbox_image": "https://cdn.example.com/inbox/promo.png",
      "inbox_days": 7,
      "data": {
        "displayType": "captioned",
        "promo_id": "SUMMER2026",
        "buttons": [
          { "title": "Claim", "url": "https://example.com/promo/SUMMER2026" },
          { "title": "Read",  "action": "markRead" },
          { "title": "Save",  "action": "custom", "tag": "save_promo" }
        ]
      },
      "platforms": [1]
    }]
  }
}

Jedes Button-Objekt hat diese Felder:

Feld	Typ	Wann
`title`	string	Erforderlich. Sichtbare Button-Beschriftung.
`url`	string	Eine nicht leere, analysierbare URL erzeugt eine `openURL`-Aktion. Das SDK öffnet sie über `UIApplication.shared.open`, es sei denn, Ihr Delegate unterdrückt dies.
`action`	string	Explizites Aktions-Token: `dismiss` (entfernt die Nachricht aus dem Feed), `markRead` (markiert die Nachricht als gelesen) oder `custom` (vom Host behandelt). Groß- und Kleinschreibung wird nicht beachtet.
Alles andere	any	Wenn die Aktion `custom` ist, wird jeder Schlüssel im Button-Objekt außer `title` und `action` als benutzerdefinierte Payload an Ihren Delegate weitergeleitet – einigen Sie sich mit dem Marketer auf einen Schlüssel (z. B. `tag`) und führen Sie die Verteilung darauf basierend durch.

Auflösungspriorität: zuerst das explizite action-Token, dann url, falls nicht leer, andernfalls fällt der Button in custom und trägt die volle Payload (ohne title und action).

Fangen Sie Taps von Ihrem Delegate ab. Die button.action-Eigenschaft ist das typisierte PushwooshInboxButtonAction-Enum:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didTapButton button: PushwooshInboxButton,
                  onMessage message: PWInboxMessageProtocol) -> Bool {
        switch button.action {
        case .openURL(let url):
            // Standardverhalten ist in Ordnung – lassen Sie das SDK die URL öffnen.
            return true

        case .dismiss, .markRead:
            // Das SDK behandelt beides. Geben Sie false zurück, wenn Sie es überschreiben möchten.
            return true

        case .custom(let payload):
            // Vom Marketer definierter benutzerdefinierter Button. Führen Sie die Verteilung basierend auf einem vereinbarten Schlüssel durch.
            if let tag = payload["tag"] as? String {
                switch tag {
                case "save_promo":
                    saveCurrentPromoLocally(message: message)
                default:
                    break
                }
            }
            return true   // wird für custom ignoriert – das SDK führt hier niemals eine Standardaktion aus
        }
    }
}