Content Cards

Nota

Este guia usa exemplos de código do SDK da Braze para Web 4.0.0+. Para fazer upgrade para a versão mais recente do SDK para Web, consulte o Guia de atualização do SDK.

Pré-requisitos

Antes de usar os Content Cards, é necessário integrar o SDK da Braze para web ao seu app. Nenhuma configuração adicional é necessária. Para criar sua própria interface, consulte o guia de personalização de Content Cards.

Nota

Alguns bloqueadores de anúncios e extensões de privacidade do navegador podem bloquear o script do SDK da Braze para web ou solicitações de rede relacionadas, o que pode impedir o carregamento dos Content Cards. Se você estiver usando o método de integração por CDN, considere mudar para o método de integração por NPM, que armazena as bibliotecas do SDK localmente no seu website e pode evitar alguns problemas relacionados a bloqueadores de anúncios.

Interface padrão do feed

Para usar a interface de Content Cards incluída, você precisa especificar onde exibir o feed no seu website.

Neste exemplo, temos um <div id="feed"></div> no qual queremos inserir o feed de Content Cards. Usaremos três botões para ocultar, exibir ou alternar (ocultar ou exibir com base no estado atual) o feed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<button id="toggle" type="button">Toggle Cards Feed</button>
<button id="hide" type="button">Hide Cards Feed</button>
<button id="show" type="button">Show Cards Feed</button>

<nav>
    <h1>Your Personalized Feed</h1>
    <div id="feed"></div>
</nav>

<script>
   const toggle = document.getElementById("toggle");
   const hide = document.getElementById("hide");
   const show = document.getElementById("show");
   const feed = document.getElementById("feed");

   toggle.onclick = function(){
      braze.toggleContentCards(feed);
   }

   hide.onclick = function(){
      braze.hideContentCards();
   }

   show.onclick = function(){
      braze.showContentCards(feed);
   }
</script>

Ao usar os métodos toggleContentCards(parentNode, filterFunction) e showContentCards(parentNode, filterFunction), se nenhum argumento for fornecido, todos os Content Cards serão exibidos em uma barra lateral com posição fixa na página. Caso contrário, o feed será inserido no parentNode especificado.

Consulte a documentação de referência do SDK para saber mais sobre a alternância de Content Cards.

Testando Content Cards na web

Você pode testar a integração dos Content Cards usando as ferramentas de desenvolvedor do seu navegador.

1. Crie uma Campaign de Content Cards e direcione ao seu usuário teste.
2. Faça login no website que possui a integração do Web SDK.
3. Abra o console do navegador. No Chrome, clique com o botão direito na página, selecione Inspecionar e depois selecione a guia Console.
4. Execute estes comandos no console:
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Tipos de cartão e propriedades

O modelo de dados dos Content Cards está disponível no SDK para Web e oferece os seguintes tipos de Content Cards: ImageOnly, CaptionedImage e ClassicCard. Cada tipo herda propriedades comuns de um modelo base Card e possui as seguintes propriedades adicionais.

Dica

Para registrar dados de Content Cards, consulte Registro de análise de dados.

Modelo base do cartão

Todos os Content Cards possuem estas propriedades compartilhadas:

Somente imagem

Cartões ImageOnly são imagens clicáveis em tamanho completo.

Imagem com legenda

Cartões CaptionedImage são imagens clicáveis em tamanho completo com texto descritivo acompanhando.

Clássico

O modelo ClassicCard pode conter uma imagem sem texto ou um texto com imagem.

Formatos de imagem

As imagens de Content Cards (incluindo GIFs) são renderizadas usando tags HTML <img> padrão. O suporte a GIFs depende das capacidades do navegador do usuário e não requer uma versão mínima do SDK para Web. Todos os navegadores modernos suportam a reprodução de GIFs nativamente.

Grupo de controle

Se você usar o feed padrão de Content Cards, as impressões e os cliques serão rastreados automaticamente.

Se você usar uma integração personalizada para Content Cards, será necessário registrar impressões quando um cartão de controle teria sido visto. Como parte desse processo, certifique-se de lidar com os cartões de controle ao registrar impressões em um teste A/B. Esses cartões estão em branco e, embora não sejam vistos pelos usuários, você ainda deve registrar as impressões para comparar o desempenho deles com os cartões que não são de controle.

Para determinar se um Content Card está no grupo de controle de um teste A/B, verifique a propriedade card.isControl (Web SDK v4.5.0+) ou verifique se o cartão é uma instância de ControlCard (card instanceof braze.ControlCard).

Métodos de cartão

Métodos de feed padrão

Use estes métodos ao exibir Content Cards com a interface padrão de feed da Braze:

Métodos de feed personalizado

Use estes métodos ao criar sua própria interface de Content Cards:

Para saber mais, consulte a documentação de referência do SDK.

Melhores práticas

Chame os métodos na ordem correta

Para feeds personalizados, os Content Cards são atualizados apenas no início da sessão se subscribeToContentCardsUpdates() for chamado antes de openSession(). Chame os métodos da Braze nesta ordem:

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

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

// Step 1: Initialize the SDK
braze.initialize("YOUR-API-KEY", { baseUrl: "YOUR-SDK-ENDPOINT" });

// Step 2: Subscribe to card updates
braze.subscribeToContentCardsUpdates((updates) => {
  const cards = updates.cards;
  renderCards(cards);
});

// Step 3: Identify the user
braze.changeUser("USER_ID");

// Step 4: Start the session
braze.openSession();

