Ir para o conteúdo

Registro de análise de dados

Ao criar uma interface personalizada para Content Cards, você deve registrar manualmente os dados de análise, como impressões, cliques e dispensas, pois isso só é tratado automaticamente para os modelos de cartão padrão. Registrar esses eventos é uma parte padrão da integração de Content Cards e é essencial para relatórios precisos de Campaigns e faturamento. Para fazer isso, preencha sua interface personalizada com dados dos modelos de dados da Braze e, em seguida, registre manualmente os eventos. Depois de entender como registrar os dados de análise, você poderá ver as maneiras comuns pelas quais os clientes da Braze criam Content Cards personalizados.

Registro de análise de dados

Ao implementar seus Content Cards personalizados, você pode analisar os objetos de Content Card e extrair os dados do payload, como title, cardDescription e imageUrl. Em seguida, você pode usar os dados do modelo resultantes para preencher sua interface personalizada.

Para obter os modelos de dados dos Content Cards, inscreva-se para receber atualizações de Content Cards. Há duas propriedades que merecem atenção especial:

  • id: Representa a string de ID do Content Card. É o identificador exclusivo usado para registrar a análise de dados de Content Cards personalizados.
  • extras: Engloba todos os pares chave-valor do dashboard da Braze.

Todas as propriedades fora de id e extras são opcionais para análise em Content Cards personalizados. Para saber mais sobre o modelo de dados, consulte o artigo de integração de cada plataforma: Android, iOS, Web.

Registre uma função de retorno de chamada com subscribeToContentCardsEvents() para receber os cartões armazenados em cache e atualizações quando os cartões forem atualizados.

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

// - Available in version 7.0.0+
braze.subscribeToContentCardsEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
    case braze.ChannelEventType.CACHE_LOAD:
    case braze.ChannelEventType.DATA_UPDATED: {
      const cards = event.cacheSnapshot.contentCards.cards;
      // For example:
      cards.forEach(card => {
        if (card.isControl) {
          // Do not display the control card, but remember to call `logContentCardImpressions([card])`
        }
        else if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
          // Use `card.title`, `card.imageUrl`, etc.
        }
        else if (card instanceof braze.ImageOnly) {
          // Use `card.imageUrl`, etc.
        }
      });
      break;
    }
    case braze.ChannelEventType.ERROR:
      // Check `event.reason` and `event.retryState`
      break;
  }
});

braze.subscribeToContentCardsUpdates((updates) => {
  const cards = updates.cards;
// For example:
  cards.forEach(card => {
    if (card.isControl) {
      // Do not display the control card, but remember to call `logContentCardImpressions([card])`
    }
    else if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
      // Use `card.title`, `card.imageUrl`, etc.
    }
    else if (card instanceof braze.ImageOnly) {
      // Use `card.imageUrl`, etc.
    }
  })
});

braze.openSession();

Use subscribeToContentCardsEvents no Web SDK 7.0.0 e versões posteriores. subscribeToContentCardsUpdates é o padrão anterior, descontinuado a partir da versão 7.0.0.

Para a lista completa de eventos que você pode receber, consulte Criar Content Cards.

Etapa 1: Criar uma variável privada de assinante

Para se inscrever em eventos de cartão, primeiro declare uma variável privada na sua classe personalizada para armazenar seu assinante:

// - Available in version 44.0.0+
private IEventSubscriber<ContentCardsEvent> mContentCardsEventSubscriber;

private IEventSubscriber<ContentCardsUpdatedEvent> mContentCardsUpdatedSubscriber;

Etapa 2: Inscrever-se em eventos

Em seguida, adicione o código a seguir para se inscrever em eventos de Content Cards da Braze, normalmente dentro do Activity.onCreate() da sua atividade personalizada de Content Cards:

