Suscripciones a eventos

Aprende cómo funcionan las suscripciones a eventos del SDK de Braze para Banners, Content Cards y conmutadores de características. Este artículo explica cuándo se activa cada evento y qué debe hacer tu integración al respecto.

Requisitos previos

Estas son las versiones mínimas del SDK necesarias para usar las suscripciones a eventos:

Acerca de las suscripciones a eventos

Cada canal tiene un método de suscripción a eventos. Registras una devolución de llamada y el SDK la invoca cada vez que algo ocurre en ese canal, como una reproducción de caché, una actualización completada, un evento de análisis o un error. Cada evento te indica qué tipo de evento recibiste.

Los métodos de suscripción a eventos reemplazan a los métodos anteriores de suscripción a actualizaciones. Los métodos anteriores entregan solo los datos actuales. Los métodos de eventos también te indican por qué cambiaron los datos, cuándo se registran y envían los eventos de análisis, y cuándo falla una solicitud.

• web
• swift
• android

Canal	Método de suscripción a eventos	Reemplaza a	Guía
Banners	subscribeToBannersEvents	subscribeToBannersUpdates	Gestionar ubicaciones de Banner
Content Cards	subscribeToContentCardsEvents	subscribeToContentCardsUpdates	Crear Content Cards
Conmutadores de características	subscribeToFeatureFlagsEvents	subscribeToFeatureFlagsUpdates	Crear conmutadores de características

Importante

subscribeToBannersUpdates, subscribeToContentCardsUpdates y subscribeToFeatureFlagsUpdates están obsoletos y se eliminarán en una futura versión principal. Usa en su lugar el método de suscripción a eventos correspondiente.

Canal	Método de suscripción a eventos	Reemplaza a	Guía
Banners	braze.banners.subscribeToEvents(_:)	subscribeToUpdates(_:)	Gestionar ubicaciones de Banner
Content Cards	braze.contentCards.subscribeToEvents(_:)	subscribeToUpdates(_:)	Crear Content Cards
Conmutadores de características	braze.featureFlags.subscribeToEvents(_:)	subscribeToUpdates(_:)	Crear conmutadores de características

Para consultar la referencia completa de la API, visita la documentación de BrazeKit.

Cada canal también tiene una propiedad eventsStream que entrega los mismos eventos como un AsyncStream. Las aplicaciones Objective-C usan el método subscribeToEvents: en los mismos objetos de canal.

Importante

El método anterior subscribeToUpdates(_:) y los flujos de actualización por canal, como bannersStream, están obsoletos. Usa subscribeToEvents(_:) o eventsStream en su lugar.

Canal	Método de suscripción a eventos	Clase de evento	Reemplaza a	Guía
Banners	subscribeToBannersEvents	BannersEvent	subscribeToBannersUpdates	Gestionar ubicaciones de Banner
Content Cards	subscribeToContentCardsEvents	ContentCardsEvent	subscribeToContentCardsUpdates	Crear Content Cards
Conmutadores de características	subscribeToFeatureFlagsEvents	FeatureFlagsEvent	subscribeToFeatureFlagsUpdates	Crear conmutadores de características

Para consultar la referencia completa de la API, visita el KDoc del SDK de Braze para Android.

Importante

subscribeToBannersUpdates, subscribeToContentCardsUpdates, subscribeToFeatureFlagsUpdates y subscribeToBannersErrors están obsoletos. Usa en su lugar el método de suscripción a eventos correspondiente.

Nombres por plataforma

Este artículo usa los nombres de Web para los tipos de eventos, motivos de actualización, estados de reintento, acciones de análisis y motivos de error. Swift y Android usan los mismos conceptos con nombres que siguen las convenciones de cada plataforma.

Los demás motivos de actualización, estados de reintento, acciones de análisis y motivos de error siguen el mismo patrón. En Swift, el tipo de motivo de actualización es Braze.ChannelUpdateReason. En Android, cada canal tiene su propio tipo de motivo de actualización, como BannersUpdateReason.

Cómo se entregan los eventos

El SDK entrega los eventos en este orden:

1. Cuando te suscribes: el SDK invoca tu devolución de llamada de inmediato con un evento CACHE_REPLAY que contiene los datos en caché. Si el canal está deshabilitado, envía un evento ERROR con el motivo FEATURE_DISABLED en su lugar. En ambos casos, tu suscripción permanece activa.
2. Cuando la caché cambia: el SDK envía un evento CACHE_LOAD si la caché cambió sin una actualización del servidor, o un evento DATA_UPDATED si finalizó una actualización o modificaste los datos localmente.
3. Cuando tú o el SDK registran análisis: el SDK envía un evento IMPRESSION, CLICK o DISMISS con la acción ENQUEUED, y lo envía de nuevo con la acción FLUSHED después de que Braze lo acepte.
4. Cuando algo falla: el SDK envía un evento ERROR.

