Skip to content

Registro de análise de dados

Ao construir uma interface personalizada para Content Cards, você deve registrar manualmente análises como impressões, cliques e dispensas, pois isso é tratado automaticamente apenas para modelos de cartão padrão. Registrar esses eventos é uma parte padrão da integração de Content Cards e é essencial para relatórios e faturamento precisos de Campaigns. 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 a análise de dados, você poderá ver as maneiras comuns pelas quais os clientes da Braze criam Content Cards personalizados.

Registrando análise de dados

Ao implementar seus Content Cards personalizados, você pode analisar os objetos de Content Card e extrair os dados de carga útil, como title, cardDescription e imageUrl. Em seguida, você pode usar os dados do modelo resultante 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. Este é o identificador único usado para registrar 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 de 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 para se inscrever em atualizações quando os cartões forem atualizados.

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";

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

Etapa 1: Crie uma variável de assinante privada

Para se inscrever em atualizações de cartões, primeiro declare uma variável privada na sua classe personalizada para armazenar seu assinante:

1
2

// subscriber variable
private IEventSubscriber<ContentCardsUpdatedEvent> mContentCardsUpdatedSubscriber;

Etapa 2: Inscreva-se para receber atualizações

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

1
2
3
4
5
6
7
8
9
10
11
12
13

// 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 of all Content Cards
        List<Card> allCards = event.getAllCards();

        // Your logic below
    }
};
Braze.getInstance(context).subscribeToContentCardsUpdates(mContentCardsUpdatedSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

Etapa 3: Cancele a 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:

1

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

Etapa 1: Crie uma variável de assinante privada

Para se inscrever em atualizações de cartões, primeiro declare uma variável privada na sua classe personalizada para armazenar seu assinante:

1

private var contentCardsUpdatedSubscriber: IEventSubscriber<ContentCardsUpdatedEvent>? = null

Etapa 2: Inscreva-se para receber atualizações

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

1
2
3
4
5
6
7
8
9
10

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

  // Your logic below
}
Braze.getInstance(context).subscribeToContentCardsUpdates(contentCardsUpdatedSubscriber)
Braze.getInstance(context).requestContentCardsRefresh(true)

Etapa 3: Cancele a 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:

1

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

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

1

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

Além disso, você também pode manter uma inscrição para observar alterações nos seus Content Cards. Isso pode ser feito de duas maneiras:

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

Cancellable

1
2
3
4
5
6

// This subscription is maintained through a Braze cancellable, which will observe for changes 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.subscribeToUpdates { [weak self] contentCards in
  // Implement your completion handler to respond to updates in `contentCards`.
}

AsyncStream

1

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

Acessores de snapshot não bloqueantes

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 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.
}

1

NSArray<BRZContentCardRaw *> *contentCards = AppDelegate.braze.contentCards.cards;

Além disso, se você quiser manter uma inscrição nos seus Content Cards, pode chamar subscribeToUpdates:

1
2
3
4

// This subscription is maintained through Braze cancellable, which will continue to observe for changes until the subscription is cancelled.
BRZCancellable *cancellable = [self.braze.contentCards subscribeToUpdates:^(NSArray<BRZContentCardRaw *> *contentCards) {
  // Implement your completion handler to respond to updates in `contentCards`.
}];

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 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:

1
2
3
4
5
6
7
8
9
10

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 de Content Cards mais recentes em cache:

1
2
3

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

const cachedCards = await Braze.getCachedContentCards();

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

1

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:

1
2
3

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

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

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

1
2
3

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 ao BrazeManager facilmente.

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:

1
2
3
4
5
6
7
8
9
10
11

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:

1
2
3
4
5
6
7
8
9

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 ver um exemplo, consulte o tutorial de interface de Content Cards.

1
2
3
4
5
6
7
8
9
10
11
12

// 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
}

1
2
3
4
5
6
7
8
9
10

// 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:

1

Braze.logContentCardImpression(card.id);

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

1

Braze.logContentCardClicked(card.id);

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

1

Braze.logContentCardDismissed(card.id);

Tratamento do 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 de clique configurada, incluindo ações da Braze (URLs brazeActions://).

1
2
3
4
5
6
7
8
9
10
11
12

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 válida da Braze 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 dos Content Cards. Para implementações personalizadas, use a interface IContentCardsActionListener descrita em Registro de análise de dados.

O comportamento ao clicar é tratado automaticamente pela interface padrão dos Content Cards. Para implementações personalizadas, use o protocolo BrazeContentCardUIViewControllerDelegate descrito em Registro de 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 de métodos, consulte Content Cards para React Native.

1
2
3
4
5
6
7
8
9

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!