Use cartões em cache para manter o conteúdo entre carregamentos de página

Como subscribeToContentCardsUpdates() invoca seu retorno de chamada apenas quando há novas atualizações (por exemplo, no início da sessão), os cartões podem desaparecer do seu feed personalizado se o usuário atualizar a página no meio da sessão. Para evitar isso, use getCachedContentCards() para renderizar imediatamente os cartões do cache local, junto com a sua inscrição para novas atualizações:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

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

function renderCards(cards) {
  const container = document.getElementById("content-cards");
  container.textContent = "";
  const displayedCards = [];

  cards.forEach(card => {
    if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
      const cardElement = document.createElement("div");

      const h3 = document.createElement("h3");
      h3.textContent = card.title || "";
      cardElement.appendChild(h3);

      const p = document.createElement("p");
      p.textContent = card.description || "";
      cardElement.appendChild(p);

      if (card.imageUrl) {
        const img = document.createElement("img");
        img.src = card.imageUrl;
        img.alt = card.title || "";
        cardElement.appendChild(img);
      }

      if (card.url) {
        cardElement.addEventListener("click", () => {
          braze.logContentCardClick(card);
          braze.handleBrazeAction(card.url);
        });
      }

      container.appendChild(cardElement);
      displayedCards.push(card);
    }
  });

  if (displayedCards.length > 0) {
    braze.logContentCardImpressions(displayedCards);
  }
}

// Display cached cards immediately
const cached = braze.getCachedContentCards();
if (cached && cached.cards.length > 0) {
  renderCards(cached.cards);
}

// Subscribe to future updates
braze.subscribeToContentCardsUpdates((updates) => {
  renderCards(updates.cards);
});

Registre a análise de dados para feeds personalizados

Ao usar uma interface personalizada, impressões, cliques e descartes não são rastreados automaticamente. Você deve registrar cada evento manualmente:

• Impressões: Chame logContentCardImpressions([card1, card2, ...]) com um array de objetos de cartão quando os cartões ficarem visíveis para o usuário.
• Cliques: Chame logContentCardClick(card) quando um usuário interagir com um cartão.
• Comportamento ao clicar: Chame handleBrazeAction(card.url) para executar a ação de clique configurada no cartão (como navegar para uma URL ou registrar um evento personalizado).

Aviso

O argumento passado para logContentCardClick() deve ser um objeto Card original da Braze. Se você transformar ou reconstruir os dados do cartão (por exemplo, serializando e desserializando), os cliques não serão registrados e você verá o erro: “card must be a Card object.”

Usando o Google Tag Manager

O Google Tag Manager funciona injetando a CDN da Braze (uma versão do nosso SDK Web) diretamente no código do seu website, o que significa que todos os métodos do SDK estão disponíveis exatamente como se você tivesse integrado o SDK sem o Google Tag Manager, exceto ao implementar Content Cards.

Configurando Content Cards

• google tag manager
• manual

1
2
3

<script>
   window.braze.showContentCards();
</script>

1
2
3

body .ab-feed {
    width: 800px;
}

Atualizando modelos

Para atualizar para a versão mais recente do SDK Web da Braze, siga estas três etapas no seu dashboard do Google Tag Manager:

1. Atualize o modelo de tag
   Acesse a página Templates dentro do seu espaço de trabalho. Você deverá ver um ícone indicando que uma atualização está disponível.
   
   
   
   Clique no ícone e, após revisar a alteração, clique em Accept Update.
   
   
   
   
2. Atualize o número da versão
   Depois que o modelo de tag for atualizado, edite a tag Braze Initialization e atualize a versão do SDK para a versão major.minor mais recente. Por exemplo, se a versão mais recente for 4.1.2, insira 4.1. Você pode ver a lista de versões do SDK no nosso changelog.
   
   
   
   
3. QA e publicação
   Verifique se a nova versão do SDK está funcionando usando a ferramenta de depuração do Google Tag Manager antes de publicar uma atualização no seu contêiner de tags.

Solução de problemas

Ativar depuração de tags

Cada modelo de tag da Braze tem uma caixa de seleção opcional GTM Tag Debugging que pode ser usada para registrar mensagens de depuração no console JavaScript da sua página web.

Entrar no modo de depuração

Outra forma de ajudar a depurar sua integração com o Google Tag Manager é usar o recurso de modo de prévia do Google.

Isso ajudará a identificar quais valores estão sendo enviados da camada de dados da sua página web para cada tag da Braze acionada, e também explicará quais tags foram ou não acionadas.

Verificar a sequência de tags para eventos personalizados

Se eventos personalizados ou outras ações não estiverem sendo registrados na Braze, uma causa comum é uma condição de corrida em que uma tag de ação (como Custom Event ou Purchase) é disparada antes que a tag Braze Initialization tenha sido concluída. Para corrigir isso, configure a sequência de tags no GTM:

1. Abra a tag de ação que não está registrando corretamente.
2. Em Advanced Settings > Tag Sequencing, selecione A tag that fires before [this tag].
3. Escolha a tag Braze Initialization como a tag de configuração.

Isso garante que o SDK esteja totalmente inicializado antes que qualquer tag de ação tente enviar dados para a Braze.

Ativar registro detalhado

Para capturar registros detalhados para solução de problemas, você pode ativar o registro detalhado na sua integração com o Google Tag Manager. Esses registros aparecerão na guia Console das ferramentas de desenvolvedor do seu navegador.

Na sua integração com o Google Tag Manager, navegue até a tag Braze Initialization e selecione Enable Web SDK Logging.