Abonnements aux événements

Découvrez comment fonctionnent les abonnements aux événements du SDK Braze pour les Banners, Content Cards et Feature Flags. Cet article explique quand chaque événement se déclenche et ce que votre intégration doit faire en conséquence.

Prérequis

Voici les versions minimales du SDK nécessaires pour utiliser les abonnements aux événements :

À propos des abonnements aux événements

Chaque canal dispose d’une méthode d’abonnement aux événements. Vous enregistrez un rappel, et le SDK l’appelle chaque fois que quelque chose se produit sur ce canal, comme une relecture du cache, une actualisation terminée, un événement analytique ou une erreur. Chaque événement vous indique le type d’événement reçu.

Les méthodes d’abonnement aux événements remplacent les anciennes méthodes d’abonnement aux mises à jour. Les anciennes méthodes ne fournissent que les données actuelles. Les méthodes d’événement vous indiquent également pourquoi les données ont changé, quand des événements analytiques sont enregistrés et envoyés, et quand une requête échoue.

• web
• swift
• android

Canal	Méthode d’abonnement aux événements	Remplace	Guide
Banners	subscribeToBannersEvents	subscribeToBannersUpdates	Gérer les emplacements Banner
Content Cards	subscribeToContentCardsEvents	subscribeToContentCardsUpdates	Créer des Content Cards
Feature Flags	subscribeToFeatureFlagsEvents	subscribeToFeatureFlagsUpdates	Créer des feature flags

Important

subscribeToBannersUpdates, subscribeToContentCardsUpdates et subscribeToFeatureFlagsUpdates sont dépréciées et seront supprimées dans une future version majeure. Utilisez la méthode d’abonnement aux événements correspondante à la place.

Canal	Méthode d’abonnement aux événements	Remplace	Guide
Banners	braze.banners.subscribeToEvents(_:)	subscribeToUpdates(_:)	Gérer les emplacements Banner
Content Cards	braze.contentCards.subscribeToEvents(_:)	subscribeToUpdates(_:)	Créer des Content Cards
Feature Flags	braze.featureFlags.subscribeToEvents(_:)	subscribeToUpdates(_:)	Créer des feature flags

Pour la référence API complète, consultez la documentation BrazeKit.

Chaque canal dispose également d’une propriété eventsStream qui fournit les mêmes événements sous forme d’AsyncStream. Les applications Objective-C utilisent la méthode subscribeToEvents: sur les mêmes objets de canal.

Important

L’ancienne méthode subscribeToUpdates(_:) et les flux de mise à jour par canal, tels que bannersStream, sont dépréciés. Utilisez subscribeToEvents(_:) ou eventsStream à la place.

Canal	Méthode d’abonnement aux événements	Classe d’événement	Remplace	Guide
Banners	subscribeToBannersEvents	BannersEvent	subscribeToBannersUpdates	Gérer les emplacements Banner
Content Cards	subscribeToContentCardsEvents	ContentCardsEvent	subscribeToContentCardsUpdates	Créer des Content Cards
Feature Flags	subscribeToFeatureFlagsEvents	FeatureFlagsEvent	subscribeToFeatureFlagsUpdates	Créer des feature flags

Pour la référence API complète, consultez la documentation KDoc du SDK Android Braze.

Important

subscribeToBannersUpdates, subscribeToContentCardsUpdates, subscribeToFeatureFlagsUpdates et subscribeToBannersErrors sont dépréciées. Utilisez la méthode d’abonnement aux événements correspondante à la place.

Noms par plateforme

Cet article utilise les noms Web pour les types d’événements, les raisons de mise à jour, les états de nouvelle tentative, les actions analytiques et les raisons d’erreur. Swift et Android utilisent les mêmes concepts avec des noms qui suivent les conventions de chaque plateforme.

Les autres raisons de mise à jour, états de nouvelle tentative, actions analytiques et raisons d’erreur suivent le même schéma. Sur Swift, le type de raison de mise à jour est Braze.ChannelUpdateReason. Sur Android, chaque canal possède son propre type de raison de mise à jour, comme BannersUpdateReason.

Comment les événements sont délivrés

Le SDK délivre les événements dans cet ordre :

1. Lorsque vous vous abonnez : le SDK appelle votre rappel immédiatement avec un événement CACHE_REPLAY contenant les données en cache. Si le canal est désactivé, il envoie à la place un événement ERROR avec la raison FEATURE_DISABLED. Dans les deux cas, votre abonnement reste actif.
2. Lorsque le cache change : le SDK envoie un événement CACHE_LOAD si le cache a changé sans actualisation serveur, ou un événement DATA_UPDATED si une actualisation est terminée ou si vous avez modifié les données localement.
3. Lorsque vous ou le SDK enregistrez des données analytiques : le SDK envoie un événement IMPRESSION, CLICK ou DISMISS avec l’action ENQUEUED, puis le renvoie avec l’action FLUSHED après que Braze l’a accepté.
4. Lorsqu’un problème survient : le SDK envoie un événement ERROR.

