Cartões de conteúdo

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 poder usar os Content Cards, você precisará integrar o Braze Web SDK ao seu app. No entanto, 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 Braze Web SDK 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 site e pode evitar alguns problemas relacionados a bloqueadores de anúncios.

Interface do feed padrão

Para usar a interface de Content Cards incluída, você precisará especificar onde mostrar o feed no seu site.

Neste exemplo, temos um <div id="feed"></div> no qual queremos colocar o feed dos Content Cards. Usaremos três botões para ocultar, mostrar ou alternar (ocultar ou mostrar 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 mostrados em uma barra lateral de posição fixa no lado direito da página. Caso contrário, o feed será colocado na opção parentNode especificada.

Consulte os documentos de referência do SDK para saber mais sobre a alternância de Content Cards.

Testando Content Cards na web

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

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

Tipos e propriedades do cartão

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

Dica

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

Modelo de cartão base

Todos os Content Cards têm essas propriedades compartilhadas:

Somente imagem

Os cartões ImageOnly são imagens clicáveis em tamanho real.

Imagem legendada

Os cartões CaptionedImage são imagens clicáveis em tamanho real com texto descritivo.

Clássico

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

Grupo de controle

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

Se você usar uma integração personalizada para Content Cards, precisará registrar impressões quando um cartão de controle tiver sido visto. Nesse caso, lide 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 ControlCard (card instanceof braze.ControlCard).

Métodos do cartão

Métodos do feed padrão

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

Métodos do feed personalizado

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

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

Práticas recomendadas

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 (como 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 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 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 se tornarem 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 o comportamento ao clicar configurado 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 o Braze CDN (uma versão do nosso Web SDK) diretamente no código do seu site, o que significa que todos os métodos do SDK estão disponíveis como se você tivesse integrado o SDK sem o Google Tag Manager, exceto ao implementar Content Cards.

Configuração de Content Cards

• google tag manager
• manual

1
2
3
<script>
   window.braze.showContentCards();
</script>

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

Fazendo upgrade de modelos

Para fazer upgrade para a versão mais recente do Braze Web SDK, siga as três etapas a seguir no seu dashboard do Google Tag Manager:

1. Atualizar modelo de tag
   Acesse a página Templates no seu espaço de trabalho. Aqui você verá um ícone indicando que há uma atualização disponível.
   
   
   
   Clique nesse ícone e, após revisar a alteração, clique em Accept Update.
   
   
   
   
2. Atualizar o número da versão
   Depois que seu modelo de tag tiver sido atualizado, edite a tag de inicialização da Braze e atualize a versão do SDK para a versão mais recente major.minor. Por exemplo, se a versão mais recente for 4.1.2, digite 4.1. Você pode ver uma lista das 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 debug do Google Tag Manager antes de publicar uma atualização no seu contêiner de tags.

Solução de problemas

Ativar a depuração de tag

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 da web.

Entrar no modo de depuração

Outra maneira 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 da web para cada tag da Braze disparada e também explicará quais tags foram ou não disparadas.

Verificar o sequenciamento 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 de Braze Initialization tenha sido concluída. Para corrigir isso, configure o sequenciamento 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 sua tag de 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 o 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 serão exibidos na guia Console das ferramentas de desenvolvedor do seu navegador.

Na sua integração do Google Tag Manager, navegue até a tag de inicialização da Braze e selecione Enable Web SDK Logging.