Event-Abonnements

Erfahren Sie, wie Event-Abonnements im Braze SDK für Banner, Content Cards und Feature-Flags funktionieren. Dieser Artikel erklärt, wann jedes Event ausgelöst wird und was Ihre Integration damit tun sollte.

Voraussetzungen

Dies sind die minimalen SDK-Versionen, die für die Verwendung von Event-Abonnements erforderlich sind:

Über Event-Abonnements

Jeder Kanal verfügt über eine Event-Abonnement-Methode. Sie registrieren einen Callback, und das SDK ruft diesen jedes Mal auf, wenn etwas auf diesem Kanal passiert – zum Beispiel ein Cache-Replay, eine abgeschlossene Aktualisierung, ein Analytics-Event oder ein Fehler. Jedes Event teilt Ihnen mit, welche Art von Event Sie empfangen haben.

Die Event-Abonnement-Methoden ersetzen die älteren Update-Abonnement-Methoden. Die älteren Methoden liefern nur die aktuellen Daten. Die Event-Methoden teilen Ihnen außerdem mit, warum sich die Daten geändert haben, wann Analytics-Events protokolliert und gesendet werden und wann eine Anfrage fehlschlägt.

• web
• swift
• android

Kanal	Event-Abonnement-Methode	Ersetzt	Anleitung
Banner	subscribeToBannersEvents	subscribeToBannersUpdates	Banner-Platzierungen verwalten
Content Cards	subscribeToContentCardsEvents	subscribeToContentCardsUpdates	Content Cards erstellen
Feature-Flags	subscribeToFeatureFlagsEvents	subscribeToFeatureFlagsUpdates	Feature-Flags erstellen

Wichtig

subscribeToBannersUpdates, subscribeToContentCardsUpdates und subscribeToFeatureFlagsUpdates sind veraltet und werden in einer zukünftigen Hauptversion entfernt. Verwenden Sie stattdessen die entsprechende Event-Abonnement-Methode.

Kanal	Event-Abonnement-Methode	Ersetzt	Anleitung
Banner	braze.banners.subscribeToEvents(_:)	subscribeToUpdates(_:)	Banner-Platzierungen verwalten
Content Cards	braze.contentCards.subscribeToEvents(_:)	subscribeToUpdates(_:)	Content Cards erstellen
Feature-Flags	braze.featureFlags.subscribeToEvents(_:)	subscribeToUpdates(_:)	Feature-Flags erstellen

Die vollständige API-Referenz finden Sie in der BrazeKit-Dokumentation.

Jeder Kanal hat außerdem eine eventsStream-Eigenschaft, die dieselben Events als AsyncStream liefert. Objective-C-Apps verwenden die subscribeToEvents:-Methode auf denselben Kanalobjekten.

Wichtig

Die ältere subscribeToUpdates(_:)-Methode und die kanalspezifischen Update-Streams wie bannersStream sind veraltet. Verwenden Sie stattdessen subscribeToEvents(_:) oder eventsStream.

Kanal	Event-Abonnement-Methode	Event-Klasse	Ersetzt	Anleitung
Banner	subscribeToBannersEvents	BannersEvent	subscribeToBannersUpdates	Banner-Platzierungen verwalten
Content Cards	subscribeToContentCardsEvents	ContentCardsEvent	subscribeToContentCardsUpdates	Content Cards erstellen
Feature-Flags	subscribeToFeatureFlagsEvents	FeatureFlagsEvent	subscribeToFeatureFlagsUpdates	Feature-Flags erstellen

Die vollständige API-Referenz finden Sie im Braze Android SDK KDoc.

Wichtig

subscribeToBannersUpdates, subscribeToContentCardsUpdates, subscribeToFeatureFlagsUpdates und subscribeToBannersErrors sind veraltet. Verwenden Sie stattdessen die entsprechende Event-Abonnement-Methode.

Namen nach Plattform

Dieser Artikel verwendet die Web-Namen für Event-Typen, Aktualisierungsgründe, Wiederholungsstatus, Analytics-Aktionen und Fehlergründe. Swift und Android verwenden dieselben Konzepte mit Namen, die den Konventionen der jeweiligen Plattform entsprechen.