Votre rappel reçoit l’événement comme seul argument. Gérez chaque type d’événement avec un switch sur le type d’événement. Sur Web, le SDK consigne les erreurs que votre rappel lance et continue de délivrer l’événement aux autres abonnés.

• 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);

Remarque

Appelez la méthode d’abonnement aux événements après avoir initialisé le SDK. Appelez-la avant openSession() pour que votre rappel reçoive les événements de la première session. Si le SDK est désactivé, la méthode renvoie undefined.

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()

Remarque

Conservez une référence forte vers l’objet cancellable retourné. Le SDK annule l’abonnement lorsque le cancellable est libéré. Le SDK appelle votre gestionnaire sur le thread principal.

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)

Remarque

Le SDK appelle votre abonné depuis un thread en arrière-plan. Basculez sur le thread principal avant de mettre à jour votre interface utilisateur.

Instantanés du cache

Les événements CACHE_REPLAY, CACHE_LOAD et DATA_UPDATED incluent une propriété cacheSnapshot contenant les données que le SDK a mises en cache pour l’utilisateur actuel.

Chaque instantané inclut également lastSyncAt, l’horodatage de la dernière synchronisation réussie pour l’utilisateur actuel, exprimé en timestamp Unix en secondes. La valeur est 0 si aucune synchronisation n’a réussi et null (nil sur Swift) si le canal est désactivé.

Migrer depuis les abonnements aux mises à jour

Les méthodes d’abonnement aux mises à jour fonctionnent toujours, mais elles sont dépréciées. Pour migrer chaque abonnement, après avoir rempli les prérequis :

1. Remplacez la méthode dépréciée par la méthode d’abonnement aux événements correspondante. Les tableaux dans À propos des abonnements aux événements listent chaque paire.
2. Mettez à jour votre rappel. L’ancien rappel ne recevait que les données actuelles. Le nouveau rappel reçoit un événement, vérifiez donc le type d’événement. Pour les événements CACHE_REPLAY, CACHE_LOAD et DATA_UPDATED, lisez les données depuis cacheSnapshot et effectuez un nouveau rendu.
3. (Facultatif) Gérez les événements ERROR pour savoir quand une actualisation ou une opération analytique échoue. Sur Android, ils remplacent subscribeToBannersErrors. Pour plus de détails, consultez Raisons d’erreur.
4. Supprimez l’abonnement. Sur Android, passez la nouvelle classe d’événement (BannersEvent, ContentCardsEvent ou FeatureFlagsEvent) à removeSingleSubscription, et non l’ancienne classe …UpdatedEvent.

Pour consulter le code avant/après, reportez-vous au guide de chaque canal dans les tableaux de la section À propos des abonnements aux événements.

Types d’événements

Chaque événement correspond à l’un des types d’événements de ce tableau. Sur Web, l’événement possède une propriété type avec l’une des valeurs ChannelEventType. Sur Swift et Android, chaque type d’événement est son propre case ou classe. Tous les canaux n’envoient pas tous les types d’événements.

Raisons de mise à jour

Les événements DATA_UPDATED incluent une reason avec l’une des valeurs ChannelUpdateReason.

États de nouvelle tentative

Les événements ERROR incluent un retryState avec l’une des valeurs RetryState. Il vous indique si le SDK retentera l’opération échouée et ce que vous devez faire.

Remarque

Les actualisations ne sont pas retentées automatiquement après une erreur client (une réponse HTTP 4xx autre que 429). Le SDK signale ces erreurs avec l’état de nouvelle tentative DO_NOT_RETRY. Il retente tout de même les réponses HTTP 429, HTTP 5xx et les défaillances réseau.

Actions analytiques

Les événements IMPRESSION, CLICK et DISMISS incluent une action avec l’une des valeurs AnalyticsAction. Chaque événement analytique est envoyé deux fois : d’abord avec ENQUEUED, puis avec FLUSHED.

Raisons d’erreur

Les événements ERROR incluent une reason avec l’une des valeurs ChannelErrorReason. Chaque raison peut s’appliquer à tous les canaux.

Conseil

Vous pouvez recevoir une erreur FEATURE_DISABLED lorsque vous vous abonnez avant que le SDK ait reçu sa première configuration de Braze, même si le canal est activé pour votre workspace. Gardez votre abonnement actif et gérez l’événement DATA_UPDATED qui suit.