Acerca del SDK Web de Braze

El SDK Web de Braze te permite recopilar análisis y mostrar mensajes enriquecidos dentro de la aplicación, push y Content Cards a tus usuarios web. Para obtener más información, consulta la documentación de referencia de JavaScript de Braze.

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.

Integrar el SDK Web

Puedes integrar el SDK Web de Braze utilizando los siguientes métodos. Para opciones adicionales, consulta otros métodos de integración.

• Integración basada en código: Integra el SDK Web de Braze directamente en tu base de código utilizando tu gestor de paquetes preferido o la CDN de Braze. Esto te da control total sobre cómo se carga y configura el SDK.
• Google Tag Administrador: Una solución sin código que te permite integrar el SDK Web de Braze sin modificar el código de tu sitio. Para más información, consulta Google Tag Administrador con el SDK de Braze.

Importante

Recomendamos utilizar el método de integración NPM. Sus ventajas incluyen almacenar las bibliotecas del SDK localmente en tu sitio web, proporcionar inmunidad frente a extensiones de bloqueo de anuncios y contribuir a tiempos de carga más rápidos como parte del soporte de bundlers.

• integración basada en código
• google tag administrador

Paso 1: Instala la biblioteca de Braze

Puedes instalar la biblioteca de Braze utilizando uno de los siguientes métodos. Sin embargo, si tu sitio web utiliza una Content-Security-Policy, revisa la Política de seguridad de contenido antes de continuar.

Importante

Aunque la mayoría de los bloqueadores de anuncios no bloquean el SDK Web de Braze, algunos bloqueadores más restrictivos pueden causar problemas.

• package administrador
• braze cdn

Si tu sitio utiliza los gestores de paquetes NPM o Yarn, puedes añadir el paquete NPM de Braze como dependencia.

Las definiciones de Typescript se incluyen a partir de la versión v3.0.0. Para notas sobre la actualización de 2.x a 3.x, consulta nuestro registro de cambios.

1
2
3
npm install --save @braze/web-sdk
# or, using yarn:
# yarn add @braze/web-sdk

Una vez instalado, puedes hacer import o require de la biblioteca de la forma habitual:

1
2
3
import * as braze from "@braze/web-sdk";
// or, using `require`
const braze = require("@braze/web-sdk");

Añade el SDK Web de Braze directamente a tu HTML haciendo referencia a nuestro script alojado en la CDN, que carga la biblioteca de forma asíncrona.

Importante

La configuración predeterminada Prevenir seguimiento entre sitios en Safari puede impedir que los tipos de mensajes dentro de la aplicación como Banners y Content Cards se muestren cuando utilizas el método de integración CDN. Para evitar este problema, utiliza el método de integración NPM para que Safari no clasifique estos mensajes como tráfico entre sitios y tus usuarios web puedan verlos en todos los navegadores compatibles.

Paso 2: Inicializa el SDK

Después de añadir el SDK Web de Braze a tu sitio web, inicializa la biblioteca con la clave de API y la URL del endpoint del SDK que se encuentran en Configuración > Configuración de la aplicación dentro de tu panel de Braze. Para una lista completa de opciones de braze.initialize(), junto con nuestros otros métodos JavaScript, consulta la documentación JavaScript de Braze.

Nota

Los dominios personalizados para solicitudes del SDK Web no son compatibles: El baseUrl del SDK Web debe ser un endpoint del SDK de Braze (por ejemplo, sdk.iad-05.braze.com). Braze no admite el enrutamiento del tráfico del SDK Web a través de un dominio propio del cliente mediante registros CNAME. Si necesitas que las solicitudes del SDK Web se originen desde tu propio dominio, contacta con soporte de Braze.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE",
    enableLogging: false, // set to `true` for debugging
    allowUserSuppliedJavascript: false, // set to `true` to support custom HTML messages
});

// Enable automatic display of in-app messages
// Required if you want in-app messages to display automatically when triggered
braze.automaticallyShowInAppMessages();

// if you use Content Cards
braze.subscribeToContentCardsUpdates(function(cards){
    // cards have been updated
});

// optionally set the current user's external ID before starting a new session
// you can also call `changeUser` later in the session after the user logs in
if (isLoggedIn){
    braze.changeUser(userIdentifier);
}

// `openSession` should be called last - after `changeUser` and `automaticallyShowInAppMessages`
braze.openSession();

Importante