Die übrigen Aktualisierungsgründe, Wiederholungsstatus, Analytics-Aktionen und Fehlergründe folgen demselben Muster. In Swift ist der Typ für Aktualisierungsgründe Braze.ChannelUpdateReason. In Android hat jeder Kanal seinen eigenen Aktualisierungsgrund-Typ, wie z. B. BannersUpdateReason.

Wie Events zugestellt werden

Das SDK stellt Events in dieser Reihenfolge zu:

1. Wenn Sie abonnieren: Das SDK ruft Ihren Callback sofort mit einem CACHE_REPLAY-Event auf, das die zwischengespeicherten Daten enthält. Wenn der Kanal deaktiviert ist, wird stattdessen ein ERROR-Event mit dem Grund FEATURE_DISABLED gesendet. In beiden Fällen bleibt Ihr Abonnement aktiv.
2. Wenn sich der Cache ändert: Das SDK sendet ein CACHE_LOAD-Event, wenn sich der Cache ohne Server-Aktualisierung geändert hat, oder ein DATA_UPDATED-Event, wenn eine Aktualisierung abgeschlossen ist oder Sie die Daten lokal geändert haben.
3. Wenn Sie oder das SDK Analytics protokollieren: Das SDK sendet ein IMPRESSION-, CLICK- oder DISMISS-Event mit der Aktion ENQUEUED und sendet es erneut mit der Aktion FLUSHED, nachdem Braze es akzeptiert hat.
4. Wenn etwas fehlschlägt: Das SDK sendet ein ERROR-Event.

Ihr Callback empfängt das Event als einziges Argument. Behandeln Sie jede Art von Event mit einem Switch auf den Event-Typ. Im Web protokolliert das SDK einen Fehler, den Ihr Callback auslöst, und stellt das Event trotzdem an andere Abonnent:innen zu.

• web
• swift
• android

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import * as braze from "@braze/web-sdk";

// Register the subscription
const subscriptionId = braze.subscribeToBannersEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
      // Sent once, right away, with the cached data
      break;
    case braze.ChannelEventType.DATA_UPDATED:
      // A refresh finished or the data changed locally
      break;
    case braze.ChannelEventType.ERROR:
      // A request or analytics operation failed
      break;
  }
});

// Remove the subscription when you no longer need it
braze.removeSubscription(subscriptionId);

Hinweis

Rufen Sie die Event-Abonnement-Methode auf, nachdem Sie das SDK initialisiert haben. Rufen Sie sie vor openSession() auf, damit Ihr Callback die Events der ersten Sitzung empfängt. Wenn das SDK deaktiviert ist, gibt die Methode undefined zurück.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Register the subscription and keep a strong reference to it
let cancellable = AppDelegate.braze?.banners.subscribeToEvents { event in
  switch event {
  case .cacheReplay(let cacheSnapshot):
    // Sent once, right away, with the cached data
    break
  case .dataUpdated(let cacheSnapshot, let reason):
    // A refresh finished or the data changed locally
    break
  case .error(let reason, let retryState):
    // A request or analytics operation failed
    break
  default:
    break
  }
}

// Remove the subscription when you no longer need it
cancellable?.cancel()

Hinweis

Behalten Sie eine starke Referenz auf das zurückgegebene Cancellable. Das SDK beendet das Abonnement, wenn das Cancellable freigegeben wird. Das SDK ruft Ihren Handler auf dem Hauptthread auf.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Register the subscription
val subscriber = IEventSubscriber<BannersEvent> { event ->
  when (event) {
    is BannersEvent.CacheReplay -> {
      // Sent once, right away, with the cached data
    }
    is BannersEvent.DataUpdated -> {
      // A refresh finished or the data changed locally
    }
    is BannersEvent.ErrorEvent -> {
      // A request or analytics operation failed
    }
    else -> Unit
  }
}
Braze.getInstance(context).subscribeToBannersEvents(subscriber)

// Remove the subscription when you no longer need it
Braze.getInstance(context).removeSingleSubscription(subscriber, BannersEvent::class.java)

Hinweis

