Cartões de conteúdo

Pré-requisitos

Antes de poder usar os Cartões de conteúdo, você precisará integrar o Braze Web SDK em seu app. No entanto, não é necessária nenhuma configuração adicional. Para criar sua própria interface do usuário, consulte o Guia de personalização do cartão de conteúdo.

Interface do usuário do feed padrão

Para usar a interface de usuário dos Cartões de conteúdo incluída, você precisará especificar onde mostrar o feed em seu site.

Neste exemplo, temos um <div id="feed"></div> no qual queremos colocar o feed dos Cartões de conteúdo. 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 Cartões de conteúdo 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 do cartão de conteúdo.

Testando Cartões de conteúdo na web

Você pode testar sua integração de Cartões de conteúdo usando as ferramentas de desenvolvedor do seu navegador.

1. Crie uma campanha de cartão de conteúdo 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 Inspecionar 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 Cartões de conteúdo está disponível no Web SDK e oferece os seguintes tipos de Cartões de conteúdo: ImageOnly, CaptionedImage e ClassicCard. Cada tipo herda propriedades comuns de um modelo base Card e tem as seguintes propriedades adicionais.

Modelo de cartão base

Todos os Cartões de conteúdo 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 Cartões de conteúdo, as impressões e os cliques serão automaticamente rastreados.

Se você usar uma integração personalizada para Cartões de conteúdo, precisará registrar impressões quando um cartão de controle tiver sido visto. Nessa iniciativa, 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 a performance deles com os cartões que não são de controle.

Para determinar se um cartão de conteúdo 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 Cartões de conteúdo usando a interface padrão da Braze:

Métodos do feed personalizado

Use estes métodos ao criar sua própria interface de Cartões de conteúdo:

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 Cartões de conteúdo 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 vetor 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).

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 Cartões de conteúdo.

Configuração de Cartões de conteúdo

• 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 Modelos em 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 (Aceitar atualização).
   
   
   
   
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 em nosso changelog.
   
   
   
   
3. Controle de qualidade 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 de depuração de tag GTM 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 Evento personalizado ou Compra) é disparada antes que a tag de Inicialização da Braze 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 Configurações avançadas > Sequenciamento de tags, selecione Uma tag que é disparada antes de [esta tag].
3. Escolha sua tag de Inicialização da Braze 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.

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