Visualización de In-App Messages: Para mostrar mensajes dentro de la aplicación automáticamente cuando se desencadenan, debes llamar a braze.automaticallyShowInAppMessages(). Sin esta llamada, los mensajes dentro de la aplicación no se muestran automáticamente. Si quieres gestionar la visualización de mensajes manualmente, elimina esta llamada y utiliza braze.subscribeToInAppMessage() en su lugar. Para más información, consulta Desactivar desencadenadores automáticos.

Solución de problemas con sesiones faltantes para usuarios anónimos

Si observas un comportamiento de “sesión faltante”, o no puedes realizar un seguimiento de la sesión para usuarios que permanecen anónimos en la web, asegúrate de que tu integración llame a braze.openSession() durante la inicialización.

• Escenario: Los usuarios anónimos pueden devolver un ID de Braze, pero los datos de sesión están en blanco o faltan.
• Causa: La implementación no llama a braze.openSession().
• Resolución: Llama siempre a braze.openSession() después de la inicialización (y después de braze.changeUser() si estableces un ID externo).

Para más información, consulta Paso 2: Inicializa el SDK.

Importante

Los usuarios anónimos en dispositivos móviles o web pueden contarse como parte de tus MAU. Como resultado, es posible que quieras cargar o inicializar el SDK de forma condicional para excluir a estos usuarios de tu recuento de MAU.

Requisitos previos

Antes de poder utilizar este método de integración, deberás crear una cuenta y un contenedor para Google Tag Administrador.

Paso 1: Abre la galería de plantillas de etiquetas

En Google Tag Administrador, elige tu espacio de trabajo y, a continuación, selecciona Templates. En el panel Tag Template, selecciona Search Gallery.

Paso 2: Añade la plantilla de etiqueta de inicialización

En la galería de plantillas, busca braze-inc y selecciona Braze Initialization Tag.

Selecciona Add to workspace > Add.

Paso 3: Configura la etiqueta

En la sección Templates, selecciona la plantilla que acabas de añadir.

Selecciona el icono del lápiz para abrir el menú desplegable Tag Configuration.

Introduce la información mínima requerida:

Campo	Descripción
API Key	Tu clave de API de Braze, que se encuentra en el panel de Braze en Settings > App Settings.
API Endpoint	La URL de tu endpoint REST. Tu endpoint dependerá de la URL de Braze para tu instancia.
SDK Version	La versión MAJOR.MINOR más reciente del SDK Web de Braze que aparece en el registro de cambios. Por ejemplo, si la última versión es 4.1.2, introduce 4.1. Para más información, consulta Acerca de la gestión de versiones del SDK.

Para configuraciones de inicialización adicionales, selecciona Braze Initialization Options y elige las opciones que necesites.

Paso 4: Elige las opciones de inicialización

La etiqueta de inicialización de Braze expone las siguientes opciones. La mayoría se mapean directamente a las InitializationOptions del SDK Web, y algunas corresponden a métodos del SDK Web que la etiqueta llamará durante la inicialización. Selecciona las opciones que se ajusten a tus necesidades de integración:

Opción GTM	Configuración o método del SDK Web	Descripción
Allow HTML In-App Messages	allowUserSuppliedJavascript	Habilita mensajes HTML dentro de la aplicación, banners y acciones de clic JavaScript proporcionadas por el usuario. Necesario para mensajes HTML dentro de la aplicación y banners que utilizan HTML personalizado. Habilita esta opción solo si confías en el contenido HTML y JavaScript, ya que permite la ejecución de JavaScript proporcionado por el usuario.
App Version Number	appVersion, appVersionNumber	Versión de la aplicación para segmentación (por ejemplo, 1.2.3.4).
Automatically Open New Session	braze.openSession()	Abre una nueva sesión después de que el SDK se inicialice llamando a este método por ti.
Automatically show new in app messages	braze.automaticallyShowInAppMessages()	Muestra automáticamente los nuevos mensajes dentro de la aplicación cuando llegan del servidor llamando a este método después de la inicialización.
Disable Automatic Push Token Maintenance	disablePushTokenMaintenance	Impide que el SDK sincronice los tokens de notificaciones push con el backend de Braze en las nuevas sesiones.
Disable Automatic Service Worker Registration	manageServiceWorkerExternally	Úsalo si tú mismo realizas el registro y controlas el prestador de servicios.
Disable Cookies	noCookies	Utiliza localStorage en lugar de cookies para los datos de usuario/sesión. Evita el reconocimiento entre subdominios.
Disable Font Awesome	doNotLoadFontAwesome	Evita que el SDK cargue Font Awesome desde el CDN. Úsalo si tu sitio tiene su propio Font Awesome.
Enable SDK Authentication	enableSdkAuthentication	Habilita la autenticación SDK.
Enable Web SDK Logging	enableLogging	Habilita el registro en consola para depuración. Elimínalo antes de pasar a producción.
Minimum Interval Between Triggered Messages	minimumIntervalBetweenTriggerActionsInSeconds	Segundos mínimos entre acciones desencadenantes (predeterminado: 30).
Open Cards in New Tab	openCardsInNewTab	Abre los enlaces de las tarjetas de contenido en una nueva pestaña cuando se utiliza la interfaz de usuario predeterminada de la fuente.
Service Worker Location	serviceWorkerLocation	Ruta personalizada para el archivo del prestador de servicios (predeterminado: /service-worker.js).
Session Timeout (seconds)	sessionTimeoutInSeconds	Tiempo de espera de la sesión en segundos (predeterminado: 1800).

