Tarjetas de contenido

Requisitos previos

Antes de poder utilizar las Tarjetas de contenido, tendrás que integrar el SDK Web de Braze en tu aplicación. Sin embargo, no es necesaria ninguna configuración adicional. Para crear tu propia interfaz de usuario, consulta la Guía de personalización de tarjetas de contenido.

IU estándar de la fuente

Para utilizar la interfaz de usuario de las Tarjetas de contenido incluida, tendrás que especificar dónde mostrar la fuente en tu sitio web.

En este ejemplo, tenemos un <div id="feed"></div> en el que queremos colocar la fuente de Tarjetas de contenido. Utilizaremos tres botones para ocultar, mostrar o alternar (ocultar o mostrar en función de su estado actual) la fuente.

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>

Al utilizar los métodos toggleContentCards(parentNode, filterFunction) y showContentCards(parentNode, filterFunction), si no se proporcionan argumentos, todas las Tarjetas de contenido se mostrarán en una barra lateral de posición fija en la parte derecha de la página. De lo contrario, la fuente se colocará en la opción parentNode especificada.

Consulta la documentación de referencia del SDK para obtener más información sobre cómo alternar las Tarjetas de contenido.

Probar Tarjetas de contenido en la web

Puedes probar tu integración de Tarjetas de contenido utilizando las herramientas de desarrollador de tu navegador.

1. Crea una campaña de tarjeta de contenido y dirígela a tu usuario de prueba.
2. Inicia sesión en el sitio web que tiene tu integración del SDK Web.
3. Abre la consola de tu navegador. En Chrome, haz clic derecho en la página, selecciona Inspeccionar y luego selecciona la pestaña Consola.
4. Ejecuta estos comandos en la consola:
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Tipos de tarjeta y propiedades

El modelo de datos de las Tarjetas de contenido está disponible en el SDK Web y ofrece los siguientes tipos de tarjetas de contenido: ImageOnly, CaptionedImage y ClassicCard. Cada tipo hereda propiedades comunes de un modelo base Card y tiene las siguientes propiedades adicionales.

Modelo de tarjeta base

Todas las Tarjetas de contenido tienen estas propiedades compartidas:

Solo imagen

Las tarjetas ImageOnly son imágenes a tamaño completo en las que se puede hacer clic.

Imagen subtitulada

Las tarjetas CaptionedImage son imágenes de tamaño completo en las que se puede hacer clic y que van acompañadas de un texto descriptivo.

Clásica

El modelo ClassicCard puede contener una imagen sin texto o un texto con imagen.

Grupo de control

Si utilizas la fuente predeterminada de Tarjetas de contenido, las impresiones y los clics se rastrearán automáticamente.

Si utilizas una integración personalizada para Tarjetas de contenido, necesitas registrar las impresiones cuando se hubiera visto una tarjeta de control. Como parte de este esfuerzo, asegúrate de gestionar las tarjetas de control al registrar las impresiones en una prueba A/B. Estas tarjetas están en blanco y, aunque no las vean los usuarios, debes registrar las impresiones para comparar su rendimiento con el de las tarjetas que no son de control.

Para determinar si una tarjeta de contenido está en el grupo de control de una prueba A/B, comprueba la propiedad card.isControl (Web SDK v4.5.0+) o comprueba si la tarjeta es una instancia de ControlCard (card instanceof braze.ControlCard).

Métodos de tarjeta

Métodos de fuente predeterminada

Usa estos métodos cuando muestres Tarjetas de contenido utilizando la interfaz de usuario predeterminada de Braze:

Métodos de fuente personalizada

Usa estos métodos cuando construyas tu propia interfaz de usuario de Tarjetas de contenido:

Para más detalles, consulta la documentación de referencia del SDK.

Buenas prácticas

Llama a los métodos en el orden correcto

Para fuentes personalizadas, las Tarjetas de contenido solo se actualizan al inicio de sesión si subscribeToContentCardsUpdates() se llama antes de openSession(). Llama a tus métodos de Braze en este orden:

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

Usa tarjetas en caché para mantener el contenido entre cargas de página