Tu devolución de llamada recibe el evento como su único argumento. Gestiona cada tipo de evento con un switch sobre el tipo de evento. En Web, el SDK registra un error que tu devolución de llamada lance y aún así entrega el evento a los demás suscriptores.

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

Nota

Invoca el método de suscripción a eventos después de inicializar el SDK. Invócalo antes de openSession() para que tu devolución de llamada reciba los eventos de la primera sesión. Si el SDK está deshabilitado, el método devuelve 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()

Nota

Mantén una referencia fuerte al cancelable devuelto. El SDK cancela la suscripción cuando el cancelable es liberado de la memoria. El SDK invoca tu controlador en el hilo 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)

Nota

El SDK invoca a tu suscriptor desde un hilo en segundo plano. Cambia al hilo principal antes de actualizar tu interfaz de usuario.

Instantáneas de caché

Los eventos CACHE_REPLAY, CACHE_LOAD y DATA_UPDATED incluyen una propiedad cacheSnapshot con los datos que el SDK tiene en caché para el usuario actual.

Cada instantánea también incluye lastSyncAt, la hora de la última sincronización exitosa para el usuario actual como un timestamp Unix en segundos. El valor es 0 si no ha habido una sincronización exitosa y null (nil en Swift) si el canal está deshabilitado.

Migrar desde suscripciones a actualizaciones

Los métodos de suscripción a actualizaciones aún funcionan, pero están obsoletos. Para migrar cada suscripción, después de cumplir los requisitos previos:

1. Reemplaza el método obsoleto con el método de suscripción a eventos para ese canal. Las tablas en Acerca de las suscripciones a eventos listan cada par.
2. Actualiza tu devolución de llamada. La devolución de llamada anterior recibía solo los datos actuales. La nueva devolución de llamada recibe un evento, así que comprueba el tipo de evento. Para los eventos CACHE_REPLAY, CACHE_LOAD y DATA_UPDATED, lee los datos de cacheSnapshot y vuelve a renderizar.
3. (Opcional) Gestiona los eventos ERROR para saber cuándo falla una actualización o una operación de análisis. En Android, reemplazan a subscribeToBannersErrors. Para más detalles, consulta Motivos de error.
4. Elimina la suscripción. En Android, pasa la nueva clase de evento (BannersEvent, ContentCardsEvent o FeatureFlagsEvent) a removeSingleSubscription, no la clase heredada …UpdatedEvent.

Para ver código de antes y después, consulta la guía de cada canal en las tablas de Acerca de las suscripciones a eventos.

Tipos de eventos

Cada evento es uno de los tipos de eventos de esta tabla. En Web, el evento tiene una propiedad type con uno de los valores ChannelEventType. En Swift y Android, cada tipo de evento es su propio case o clase. No todos los canales envían todos los tipos de eventos.

Motivos de actualización

Los eventos DATA_UPDATED incluyen un reason con uno de los valores ChannelUpdateReason.

Estados de reintento

Los eventos ERROR incluyen un retryState con uno de los valores RetryState. Te indica si el SDK reintentará la operación fallida y qué debes hacer.

Nota

Las actualizaciones no se reintentan automáticamente después de un error del cliente (una respuesta HTTP 4xx diferente a 429). El SDK reporta estos errores con el estado de reintento DO_NOT_RETRY. Aún así reintenta las respuestas HTTP 429, HTTP 5xx y los fallos de red.

Acciones de análisis

Los eventos IMPRESSION, CLICK y DISMISS incluyen una action con uno de los valores AnalyticsAction. Cada evento de análisis se envía dos veces: primero con ENQUEUED, luego con FLUSHED.

Motivos de error

Los eventos ERROR incluyen un reason con uno de los valores ChannelErrorReason. Cada motivo puede aplicarse a cualquier canal.

Consejo

Puedes recibir un error FEATURE_DISABLED cuando te suscribes antes de que el SDK haya recibido su primera configuración de Braze, incluso si el canal está habilitado para tu espacio de trabajo. Mantén tu suscripción activa y gestiona el evento DATA_UPDATED que le sigue.