Nota

Para habilitar los mensajes HTML personalizados dentro de la aplicación cuando utilices la etiqueta de inicialización de Braze de Google Tag Administrador, selecciona Allow HTML In-App Messages en Braze Initialization Options. Esta casilla de verificación se mapea con la opción de inicialización allowUserSuppliedJavascript en braze.initialize() y la establece en true. La etiqueta de inicialización de Braze de Google Tag Administrador utiliza esta etiqueta en lugar del nombre de la opción.

Para las opciones que no aparecen en la plantilla GTM (como contentSecurityNonce, localization o devicePropertyAllowlist), utiliza la inicialización en tiempo de ejecución.

Paso 5: Configura para desencadenar en todas las páginas

La etiqueta de inicialización debe ejecutarse en todas las páginas de tu sitio web. Esto te permite utilizar los métodos del SDK de Braze y registrar análisis de notificaciones push web.

Importante

Secuenciación de etiquetas: La etiqueta de inicialización de Braze debe dispararse antes que cualquier otra etiqueta que llame a métodos del SDK de Braze (como braze.getUser() o braze.logCustomEvent()). Si los eventos personalizados, los atributos de usuario u otras llamadas a métodos de Braze se disparan antes de que el SDK se inicialice, puedes encontrar errores como Uncaught TypeError: Cannot read properties of undefined (reading 'getUser'). Para garantizar la secuenciación correcta, configura tu etiqueta de inicialización de Braze como una etiqueta de configuración o utiliza la característica de secuenciación de etiquetas de GTM para garantizar que se dispare primero. Para más información, consulta Secuenciación de etiquetas para etiquetas de acción de Braze.

Paso 6: Verifica tu integración

Puedes verificar tu integración utilizando cualquiera de las siguientes opciones:

• Opción 1: Con la herramienta de depuración de Google Tag Administrador, puedes comprobar si la etiqueta de inicialización de Braze se desencadena correctamente en las páginas o eventos que has configurado.
• Opción 2: Comprueba si hay solicitudes de red realizadas a Braze desde tu página web. Además, la biblioteca global window.braze debería estar definida.

Filtrado del tráfico de bots

Los MAU pueden incluir un porcentaje de usuarios bot, lo que infla tu recuento de MAU. Aunque el SDK Web de Braze incluye detección integrada para algunos rastreadores web comunes (como los bots de motores de búsqueda y los bots de vista previa de redes sociales), es especialmente importante mantenerse proactivo con soluciones robustas para detectar bots, ya que las actualizaciones del SDK por sí solas no pueden detectar de forma consistente todos los bots nuevos.

Limitaciones de la detección de bots por parte del SDK

El SDK Web incluye una detección básica de bots basada en agentes de usuario que filtra los rastreadores conocidos. Sin embargo, este enfoque tiene limitaciones:

• Constantemente surgen nuevos bots: Las empresas de IA y otros actores crean regularmente nuevos bots que pueden camuflarse para evitar ser detectados.
• Suplantación de agente de usuario: Los bots sofisticados pueden imitar los agentes de usuario legítimos de los navegadores.
• Bots personalizados: Los usuarios sin conocimientos técnicos ahora pueden crear fácilmente bots utilizando modelos de lenguaje grandes (LLM), lo que hace que el comportamiento de los bots sea impredecible.