Dado que subscribeToContentCardsUpdates() solo invoca su devolución de llamada cuando hay nuevas actualizaciones (como al inicio de sesión), las tarjetas pueden desaparecer de tu fuente personalizada si un usuario actualiza la página a mitad de sesión. Para evitar esto, usa getCachedContentCards() para renderizar tarjetas inmediatamente desde la caché local, junto con tu suscripción para nuevas actualizaciones:

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

Registra análisis para fuentes personalizadas

Cuando usas una interfaz personalizada, las impresiones, los clics y los descartes no se rastrean automáticamente. Debes registrar cada evento manualmente:

• Impresiones: Llama a logContentCardImpressions([card1, card2, ...]) con una matriz de objetos de tarjeta cuando las tarjetas sean visibles para el usuario.
• Clics: Llama a logContentCardClick(card) cuando un usuario interactúe con una tarjeta.
• Comportamiento de clic: Llama a handleBrazeAction(card.url) para ejecutar la acción de clic configurada de la tarjeta (como navegar a una URL o registrar un evento personalizado).

Uso de Google Tag Manager

Google Tag Manager funciona inyectando la CDN de Braze (una versión de nuestro SDK Web) directamente en el código de tu sitio web, lo que significa que todos los métodos del SDK están disponibles igual que si hubieras integrado el SDK sin Google Tag Manager, excepto al implementar Tarjetas de contenido.

Configuración de las Tarjetas de contenido

• google tag manager
• manual

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

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

Actualización de plantillas

Para actualizar a la última versión del SDK Web de Braze, sigue los tres pasos siguientes en tu dashboard de Google Tag Manager:

1. Actualizar plantilla de etiquetas
   Ve a la página Plantillas dentro de tu espacio de trabajo. Aquí deberías ver un icono que indica que hay una actualización disponible.
   
   
   
   Haz clic en ese icono y, tras revisar el cambio, haz clic en Aceptar actualización.
   
   
   
   
2. Actualizar número de versión
   Una vez actualizada tu plantilla de etiquetas, edita la etiqueta de inicialización de Braze y actualiza la versión del SDK a la versión más reciente de major.minor. Por ejemplo, si la última versión es 4.1.2, introduce 4.1. Puedes ver una lista de las versiones del SDK en nuestro registro de cambios.
   
   
   
   
3. Control de calidad y publicación
   Comprueba que la nueva versión del SDK funciona utilizando la herramienta de depuración de Google Tag Manager antes de publicar una actualización en tu contenedor de etiquetas.

Solución de problemas

Habilitar la depuración de etiquetas

Cada plantilla de etiqueta de Braze tiene una casilla de verificación opcional Depuración de etiquetas GTM que puede utilizarse para registrar mensajes de depuración en la consola JavaScript de tu página web.

Entrar en modo depuración

Otra forma de ayudar a depurar tu integración con Google Tag Manager es utilizar la característica de modo de vista previa de Google.

Esto ayudará a identificar qué valores se envían desde la capa de datos de tu página web a cada etiqueta de Braze desencadenada y también explicará qué etiquetas se desencadenaron o no.

Verificar la secuencia de etiquetas para eventos personalizados

Si los eventos personalizados u otras acciones no se registran en Braze, una causa común es una condición de carrera en la que una etiqueta de acción (como Evento personalizado o Compra) se dispara antes de que la etiqueta de inicialización de Braze haya completado. Para solucionarlo, configura la secuencia de etiquetas en GTM:

1. Abre la etiqueta de acción que no se está registrando correctamente.
2. En Configuración avanzada > Secuencia de etiquetas, selecciona Una etiqueta que se dispara antes de [esta etiqueta].
3. Elige tu etiqueta de inicialización de Braze como la etiqueta de configuración.

Esto asegura que el SDK esté completamente inicializado antes de que cualquier etiqueta de acción intente enviar datos a Braze.

Habilitar el registro detallado

Para capturar registros detallados para la solución de problemas, puedes habilitar el registro detallado en tu integración con Google Tag Manager. Estos registros aparecerán en la pestaña Consola de las herramientas de desarrollador de tu navegador.

En tu integración de Google Tag Manager, navega hasta tu etiqueta de inicialización de Braze y selecciona Habilitar registro del SDK Web.