// - Available in version 44.0.0+
// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(mContentCardsEventSubscriber, ContentCardsEvent.class);
mContentCardsEventSubscriber = new IEventSubscriber<ContentCardsEvent>() {
    @Override
    public void trigger(ContentCardsEvent event) {
        if (event instanceof ContentCardsEvent.CacheReplay) {
            handleCards(((ContentCardsEvent.CacheReplay) event).getCacheSnapshot());
        } else if (event instanceof ContentCardsEvent.CacheLoad) {
            handleCards(((ContentCardsEvent.CacheLoad) event).getCacheSnapshot());
        } else if (event instanceof ContentCardsEvent.DataUpdated) {
            handleCards(((ContentCardsEvent.DataUpdated) event).getCacheSnapshot());
        }
    }
};
Braze.getInstance(context).subscribeToContentCardsEvents(mContentCardsEventSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(mContentCardsUpdatedSubscriber, ContentCardsUpdatedEvent.class);
mContentCardsUpdatedSubscriber = new IEventSubscriber<ContentCardsUpdatedEvent>() {
    @Override
    public void trigger(ContentCardsUpdatedEvent event) {
        List<Card> allCards = event.getAllCards();
    }
};
Braze.getInstance(context).subscribeToContentCardsUpdates(mContentCardsUpdatedSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

private void handleCards(ContentCardsCacheSnapshot cacheSnapshot) {
    List<Card> allCards = cacheSnapshot.getCards();
}

Etapa 3: Cancelar inscrição

Também recomendamos cancelar a inscrição quando sua atividade personalizada sair de exibição. Adicione o código a seguir ao método de ciclo de vida onDestroy() da sua atividade:

// - Available in version 44.0.0+
Braze.getInstance(context).removeSingleSubscription(mContentCardsEventSubscriber, ContentCardsEvent.class);

Braze.getInstance(context).removeSingleSubscription(mContentCardsUpdatedSubscriber, ContentCardsUpdatedEvent.class);

Etapa 1: Criar uma variável privada de assinante

Para se inscrever em eventos de cartão, primeiro declare uma variável privada na sua classe personalizada para armazenar seu assinante:

// - Available in version 44.0.0+
private var contentCardsEventSubscriber: IEventSubscriber<ContentCardsEvent>? = null

private var contentCardsUpdatedSubscriber: IEventSubscriber<ContentCardsUpdatedEvent>? = null

Etapa 2: Inscrever-se em eventos

Em seguida, adicione o código a seguir para se inscrever em eventos de Content Cards da Braze, normalmente dentro do Activity.onCreate() da sua atividade personalizada de Content Cards:

// - Available in version 44.0.0+
// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(contentCardsEventSubscriber, ContentCardsEvent::class.java)
contentCardsEventSubscriber = IEventSubscriber { event ->
    when (event) {
        is ContentCardsEvent.CacheReplay -> handleCards(event.cacheSnapshot)
        is ContentCardsEvent.CacheLoad -> handleCards(event.cacheSnapshot)
        is ContentCardsEvent.DataUpdated -> handleCards(event.cacheSnapshot)
        else -> {}
    }
}
Braze.getInstance(context).subscribeToContentCardsEvents(contentCardsEventSubscriber)
Braze.getInstance(context).requestContentCardsRefresh()

// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(contentCardsUpdatedSubscriber, ContentCardsUpdatedEvent::class.java)
contentCardsUpdatedSubscriber = IEventSubscriber { event ->
    val allCards = event.allCards
}
Braze.getInstance(context).subscribeToContentCardsUpdates(contentCardsUpdatedSubscriber)
Braze.getInstance(context).requestContentCardsRefresh()

private fun handleCards(cacheSnapshot: ContentCardsCacheSnapshot) {
    val allCards = cacheSnapshot.cards
}

Etapa 3: Cancelar inscrição

Também recomendamos cancelar a inscrição quando sua atividade personalizada sair de exibição. Adicione o código a seguir ao método de ciclo de vida onDestroy() da sua atividade:

// - Available in version 44.0.0+
Braze.getInstance(context).removeSingleSubscription(contentCardsEventSubscriber, ContentCardsEvent::class.java)

Braze.getInstance(context).removeSingleSubscription(contentCardsUpdatedSubscriber, ContentCardsUpdatedEvent::class.java)

Para saber quando cada evento é disparado e o que cada motivo de atualização, estado de nova tentativa, ação de análise de dados e motivo de erro significa, consulte Inscrições em eventos.

Use subscribeToContentCardsEvents no Android SDK 44.0.0 e versões posteriores. subscribeToContentCardsUpdates é o padrão anterior, descontinuado a partir da versão 44.0.0.

Para acessar o modelo de dados dos Content Cards, chame contentCards.cards na sua instância braze.

let cards: [Braze.ContentCard] = AppDelegate.braze?.contentCards.cards

Além disso, você também pode se inscrever em eventos de Content Cards para observar mudanças no cache, análise de dados e erros. Existem duas formas de fazer isso:

  1. Mantendo um cancellable; ou
  2. Mantendo um AsyncStream.

Cancellable

// - Available in version 19.0.0+
// This subscription is maintained through a Braze cancellable, which will observe for events until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
let cancellable = AppDelegate.braze?.contentCards.subscribeToEvents { [weak self] event in
  switch event {
  case .cacheReplay(let cacheSnapshot):
    // Initial cache snapshot, delivered immediately after subscribing
    break
  case .cacheLoad(let cacheSnapshot):
    // Cache loaded at the start of a user session (for example, after `changeUser()`)
    break
  case .dataUpdated(let cacheSnapshot, let reason):
    // Cache changed after the initial replay
    break
  case .impressionEvent(let card, let action):
    break
  case .clickEvent(let card, let action):
    break
  case .dismissEvent(let card, let action):
    break
  case .error(let reason, let retryState):
    break
  }
}

let cancellable = AppDelegate.braze?.contentCards.subscribeToUpdates { [weak self] contentCards in
  // Implement your completion handler to respond to updates in `contentCards`.
}

AsyncStream

// - Available in version 19.0.0+
Task {
  for await event in AppDelegate.braze?.contentCards.eventsStream ?? AsyncStream { _ in } {
    // Same switch statement as the cancellable example above.
  }
}

let stream: AsyncStream<[Braze.ContentCard]> = AppDelegate.braze?.contentCards.cardsStream

Use subscribeToEvents(_:) ou eventsStream no Swift SDK 19.0.0 e versões posteriores. subscribeToUpdates(_:) e cardsStream são o padrão anterior, descontinuado a partir da versão 19.0.0.

Para saber quando cada evento é disparado e o que cada motivo de atualização, estado de nova tentativa, ação de análise de dados e motivo de erro significa, consulte Inscrições em eventos.

Acessores de snapshot não bloqueantes

Use esses métodos para ler o estado atual armazenado em cache sem bloquear a thread de chamada. Cada handler de conclusão é sempre entregue na thread principal.

// All cached cards.
AppDelegate.braze?.contentCards.getCachedContentCards { cards in
  // Use `cards` here.
}

// Unviewed cards only (excludes control cards).
AppDelegate.braze?.contentCards.getUnviewedCards { cards in
  // Use `cards` here.
}

// Date of the last server sync for the current user (nil until the first sync completes).
AppDelegate.braze?.contentCards.getLastUpdate { date in
  // Use `date` here.
}
NSArray<BRZContentCardRaw *> *contentCards = AppDelegate.braze.contentCards.cards;

Além disso, se você quiser se inscrever em eventos de Content Cards, pode chamar subscribeToEvents:. Cada tipo de evento é mapeado para sua própria classe (por exemplo, BRZContentCardsDataUpdatedEvent), que você pode discriminar com isKindOfClass:. O replay inicial do cache e as atualizações de dados subsequentes são ambos mapeados para BRZContentCardsDataUpdatedEvent; verifique reason contra BRZContentCardsDataUpdatedEvent.cacheReplayReason para diferenciá-los:

// - Available in version 19.0.0+
// This subscription is maintained through a Braze cancellable, which will continue to observe for events until the subscription is cancelled.
BRZCancellable *cancellable = [self.braze.contentCards subscribeToEvents:^(BRZContentCardsEvent *event) {
  if ([event isKindOfClass:[BRZContentCardsDataUpdatedEvent class]]) {
    BRZContentCardsDataUpdatedEvent *updated = (BRZContentCardsDataUpdatedEvent *)event;
    if (updated.reason == BRZContentCardsDataUpdatedEvent.cacheReplayReason) {
      // Initial cache snapshot, delivered immediately after subscribing
    } else {
      // Cache changed after the initial replay
    }
  } else if ([event isKindOfClass:[BRZContentCardsCacheLoadEvent class]]) {
    // Cache loaded at the start of a user session (for example, after `changeUser()`)
  }
}];

BRZCancellable *cancellable = [self.braze.contentCards subscribeToUpdates:^(NSArray<BRZContentCardRaw *> *contentCards) {
  // Implement your completion handler to respond to updates in `contentCards`.
}];

Use subscribeToEvents: no Swift SDK 19.0.0 e versões posteriores. subscribeToUpdates: é o padrão anterior, descontinuado a partir da versão 19.0.0.

Para ler o estado atual armazenado em cache sem bloquear a thread de chamada, use os métodos a seguir. Cada handler de conclusão é entregue na thread principal.

// All cached cards.
[AppDelegate.braze.contentCards getCachedContentCardsWithCompletion:^(NSArray<BRZContentCardRaw *> *cards) {
  // Use `cards` here.
}];

// Unviewed cards only (excludes control cards).
[AppDelegate.braze.contentCards getUnviewedCardsWithCompletion:^(NSArray<BRZContentCardRaw *> *cards) {
  // Use `cards` here.
}];

// Date of the last server sync for the current user (nil until the first sync completes).
[AppDelegate.braze.contentCards getLastUpdateWithCompletion:^(NSDate * _Nullable date) {
  // Use `date` here.
}];

Para ouvir atualizações, inscreva-se nos eventos de atualização de Content Cards:

const subscription = Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, (update) => {
  const cards = update.cards;
  cards.forEach(card => {
    if (card.isControl) {
      // Do not display the control card, but remember to log an impression
    } else {
      // Use card.title, card.cardDescription, card.image, etc.
    }
  });
});

Para obter os dados mais recentes de Content Cards armazenados em cache:

import Braze from "@braze/react-native-sdk";

const cachedCards = await Braze.getCachedContentCards();

Para solicitar uma atualização manual dos Content Cards nos servidores da Braze:

Braze.requestContentCardsRefresh();

Registrando eventos

Registrar métricas valiosas como impressões, cliques e descartes é rápido e simples. Defina um listener de clique personalizado para lidar manualmente com essas análises.

Registre eventos de impressão quando os cartões são visualizados pelos usuários usando logContentCardImpressions:

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

braze.logContentCardImpressions([card1, card2, card3]);

Registre eventos de clique em cartões quando os usuários interagem com um cartão usando logContentCardClick:

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

braze.logContentCardClick(card);

O BrazeManager pode referenciar dependências do SDK da Braze, como a lista de objetos de Content Cards, para obter o Card e chamar os métodos de registro da Braze. Use a classe base ContentCardable para referenciar e fornecer dados facilmente ao BrazeManager.

Para registrar uma impressão ou clique em um cartão, chame Card.logClick() ou Card.logImpression() respectivamente.

Você pode registrar manualmente ou definir um Content Card como “descartado” na Braze para um cartão específico com isDismissed. Se um cartão já estiver marcado como descartado, ele não poderá ser marcado como descartado novamente.

Para criar um listener de clique personalizado, crie uma classe que implemente IContentCardsActionListener e registre-a com BrazeContentCardsManager. Implemente o método onContentCardClicked(), que será chamado quando o usuário clicar em um Content Card. Em seguida, instrua a Braze a usar seu listener de clique de Content Card.

Por exemplo:

BrazeContentCardsManager.getInstance().setContentCardsActionListener(new IContentCardsActionListener() {
  @Override
  public boolean onContentCardClicked(Context context, Card card, IAction cardAction) {
    return false;
  }

  @Override
  public void onContentCardDismissed(Context context, Card card) {

  }
});

Por exemplo:

BrazeContentCardsManager.getInstance().contentCardsActionListener = object : IContentCardsActionListener {
  override fun onContentCardClicked(context: Context, card: Card, cardAction: IAction): Boolean {
    return false
  }

  override fun onContentCardDismissed(context: Context, card: Card) {

  }
}

Implemente o protocolo BrazeContentCardUIViewControllerDelegate e defina seu objeto delegate como a propriedade delegate do seu BrazeContentCardUI.ViewController. Esse delegate lidará com o envio dos dados do seu objeto personalizado de volta para a Braze para serem registrados. Para um exemplo, consulte o tutorial de interface de Content Cards.

// Set the delegate when creating the Content Cards controller
contentCardsController.delegate = delegate

// Method to implement in delegate
func contentCard(
    _ controller: BrazeContentCardUI.ViewController,
    shouldProcess clickAction: Braze.ContentCard.ClickAction,
    card: Braze.ContentCard
  ) -> Bool {
  // Intercept the content card click action here.
  return true
}
// Set the delegate when creating the Content Cards controller
contentCardsController.delegate = delegate;

// Method to implement in delegate
- (BOOL)contentCardController:(BRZContentCardUIViewController *)controller
                shouldProcess:(NSURL *)url
                         card:(BRZContentCardRaw *)card {
  // Intercept the content card click action here.
  return YES;
}

Registre eventos de impressão quando os cartões são visualizados pelos usuários:

Braze.logContentCardImpression(card.id);

Registre eventos de clique em cartões quando os usuários interagem com um cartão:

Braze.logContentCardClicked(card.id);

Registre eventos de descarte quando um usuário descarta um cartão:

Braze.logContentCardDismissed(card.id);

Tratando o comportamento ao clicar

Quando um usuário clica em um Content Card em um feed personalizado, o comportamento ao clicar (como navegar para uma URL, deep linking ou registrar um evento personalizado) não é tratado automaticamente. Use handleBrazeAction para processar a URL do cartão e executar a ação ao clicar configurada, incluindo ações da Braze (URLs brazeActions://).

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

// In your card click handler
function onCardClick(card) {
  // Log the click
  braze.logContentCardClick(card);

  // Handle the on-click behavior
  if (card.url) {
    braze.handleBrazeAction(card.url);
  }
}
Parâmetro Descrição
url Uma URL válida ou uma URL de ação da Braze válida com o esquema brazeActions://.
openLinkInNewTab (Opcional) Se a URL deve ser aberta em uma nova guia. O padrão é false.

O comportamento ao clicar é tratado automaticamente pela interface padrão de Content Cards. Para implementações personalizadas, use a interface IContentCardsActionListener descrita em Registrando análise de dados.

O comportamento ao clicar é tratado automaticamente pela interface padrão de Content Cards. Para implementações personalizadas, use o protocolo BrazeContentCardUIViewControllerDelegate descrito em Registrando análise de dados.

Quando um usuário clica em um Content Card em um feed personalizado, o comportamento ao clicar não é tratado automaticamente. Após registrar o clique com Braze.logContentCardClicked(cardId), chame Braze.processContentCardClickAction(cardId) para processar deep links, URLs e ações brazeActions://. Para referência dos métodos, consulte Content Cards para React Native.

import Braze from "@braze/react-native-sdk";

function onCardPress(card) {
  Braze.logContentCardClicked(card.id);

  if (card.url) {
    Braze.processContentCardClickAction(card.id);
  }
}

Dispensas únicas maiores que impressões únicas

Se Dispensas únicas excede Impressões únicas, sua integração personalizada de Content Cards registrou dispensas sem registrar impressões para esses mesmos cartões. A interface padrão de Content Cards da Braze registra ambos automaticamente, então essa discrepância aparece apenas quando você usa uma interface personalizada.

Registre uma impressão cada vez que exibir um cartão e registre uma dispensa quando o usuário dispensá-lo. Para nomes de métodos e exemplos, consulte as seções de plataforma abaixo.

Análise de dados ausente nos Content Cards

Se os Content Cards aparecem corretamente no seu app, mas você não recebe nenhuma análise de dados de forma consistente (impressões, cliques etc.), provavelmente trata-se de um problema de integração SDK.

  • Visualizações personalizadas de Content Cards (Android, iOS, Web): A interface padrão da Braze registra impressões e cliques automaticamente em todas as plataformas. Se você está usando uma visualização ou implementação personalizada de Content Cards, é necessário chamar os métodos de registro apropriados explicitamente dentro do seu aplicativo. Consulte Registro de análise de dados para a sua plataforma. Para implementações web personalizadas especificamente, verifique se o SDK web da Braze está carregado, confira o console do navegador em busca de erros e confirme que os dados dos cartões estão sendo recebidos.
  • Inicialização do SDK e identificação do usuário: Certifique-se de que o SDK esteja totalmente inicializado antes de exibir os cartões. Os eventos são descartados silenciosamente (não enfileirados) se o SDK não estiver inicializado, estiver em modo de inicialização com postergação ou desabilitado por GDPR. O SDK registra análise de dados para usuários anônimos, mas métricas do dashboard como “impressões diárias únicas” exigem uma identidade de usuário resolvida, então chame changeUser antes de exibir os cartões sempre que possível.

ID do Content Card

Cada envio de Campaign para um destinatário gera um novo ID de Content Card. Se o mesmo usuário receber a Campaign novamente em um envio posterior, a Braze atribui um novo ID. Faça referência ao id do cartão ao registrar impressões, cliques e dispensas em implementações personalizadas.

New Stuff!