Implementación del filtrado de bots

Importante

Las soluciones que se describen a continuación son sugerencias generales. Adapta la lógica para filtrar bots a tu entorno y patrones de tráfico únicos.

La solución más sólida es implementar tu propia lógica para filtrar bots antes de inicializar el SDK de Braze. Los enfoques comunes incluyen:

Requerir interacción del usuario

Considera la posibilidad de retrasar la inicialización del SDK hasta que el usuario realice una interacción significativa, como aceptar un banner de consentimiento de cookies, desplazarse por la página o hacer clic. Este enfoque suele ser más fácil de implementar y puede resultar muy eficaz para filtrar el tráfico de bots.

Importante

Retrasar la inicialización del SDK hasta que se produzca la interacción del usuario puede provocar que los banners y las Content Cards tampoco se muestren hasta que se produzca dicha interacción.

Detección personalizada de bots

Implementa una detección personalizada basada en tus patrones específicos de tráfico de bots, tales como:

• Analizar las cadenas de agente de usuario en busca de patrones que hayas identificado en tu tráfico
• Comprobación de indicadores de navegador sin interfaz gráfica
• Uso de servicios de detección de bots de terceros
• Supervisión de señales de comportamiento específicas de tu sitio web

Ejemplo de inicialización condicional:

1
2
3
4
5
6
7
8
// Only initialize Braze if your custom bot detection determines this is not a bot
if (!isLikelyBot()) {
  braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
  });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
}

Buenas prácticas

• Analiza periódicamente tus datos de MAU y los patrones de tráfico web para identificar nuevos comportamientos de bots.
• Realiza pruebas exhaustivas para asegurarte de que tu filtro de bots no impida el seguimiento de usuarios legítimos.
• Actualiza tu lógica de filtrado basándote en los patrones de tráfico de bots que observes en tu entorno.

Configuraciones opcionales

Registro

Para habilitar rápidamente el registro, puedes añadir ?brazeLogging=true como parámetro a la URL de tu sitio web. Alternativamente, puedes habilitar el registro básico o personalizado. Para obtener un resumen centralizado en todas las plataformas, consulta Registro detallado.

Registro básico

• antes de la inicialización
• después de la inicialización

1
enableLogging: true

1
2
3
4
5
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
    enableLogging: true
});
braze.openSession();

1
2
3
4
5
6
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
});
braze.openSession();
...
braze.toggleLogging();

Importante

Los registros básicos son visibles para todos los usuarios, así que considera deshabilitarlos o cambiar a setLogger antes de liberar tu código a producción.

Registro personalizado

Usa setLogger para registrar mensajes de depuración personalizados en la consola de JavaScript. A diferencia de los registros básicos, estos registros no son visibles para los usuarios.

1
setLogger(loggerFunction: (message: STRING) => void): void

Reemplaza STRING con tu mensaje como un único parámetro de cadena. Tu método debería ser similar al siguiente:

1
2
3
4
5
braze.initialize('API-KEY');
braze.setLogger(function(message) {
    console.log("Braze Custom Logger: " + message);
});
braze.openSession();

Actualización del SDK

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.

Cuando haces referencia al SDK Web de Braze desde nuestra red de entrega de contenido, por ejemplo, https://js.appboycdn.com/web-sdk/a.a/braze.min.js (como recomiendan nuestras instrucciones de integración predeterminadas), tus usuarios reciben actualizaciones menores (correcciones de errores y características retrocompatibles, versiones a.a.a a a.a.z en este ejemplo) de forma automática cuando actualizan tu sitio.

Sin embargo, cuando publicamos cambios importantes, requerimos que actualices el SDK Web de Braze de forma manual para garantizar que los cambios de ruptura no afecten tu integración. Además, si descargas nuestro SDK y lo alojas tú mismo, no recibes ninguna actualización de versión de forma automática y debes actualizarlo manualmente para recibir las últimas características y correcciones de errores.

Puedes mantenerte al día con nuestra última versión siguiendo nuestro feed de lanzamientos con el lector RSS o servicio de tu elección, y consultar nuestro registro de cambios para ver un recuento completo del historial de versiones de nuestro SDK Web. Para actualizar el SDK Web de Braze:

• Actualiza la versión de la biblioteca de Braze cambiando el número de versión de https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js, o en las dependencias de tu gestor de paquetes.
• Si tienes notificación push web integrada, actualiza el archivo del prestador de servicios en tu sitio; de forma predeterminada, se encuentra en /service-worker.js en el directorio raíz de tu sitio, pero la ubicación puede estar personalizada en algunas integraciones. Debes acceder al directorio raíz para alojar un archivo de prestador de servicios.

Debes actualizar estos dos archivos de forma coordinada para asegurar un funcionamiento correcto.

Otros métodos de integración

Páginas móviles aceleradas (páginas móviles aceleradas)

1
<script async custom-element="amp-web-push" src="https://cdn.ampproject.org/v0/amp-web-push-0.1.js"></script>

1
2
3
4
5
6
7
8
9
<!-- A subscription widget -->
<amp-web-push-widget visibility="unsubscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.subscribe">Subscribe to Notifications</button>
</amp-web-push-widget>

<!-- An unsubscription widget -->
<amp-web-push-widget visibility="subscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.unsubscribe">Unsubscribe from Notifications</button>
</amp-web-push-widget>

1
2
3
4
5
6
7
<amp-web-push
layout="nodisplay"
id="amp-web-push"
helper-iframe-url="FILE_PATH_TO_YOUR_HELPER_IFRAME"
permission-dialog-url="FILE_PATH_TO_YOUR_PERMISSION_DIALOG"
service-worker-url="FILE_PATH_TO_YOUR_SERVICE_WORKER?apiKey={YOUR_API_KEY}&baseUrl={YOUR_BASE_URL}"
>

Definición de módulos asíncronos (AMD)

Desactivar la compatibilidad

Si tu sitio utiliza RequireJS u otro cargador de módulos AMD, pero prefieres cargar el SDK Web de Braze a través de una de las otras opciones de esta lista, puedes cargar una versión de la biblioteca que no incluye compatibilidad con AMD. Esta versión de la biblioteca se puede cargar desde la siguiente ubicación CDN:

Cargador de módulos

Si usas RequireJS u otros cargadores de módulos AMD, te recomendamos alojar una copia de nuestra biblioteca y referenciarla como lo harías con otros recursos:

1
2
3
4
5
6
require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  // Required if you want in-app messages to display automatically
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

Electron

Electron no admite oficialmente las notificaciones push web (consulta este issue en GitHub). Hay otras soluciones alternativas de código abierto que puedes probar, aunque no han sido verificadas por Braze.

Framework Jest

Al usar Jest, es posible que veas un error similar a SyntaxError: Unexpected token 'export'. Para solucionarlo, ajusta tu configuración en package.json para ignorar el SDK de Braze:

1
2
3
4
5
"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}

Frameworks SSR

El SDK Web se ejecuta en un entorno de navegador. En frameworks SSR, inicializa Braze en un componente exclusivo del cliente para que tu servidor nunca ejecute código del SDK.

Importación dinámica agnóstica al framework

Si tu framework no aparece en esta sección, puedes importar Braze dinámicamente desde un hook del ciclo de vida exclusivo del cliente.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// MyComponent/braze-exports.js
// Export the parts of the SDK that you need.
export { initialize, openSession } from "@braze/web-sdk";