Das SDK ruft Ihren Subscriber von einem Hintergrund-Thread aus auf. Wechseln Sie zum Hauptthread, bevor Sie Ihre UI aktualisieren.

Cache-Snapshots

CACHE_REPLAY-, CACHE_LOAD- und DATA_UPDATED-Events enthalten eine cacheSnapshot-Eigenschaft mit den Daten, die das SDK für die aktuelle Nutzerin bzw. den aktuellen Nutzer zwischengespeichert hat.

Jeder Snapshot enthält außerdem lastSyncAt, den Zeitpunkt der letzten erfolgreichen Synchronisierung für die aktuelle Nutzerin bzw. den aktuellen Nutzer als Unix-Zeitstempel in Sekunden. Der Wert ist 0, wenn noch keine Synchronisierung erfolgreich war, und null (nil in Swift), wenn der Kanal deaktiviert ist.

Migration von Update-Abonnements

Die Update-Abonnement-Methoden funktionieren weiterhin, sind aber veraltet. Um jedes Abonnement zu migrieren, nachdem Sie die Voraussetzungen erfüllt haben:

1. Ersetzen Sie die veraltete Methode durch die Event-Abonnement-Methode für den jeweiligen Kanal. Die Tabellen unter Über Event-Abonnements listen jedes Paar auf.
2. Aktualisieren Sie Ihren Callback. Der alte Callback empfing nur die aktuellen Daten. Der neue Callback empfängt ein Event – prüfen Sie daher den Event-Typ. Für CACHE_REPLAY-, CACHE_LOAD- und DATA_UPDATED-Events lesen Sie die Daten aus cacheSnapshot und rendern neu.
3. (Optional) Behandeln Sie ERROR-Events, um herauszufinden, wann eine Aktualisierung oder ein Analytics-Vorgang fehlschlägt. Unter Android ersetzen sie subscribeToBannersErrors. Details finden Sie unter Fehlergründe.
4. Entfernen Sie das Abonnement. Unter Android übergeben Sie die neue Event-Klasse (BannersEvent, ContentCardsEvent oder FeatureFlagsEvent) an removeSingleSubscription, nicht die veraltete …UpdatedEvent-Klasse.

Vorher-Nachher-Code finden Sie in der Anleitung für jeden Kanal in den Tabellen unter Über Event-Abonnements.

Event-Typen

Jedes Event gehört zu einem der Event-Typen in dieser Tabelle. Im Web hat das Event eine type-Eigenschaft mit einem der ChannelEventType-Werte. In Swift und Android ist jeder Event-Typ ein eigener Case oder eine eigene Klasse. Nicht jeder Kanal sendet jeden Event-Typ.

Aktualisierungsgründe

DATA_UPDATED-Events enthalten einen reason mit einem der ChannelUpdateReason-Werte.

Wiederholungsstatus

ERROR-Events enthalten einen retryState mit einem der RetryState-Werte. Er teilt Ihnen mit, ob das SDK den fehlgeschlagenen Vorgang erneut versucht und was Sie tun sollten.

Hinweis

Aktualisierungen werden nach einem Client-Fehler (einer HTTP-4xx-Antwort außer 429) nicht automatisch wiederholt. Das SDK meldet diese Fehler mit dem Wiederholungsstatus DO_NOT_RETRY. Es versucht weiterhin HTTP 429, HTTP 5xx und Netzwerkfehler erneut.

Analytics-Aktionen

IMPRESSION-, CLICK- und DISMISS-Events enthalten eine action mit einem der AnalyticsAction-Werte. Jedes Analytics-Event wird zweimal gesendet: zuerst mit ENQUEUED, dann mit FLUSHED.

Fehlergründe

ERROR-Events enthalten einen reason mit einem der ChannelErrorReason-Werte. Jeder Grund kann auf jeden Kanal zutreffen.

Tipp

Sie können einen FEATURE_DISABLED-Fehler erhalten, wenn Sie abonnieren, bevor das SDK seine erste Konfiguration von Braze erhalten hat, selbst wenn der Kanal für Ihren Workspace aktiviert ist. Halten Sie Ihr Abonnement aktiv und behandeln Sie das darauffolgende DATA_UPDATED-Event.