Inscrições de eventos

Saiba como as inscrições de eventos do SDK da Braze funcionam para Banners, Content Cards e Feature Flags. Este artigo explica quando cada evento é disparado e o que sua integração deve fazer a respeito.

Pré-requisitos

Estas são as versões mínimas do SDK necessárias para usar inscrições de eventos:

Sobre inscrições de eventos

Cada canal possui um método de inscrição de eventos. Você registra um retorno de chamada, e o SDK o invoca toda vez que algo acontece naquele canal, como uma reprodução de cache, uma atualização concluída, um evento de análise de dados ou um erro. Cada evento informa qual tipo de evento você recebeu.

Os métodos de inscrição de eventos substituem os métodos mais antigos de inscrição de atualização. Os métodos antigos entregam apenas os dados atuais. Os métodos de eventos também informam por que os dados mudaram, quando eventos de análise de dados são registrados e enviados, e quando uma solicitação falha.

• web
• swift
• android

Canal	Método de inscrição de eventos	Substitui	Guia
Banners	subscribeToBannersEvents	subscribeToBannersUpdates	Gerenciar posicionamentos de Banner
Content Cards	subscribeToContentCardsEvents	subscribeToContentCardsUpdates	Criar Content Cards
Feature Flags	subscribeToFeatureFlagsEvents	subscribeToFeatureFlagsUpdates	Criar Feature Flags

Importante

subscribeToBannersUpdates, subscribeToContentCardsUpdates e subscribeToFeatureFlagsUpdates estão descontinuados e serão removidos em uma versão principal futura. Use o método de inscrição de eventos correspondente.

Canal	Método de inscrição de eventos	Substitui	Guia
Banners	braze.banners.subscribeToEvents(_:)	subscribeToUpdates(_:)	Gerenciar posicionamentos de Banner
Content Cards	braze.contentCards.subscribeToEvents(_:)	subscribeToUpdates(_:)	Criar Content Cards
Feature Flags	braze.featureFlags.subscribeToEvents(_:)	subscribeToUpdates(_:)	Criar Feature Flags

Para a referência completa da API, consulte a documentação do BrazeKit.

Cada canal também possui uma propriedade eventsStream que entrega os mesmos eventos como um AsyncStream. Apps em Objective-C usam o método subscribeToEvents: nos mesmos objetos de canal.

Importante

O método antigo subscribeToUpdates(_:) e os streams de atualização por canal, como bannersStream, estão descontinuados. Use subscribeToEvents(_:) ou eventsStream.

Canal	Método de inscrição de eventos	Classe de evento	Substitui	Guia
Banners	subscribeToBannersEvents	BannersEvent	subscribeToBannersUpdates	Gerenciar posicionamentos de Banner
Content Cards	subscribeToContentCardsEvents	ContentCardsEvent	subscribeToContentCardsUpdates	Criar Content Cards
Feature Flags	subscribeToFeatureFlagsEvents	FeatureFlagsEvent	subscribeToFeatureFlagsUpdates	Criar Feature Flags

Para a referência completa da API, consulte a KDoc do SDK Android da Braze.

Importante

subscribeToBannersUpdates, subscribeToContentCardsUpdates, subscribeToFeatureFlagsUpdates e subscribeToBannersErrors estão descontinuados. Use o método de inscrição de eventos correspondente.

Nomes por plataforma

Este artigo usa os nomes da Web para tipos de evento, motivos de atualização, estados de nova tentativa, ações de análise de dados e motivos de erro. Swift e Android usam os mesmos conceitos com nomes que seguem as convenções de cada plataforma.

Os demais motivos de atualização, estados de nova tentativa, ações de análise de dados e motivos de erro seguem o mesmo padrão. No Swift, o tipo de motivo de atualização é Braze.ChannelUpdateReason. No Android, cada canal possui seu próprio tipo de motivo de atualização, como BannersUpdateReason.

Como os eventos são entregues

O SDK entrega eventos nesta ordem:

1. Quando você se inscreve: O SDK invoca seu retorno de chamada imediatamente com um evento CACHE_REPLAY contendo os dados em cache. Se o canal estiver desativado, ele envia um evento ERROR com o motivo FEATURE_DISABLED. Em ambos os casos, sua inscrição permanece ativa.
2. Quando o cache muda: O SDK envia um evento CACHE_LOAD se o cache mudou sem uma atualização do servidor, ou um evento DATA_UPDATED se uma atualização foi concluída ou se você alterou os dados localmente.
3. Quando você ou o SDK registram análise de dados: O SDK envia um evento IMPRESSION, CLICK ou DISMISS com a ação ENQUEUED, e o envia novamente com a ação FLUSHED após a Braze aceitá-lo.
4. Quando algo falha: O SDK envia um evento ERROR.

