Content Cards

Nota

Esta guía utiliza ejemplos de código del SDK Web de Braze 4.0.0+. Para actualizar a la última versión del SDK Web, consulta la Guía de actualización del SDK.

Requisitos previos

Antes de poder usar Content Cards, deberás integrar el SDK Web de Braze en tu aplicación. Sin embargo, no se requiere configuración adicional. Para construir tu propia interfaz de usuario, consulta la guía de personalización de Content Cards.

Nota

Algunos bloqueadores de anuncios y extensiones de privacidad del navegador pueden bloquear el script del SDK Web de Braze o las solicitudes de red relacionadas, lo que puede impedir que las Content Cards se carguen. Si estás utilizando el método de integración por CDN, considera cambiar al método de integración por NPM, que almacena las bibliotecas del SDK de forma local en tu sitio web y puede evitar algunos problemas relacionados con los bloqueadores de anuncios.

Interfaz estándar de la fuente

Para usar la interfaz de Content Cards incluida, deberás 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 Content Cards. Usaremos tres botones para ocultar, mostrar o alternar (ocultar o mostrar según 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 usar los métodos toggleContentCards(parentNode, filterFunction) y showContentCards(parentNode, filterFunction), si no se proporcionan argumentos, todas las Content Cards se mostrarán en una barra lateral con posición fija en 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 la alternancia de Content Cards.

Pruebas de Content Cards en la web

Puedes probar tu integración de Content Cards utilizando las herramientas de desarrollador de tu navegador.

1. Crea una campaña de Content Cards 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 tarjetas y propiedades

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

Consejo

Para registrar datos de Content Cards, consulta Registro de análisis.

Modelo base de tarjeta

Todas las Content Cards comparten estas propiedades:

Solo imagen

Las tarjetas ImageOnly son imágenes clicables de tamaño completo.

Imagen con subtítulo

Las tarjetas CaptionedImage son imágenes clicables de tamaño completo con texto descriptivo acompañante.

Clásica

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

Formatos de imagen

Las imágenes de Content Cards (incluidos los GIF) se renderizan usando etiquetas HTML estándar <img>. La compatibilidad con GIF depende de las capacidades del navegador del usuario y no requiere una versión mínima del SDK Web. Todos los navegadores modernos admiten la reproducción de GIF de forma nativa.

Grupo de control

Si usas la fuente predeterminada de Content Cards, las impresiones y los clics se registrarán automáticamente.

Si usas una integración personalizada para Content Cards, necesitas registrar impresiones cuando se habría visto una tarjeta de control. Como parte de este esfuerzo, asegúrate de manejar las tarjetas de control al registrar impresiones en una prueba A/B. Estas tarjetas están en blanco y, aunque los usuarios no las ven, debes registrar las impresiones para poder comparar su rendimiento con el de las tarjetas que no son de control.

Para determinar si una Content Card está en el grupo de control de una prueba A/B, comprueba la propiedad card.isControl (Web SDK v4.5.0+) o verifica 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 Content Cards con la interfaz de usuario de fuente predeterminada de Braze:

Métodos de fuente personalizada

Usa estos métodos cuando construyas tu propia interfaz de usuario para Content Cards:

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 Content Cards solo se actualizan al iniciar la sesión si se llama a subscribeToContentCardsUpdates() 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 callback cuando hay nuevas actualizaciones (como al iniciar la sesión), las tarjetas pueden desaparecer de tu fuente personalizada si un usuario actualiza la página a mitad de sesión. Para evitarlo, usa getCachedContentCards() para renderizar inmediatamente las tarjetas 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 un array de objetos de tarjeta cuando las tarjetas se hacen visibles para el usuario.
• Clics: Llama a logContentCardClick(card) cuando un usuario interactúa con una tarjeta.
• Comportamiento al hacer clic: Llama a handleBrazeAction(card.url) para ejecutar la acción configurada al hacer clic en la tarjeta (como navegar a una URL o registrar un evento personalizado).

Advertencia

El argumento pasado a logContentCardClick() debe ser un objeto Card original de Braze. Si transformas o reconstruyes los datos de la tarjeta (por ejemplo, serializando y deserializando), los clics no se registran y verás el error: “card must be a Card object.”

Uso de Google Tag Manager

Google Tag Manager funciona inyectando el 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 Content Cards.

Configurar Content Cards

• google tag manager
• manual

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

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

Actualizar plantillas

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

1. Actualizar la plantilla de etiqueta
   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, después de revisar el cambio, haz clic en Aceptar actualización.
   
   
   
   
2. Actualizar el número de versión
   Una vez que tu plantilla de etiqueta se haya actualizado, edita la etiqueta de inicialización de Braze y actualiza la versión del SDK a la versión major.minor más reciente. Por ejemplo, si la última versión es 4.1.2, introduce 4.1. Puedes ver una lista de versiones del SDK en nuestro registro de cambios.
   
   
   
   
3. Control de calidad y publicación
   Verifica que la nueva versión del SDK esté funcionando usando 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 opcional Depuración de etiquetas GTM que se puede usar para registrar mensajes de depuración en la consola JavaScript de tu página web.

Entrar en modo de depuración

Otra forma de ayudar a depurar tu integración de Google Tag Manager es usar la función de modo de vista previa de Google.

Esto ayudará a identificar qué valores se están enviando desde la capa de datos de tu página web a cada etiqueta de Braze activada, y también explicará qué etiquetas se activaron o no.

Verificar la secuencia de etiquetas para eventos personalizados

Si los eventos personalizados u otras acciones no se están registrando en Braze, una causa común es una condición de carrera donde una etiqueta de acción (como Evento personalizado o Compra) se dispara antes de que la etiqueta de inicialización de Braze se 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 activa 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 de 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 a tu etiqueta de inicialización de Braze y selecciona Habilitar registro del SDK web.