Acerca del SDK de Web Braze

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

Integrar el SDK Web

Puedes realizar la integración del SDK de Web Braze utilizando los siguientes métodos. Para ver opciones adicionales, consulta otros métodos de integración.

• Integración basada en código: Integra el SDK de Web Braze directamente en tu código base utilizando tu administrador de paquetes preferido o el CDN de Braze. Esto te permite controlar totalmente cómo se carga y configura el SDK.
• Google Tag Manager: Una solución sin código que te permite realizar la integración del SDK de Web Braze sin modificar el código de tu sitio web. Para obtener más información, consulta Google Tag Manager con el SDK de Braze.

• code-based integration
• google tag manager

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

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

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

Filtrado del tráfico de bots

Los MAU pueden incluir un porcentaje de usuarios bot, lo que infla tu recuento de usuarios activos al mes. 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 identidad del usuario: Los bots sofisticados pueden imitar a 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

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:

Requiere 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.

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 usuarios activos mensuales (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 para filtrar 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. También puedes habilitar el registro básico o personalizado. Para obtener un resumen centralizado de todas las plataformas, consulta Registro detallado.

Registro básico

• before initialization
• after initialization

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

Registro personalizado

UtilizasetLogger 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

Sustituye STRING por tu mensaje como parámetro de una sola cadena. Tu método debe 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();

Actualizar el SDK

Cuando haces referencia al SDK web de Braze desde nuestra red de entrega de contenidos, por ejemplo,https://js.appboycdn.com/web-sdk/a.a/braze.min.js (tal y como recomiendan nuestras instrucciones de integración predeterminadas), tus usuarios reciben actualizaciones menores (correcciones de errores y características compatibles con versiones anteriores, versionesa.a.a hastaa.a.z en los ejemplos anteriores) automáticamente cuando actualizan tu sitio.

Sin embargo, cuando lanzamos cambios importantes, es necesario que actualices manualmente el SDK Web de Braze para garantizar que los cambios significativos no afecten a tu integración. Además, si descargas nuestro SDK y lo alojas tú mismo, no recibirás ninguna actualización de versión automáticamente y deberás actualizarlo manualmente para disfrutar de las últimas características y correcciones de errores.

Puedes mantenerte al día de nuestra última versión siguiendo nuestra fuente de versiones con el lector RSS o el servicio que prefieras, y consultar nuestro registro de cambios para conocer el historial completo de versiones de nuestro SDK para la Web. Para actualizar el SDK Web de Braze:

• Actualiza la versión de la biblioteca 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 administrador de paquetes.
• Si tienes integrado el push web, actualiza el archivo del prestador de servicios en tu sitio: por defecto, 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 que funcionen correctamente.

Otros métodos de integración

Páginas móviles aceleradas (AMP)

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ódulo asíncrono (AMD)

Desactivar soporte técnico

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 incluya compatibilidad con AMD. Esta versión de la biblioteca puede cargarse desde la siguiente ubicación CDN:

Cargador de módulos

Si utilizas RequireJS u otros cargadores de módulos AMD, te recomendamos que autoalojes una copia de nuestra biblioteca y la referencies como 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();
});

Electrón

Electron no admite oficialmente notificaciones push web (consulta esta incidencia de GitHub). Hay otras soluciones de código abierto que puedes probar y que no han sido probadas por Braze.

Marco Jest

Al utilizar Jest, es posible que aparezca 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)"
  ]
}

Marcos SSR

Si utilizas un marco de trabajo de renderizado del lado del servidor (SSR), como Next.js, es posible que encuentres errores, ya que el SDK está diseñado para ejecutarse en un entorno de navegador. Puedes resolver estos problemas importando dinámicamente el SDK.

Puedes conservar las ventajas de la arborescencia al hacerlo exportando las partes del SDK que necesites en un archivo aparte y luego importando dinámicamente ese archivo en tu componente.

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

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

Alternativamente, si utilizas webpack para empaquetar tu aplicación, puedes aprovechar sus comentarios mágicos para importar dinámicamente sólo las partes del SDK que necesites.

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();
    });
}, []);

Tealium iQ

Tealium iQ ofrece una integración básica de Braze llave en mano. Para configurar la integración, busca Braze en la interfaz de gestión de etiquetas de Tealium y proporciona la clave de API de SDK Web desde tu panel.

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

Vite

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

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

Otros administradores de etiquetas

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