Seu retorno de chamada recebe o evento como seu único argumento. Trate cada tipo de evento com um switch sobre o tipo do evento. Na Web, o SDK registra um erro que seu retorno de chamada lança e ainda entrega o evento para outros assinantes.

• 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

Chame o método de inscrição de eventos após inicializar o SDK. Chame-o antes de openSession() para que seu retorno de chamada receba os eventos da primeira sessão. Se o SDK estiver desativado, o método retorna 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

Mantenha uma referência forte ao cancellable retornado. O SDK cancela a inscrição quando o cancellable é desalocado. O SDK invoca seu handler na 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)

Nota

O SDK invoca seu assinante em uma thread em segundo plano. Mude para a thread principal antes de atualizar sua UI.

Snapshots de cache

Eventos CACHE_REPLAY, CACHE_LOAD e DATA_UPDATED incluem uma propriedade cacheSnapshot com os dados que o SDK armazenou em cache para o usuário atual.

Todo snapshot também inclui lastSyncAt, o horário da última sincronização bem-sucedida para o usuário atual como um timestamp Unix em segundos. O valor é 0 se nenhuma sincronização foi bem-sucedida e null (nil no Swift) se o canal estiver desativado.

Migrar das inscrições de atualização

Os métodos de inscrição de atualização ainda funcionam, mas estão descontinuados. Para migrar cada inscrição, depois de atender aos pré-requisitos:

1. Substitua o método descontinuado pelo método de inscrição de eventos para aquele canal. As tabelas em Sobre inscrições de eventos listam cada par.
2. Atualize seu retorno de chamada. O retorno de chamada antigo recebia apenas os dados atuais. O novo retorno de chamada recebe um evento, então verifique o tipo do evento. Para eventos CACHE_REPLAY, CACHE_LOAD e DATA_UPDATED, leia os dados de cacheSnapshot e renderize novamente.
3. (Opcional) Trate eventos ERROR para descobrir quando uma atualização ou uma operação de análise de dados falha. No Android, eles substituem subscribeToBannersErrors. Para mais detalhes, consulte Motivos de erro.
4. Remova a inscrição. No Android, passe a nova classe de evento (BannersEvent, ContentCardsEvent ou FeatureFlagsEvent) para removeSingleSubscription, e não a classe legada …UpdatedEvent.

Para exemplos de código antes e depois, consulte o guia de cada canal nas tabelas em Sobre inscrições de eventos.

Tipos de evento

Todo evento é um dos tipos de evento nesta tabela. Na Web, o evento tem uma propriedade type com um dos valores de ChannelEventType. No Swift e Android, cada tipo de evento é seu próprio case ou classe. Nem todo canal envia todos os tipos de evento.

Motivos de atualização

Eventos DATA_UPDATED incluem um reason com um dos valores de ChannelUpdateReason.

Estados de nova tentativa

Eventos ERROR incluem um retryState com um dos valores de RetryState. Ele indica se o SDK tentará novamente a operação que falhou e o que você deve fazer.

Nota

Atualizações não são tentadas novamente automaticamente após um erro de cliente (uma resposta HTTP 4xx diferente de 429). O SDK reporta esses erros com o estado de nova tentativa DO_NOT_RETRY. Ele ainda tenta novamente HTTP 429, HTTP 5xx e falhas de rede.

Ações de análise de dados

Eventos IMPRESSION, CLICK e DISMISS incluem uma action com um dos valores de AnalyticsAction. Cada evento de análise de dados é enviado duas vezes: primeiro com ENQUEUED, depois com FLUSHED.

Motivos de erro

Eventos ERROR incluem um reason com um dos valores de ChannelErrorReason. Todo motivo pode se aplicar a qualquer canal.

Dica

Você pode receber um erro FEATURE_DISABLED ao se inscrever antes que o SDK tenha recebido sua primeira configuração da Braze, mesmo que o canal esteja ativado para seu espaço de trabalho. Mantenha sua inscrição ativa e trate o evento DATA_UPDATED que se segue.