// MyComponent/MyComponent.js
useEffect(() => {
    import("./braze-exports.js").then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Si usas webpack, puedes importar dinámicamente solo exportaciones específicas del SDK.

1
2
3
4
5
6
7
8
9
10
11
12
13
// MyComponent.js
useEffect(() => {
    import(
        /* webpackExports: ["initialize", "openSession"] */
        "@braze/web-sdk"
    ).then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Hook compartido para Next.js y Remix

Crea un hook reutilizable useBraze y llámalo cerca de la raíz de tu aplicación.

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
// hooks/useBraze.ts
import { useEffect, useRef } from "react";

export function useBraze() {
  const didInit = useRef(false);

  useEffect(() => {
    if (didInit.current) {
      return;
    }
    didInit.current = true;

    import("@braze/web-sdk")
      .then((braze) => {
        const initialized = braze.initialize("YOUR-API-KEY-HERE", {
          // Use your Braze Web SDK endpoint, such as sdk.iad-01.braze.com.
          baseUrl: "YOUR-SDK-ENDPOINT",
          enableLogging: false,
        });
        if (!initialized) {
          return;
        }

        // Optional: Identify signed-in users before opening a session.
        // braze.changeUser("external-id");

        // Optional: Automatically display in-app messages.
        // braze.automaticallyShowInAppMessages();
        braze.openSession();
      })
      .catch((error) => {
        console.error("Unable to load Braze SDK:", error);
      });
  }, []);
}

Next.js (App Router)

Llama a useBraze en un componente cliente que envuelva tu aplicación.

1
2
3
4
5
6
7
8
9
10
// app/components/AppRoot.tsx
"use client";

import type { ReactNode } from "react";
import { useBraze } from "../hooks/useBraze";

export function AppRoot({ children }: { children: ReactNode }) {
  useBraze();
  return <>{children}</>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// app/layout.tsx
import type { ReactNode } from "react";
import { AppRoot } from "./components/AppRoot";

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AppRoot>{children}</AppRoot>
      </body>
    </html>
  );
}

Next.js (Pages Router)

Llama a useBraze en la parte superior de tu componente de aplicación personalizado.

1
2
3
4
5
6
7
8
9
10
11
// pages/_app.tsx
import type { AppProps } from "next/app";
import { useBraze } from "../hooks/useBraze";

export default function App({ Component, pageProps }: AppProps) {
  useBraze();

  return (
    <Component {...pageProps} />
  );
}

Remix

Llama a useBraze en la parte superior de tu componente de ruta raíz.

Para ejemplos de validación local de Remix, ejecuta PORT=4013 npm run dev.

1
2
3
4
5
6
7
8
9
// app/root.tsx
import { Outlet } from "@remix-run/react";
import { useBraze } from "./hooks/useBraze";

export default function App() {
  useBraze();

  return <Outlet />;
}

Registro de eventos y actualización de usuarios

Después de que useBraze inicialice el SDK en la raíz de tu aplicación, otros componentes cliente pueden llamar a los métodos de Braze. Un patrón común es llamarlos dentro de acciones del usuario, como onClick o onSubmit. En el ejemplo, los métodos del SDK se cargan dentro del controlador de clic en lugar de en la parte superior del archivo. Esto mantiene el SDK Web fuera del código del servidor y carga solo lo que esa acción necesita. El comentario webpackExports le indica a webpack qué métodos incluir, para que tu bundle se mantenga más pequeño.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// app/components/BuyButton.tsx
"use client";

export function BuyButton() {
  const handleClick = async () => {
    const { logCustomEvent, logPurchase, getUser } = await import(
      /* webpackExports: ["logCustomEvent", "logPurchase", "getUser"] */
      "@braze/web-sdk"
    );

    getUser()?.setCustomUserAttribute("last_purchase_date", "2026-05-04");
    logCustomEvent("clicked_buy", { source: "product_page" });
    logPurchase("sku_123", 19.99, "USD");
  };

  return <button onClick={handleClick}>Buy</button>;
}

Este ejemplo muestra un componente BuyButton que registra actividad cuando alguien hace clic en Comprar. Primero, importa solo logCustomEvent, logPurchase y getUser en el momento del clic. Luego actualiza un atributo de usuario, registra un evento personalizado y registra una compra. Este patrón te ayuda a mantener la inicialización centralizada en useBraze, mientras sigues rastreando acciones significativas desde cualquier componente cliente.

Si usas Remix con Vite y las importaciones desde la raíz del paquete fallan en tiempo de ejecución, usa la solución alternativa existente de Vite. Para más información, consulta Vite.

Para una lista completa de los métodos disponibles, consulta la documentación de referencia de JavaScript de Braze.

Tealium iQ

Tealium iQ ofrece una integración básica de Braze lista para usar. Para configurar la integración, busca Braze en la interfaz de Tealium Tag Management y proporciona la clave de API del SDK Web desde tu panel.

Para más detalles o asistencia en profundidad sobre la configuración de Tealium, consulta nuestra documentación de integración o contacta con tu director de cuentas de Tealium.

Vite

Si usas Vite y ves una advertencia sobre dependencias circulares o Uncaught TypeError: Class extends value undefined is not a constructor or null, es posible que necesites excluir el SDK de Braze de su descubrimiento de dependencias:

1
2
3
optimizeDeps: {
    exclude: ['@braze/web-sdk']
},

Otros gestores de etiquetas

Braze también puede ser compatible con otras soluciones de gestión de etiquetas siguiendo nuestras instrucciones de integración dentro de una etiqueta HTML personalizada. Contacta con un representante de Braze si necesitas ayuda para evaluar estas soluciones.