Administrar ubicaciones de Banner

Aprende a crear y administrar ubicaciones de Banner en el SDK de Braze, incluido el acceso a sus propiedades únicas y el registro de impresiones. Para obtener información más general, consulta Acerca de los Banner.

Acerca de las solicitudes de ubicación

Cuando creas ubicaciones en tu aplicación o sitio web, tu aplicación envía una solicitud a Braze para obtener mensajes de banner para cada ubicación.

• Puedes solicitar hasta 10 ubicaciones por cada solicitud de actualización.
• Para cada ubicación, Braze devuelve el banner con mayor prioridad para el que el usuario es elegible.
• Si se solicitan más de 10 ubicaciones en una actualización, solo se devuelven las primeras 10; el resto se descartan.

Por ejemplo, una aplicación podría solicitar tres ubicaciones en una solicitud de actualización: homepage_promo, cart_abandonment y seasonal_offer. Cada solicitud devuelve el banner más relevante para esa ubicación.

Límite de velocidad para las solicitudes de actualización

Si utilizas versiones anteriores del SDK (anteriores a Swift 13.1.0, Android 38.0.0, Web 6.1.0, React Native 17.0.0 y Flutter 15.0.0), solo se permite una solicitud de actualización por sesión de usuario.

Si utilizas versiones mínimas más recientes del SDK (Swift 13.1.0+, Android 38.0.0+, Web 6.1.0+, React Native 17.0.0+ y Flutter 15.0.0+), las solicitudes de actualización se controlan mediante un algoritmo de token bucket para evitar un sondeo excesivo:

• Cada sesión de usuario comienza con cinco tokens de actualización.
• Los tokens se recargan a una tasa de un token cada 180 segundos (3 minutos).

Cada llamada explícita a requestBannersRefresh consume un token. La actualización automática que ocurre al inicio de una nueva sesión o cuando se llama a changeUser no consume un token, ya que esta actualización es una publicación del último banner almacenado en caché para ese usuario. Si intentas actualizar cuando no hay tokens disponibles, el SDK no realiza la solicitud y registra un error hasta que se repone un token. Esto es importante para las actualizaciones a mitad de sesión y las desencadenadas por eventos. Para implementar actualizaciones dinámicas (por ejemplo, después de que un usuario complete una acción en la misma página), llama al método de actualización después de que se registre el evento personalizado, pero ten en cuenta el retraso necesario para que Braze ingiera y procese el evento antes de que el usuario reúna los requisitos para una Campaign de banner diferente.

Crear un emplazamiento

Requisitos previos

Estas son las versiones mínimas del SDK necesarias para crear emplazamientos de Banner:

Paso 1: Crear ubicaciones en Braze

Si aún no lo has hecho, tendrás que crear ubicaciones para Banners en Braze, que se utilizan para definir los lugares en tu aplicación o sitio que pueden mostrar Banners. Para crear una ubicación, ve a Configuración > Ubicaciones de Banners y, a continuación, selecciona Crear ubicación.

Dale un nombre a tu ubicación y asígnale un ID de ubicación. Asegúrate de consultar a otros equipos antes de asignar un ID, ya que se utilizará durante todo el ciclo de vida de la tarjeta y no debería cambiarse posteriormente. Para más información, consulta ID de ubicación.

Paso 2: Actualizar los emplazamientos en tu aplicación

Para actualizar los emplazamientos, llama a requestBannersRefresh() en tu SDK.

requestBannersRefresh() se fusiona con la caché de Banner existente. Solo los ID de emplazamiento que pases se añaden, actualizan o eliminan:

• Si el servidor devuelve un Banner para un emplazamiento solicitado, el Banner en caché para ese emplazamiento se reemplaza.
• Si el servidor no devuelve ningún Banner para un emplazamiento solicitado, ese emplazamiento se elimina de la caché.
• Los Banners en caché para emplazamientos que no solicitaste permanecen en la caché hasta su expiración.

Para saber cuántos emplazamientos puedes solicitar por actualización, consulta Acerca de las solicitudes de emplazamiento. Puedes actualizar diferentes conjuntos de emplazamientos a lo largo del tiempo (por ejemplo, los emplazamientos en la pantalla actual) y mantener los Banners de otros emplazamientos en la caché.

El comportamiento de actualización de Banner tiene dos vías:

1. Actualización explícita: Puedes llamar al método de actualización en cualquier momento durante una sesión activa.
2. Actualización automática en una nueva sesión: Después de realizar al menos una solicitud de actualización explícita, el SDK puede volver a solicitar los ID de emplazamiento solicitados más recientemente cuando se inicia una nueva sesión de Braze (por ejemplo, después de changeUser() o después de un tiempo de espera de sesión).

El papel de subscribeToBannersUpdates() varía según la plataforma:

• iOS y Android: subscribeToBannersUpdates() (o subscribeToUpdates() en Swift) registra una devolución de llamada de actualización. La actualización automática al inicio de sesión no depende de que la suscripción esté activa.
• Web: La actualización automática al inicio de sesión está vinculada a que subscribeToBannersUpdates() esté registrado. Sin una suscripción activa, el SDK no repite automáticamente la actualización en una nueva sesión.

En todos los casos, debes realizar al menos una solicitud de actualización explícita por ciclo de vida de la aplicación para que el SDK sepa qué ID de emplazamiento mantener actualizados. Los Banners no se obtienen automáticamente en el primer lanzamiento sin esa llamada inicial, y los ID de emplazamiento rastreados se restablecen después de reiniciar la aplicación.

Las actualizaciones automáticas al inicio de sesión no consumen un token de límite de velocidad.

Consejo

Actualiza los emplazamientos lo antes posible para evitar retrasos en la descarga o visualización de Banners.

• web
• swift
• android
• react native
• unity
• cordova
• flutter
• roku

1
2
3

import * as braze from "@braze/web-sdk";

braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

1

AppDelegate.braze?.banners.requestBannersRefresh(placementIds: ["global_banner", "navigation_square_banner"])

1
2
3
4

ArrayList<String> placementIds = new ArrayList<>();
placementIds.add("global_banner");
placementIds.add("navigation_square_banner");
Braze.getInstance(context).requestBannersRefresh(placementIds);

1

Braze.getInstance(context).requestBannersRefresh(listOf("global_banner", "navigation_square_banner"))

1

Braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

1

This feature is not currently supported on Unity.

1

This feature is not currently supported on Cordova.

1

braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

1

This feature is not currently supported on Roku.

Paso 3: Escuchar actualizaciones

Consejo

Si insertas Banners utilizando los métodos del SDK de esta guía, todos los eventos de análisis (como impresiones y clics) se gestionan automáticamente, y las impresiones solo se registran cuando el banner está visible.

• web
• swift
• android
• react native
• unity
• cordova
• flutter
• roku

• javascript
• react

Si estás utilizando JavaScript estándar con el SDK Web de Braze, usa subscribeToBannersUpdates para escuchar actualizaciones de emplazamientos y luego llama a requestBannersRefresh para obtenerlas.

1
2
3
4
5
6
7
8

import * as braze from "@braze/web-sdk";

braze.subscribeToBannersUpdates((banners) => {
  console.log("Banners were updated");
});

// always refresh after your subscriber function has been registered
braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

Si estás utilizando React con el SDK Web de Braze, configura subscribeToBannersUpdates dentro de un hook useEffect y llama a requestBannersRefresh después de registrar tu listener.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import * as braze from "@braze/web-sdk";

useEffect(() => {
  const subscriptionId = braze.subscribeToBannersUpdates((banners) => {
    console.log("Banners were updated");
  });

  // always refresh after your subscriber function has been registered
  braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

  // cleanup listeners
  return () => {
    braze.removeSubscription(subscriptionId);
  }
}, []);

Nota

Tu listener de actualizaciones de banner refleja el estado de banner en memoria del SDK. Una sola actualización puede incluir emplazamientos que ya estaban en caché (por ejemplo, de una actualización anterior, otra pantalla o trabajo automático del SDK), no solo los ID de emplazamiento de tu llamada más reciente a requestBannersRefresh. Si solo te interesan ciertos emplazamientos, comprueba el ID de emplazamiento de cada banner en tu listener y omite el resto. Cuando hayas registrado tu listener, llama a requestBannersRefresh para los emplazamientos que quieras sincronizar desde Braze.

1
2
3
4
5
6
7
8

let placementIds = ["global_banner", "navigation_square_banner"]
let cancellable = brazeClient.braze()?.banners.subscribeToUpdates { banners in
  banners.forEach { placementId, banner in
    print("Received banner: \(banner) with placement ID: \(placementId)")
  }
}
// Always refresh after your subscriber is registered
brazeClient.braze()?.banners.requestBannersRefresh(placementIds: placementIds)

Nota

Tu listener de actualizaciones de banner refleja el estado de banner en memoria del SDK. Una sola actualización puede incluir emplazamientos que ya estaban en caché (por ejemplo, de una actualización anterior, otra pantalla o trabajo automático del SDK), no solo los ID de emplazamiento de tu llamada más reciente a requestBannersRefresh. Si solo te interesan ciertos emplazamientos, comprueba el ID de emplazamiento de cada banner en tu listener y omite el resto. Cuando hayas registrado tu listener, llama a requestBannersRefresh para los emplazamientos que quieras sincronizar desde Braze.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10

ArrayList<String> placementIds = new ArrayList<>();
placementIds.add("global_banner");
placementIds.add("navigation_square_banner");
Braze.getInstance(context).subscribeToBannersUpdates(banners -> {
  for (Banner banner : banners.getBanners()) {
    Log.d(TAG, "Received banner: " + banner.getPlacementId());
  }
});
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds);

1
2
3
4
5
6
7
8

val placementIds = listOf("global_banner", "navigation_square_banner")
Braze.getInstance(context).subscribeToBannersUpdates { update ->
  for (banner in update.banners) {
    Log.d(TAG, "Received banner: " + banner.placementId)
  }
}
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds)

1
2
3
4
5
6
7
8
9
10

const bannerCardsSubscription = Braze.addListener(
  Braze.Events.BANNER_CARDS_UPDATED,
  (data) => {
    const banners = data.banners;
    console.log(
      `Received ${banners.length} Banner Cards with placement IDs:`,
      banners.map((banner) => banner.placementId)
    );
  }
);

1

This feature is not currently supported on Unity.

1

This feature is not currently supported on Cordova.

1
2
3
4
5

StreamSubscription bannerStreamSubscription = braze.subscribeToBanners((List<BrazeBanner> banners) {
  for (final banner in banners) {
    print("Received banner: " + banner.toString());
  }
});

1

This feature is not currently supported on Roku.

Paso 4: Insertar mediante el ID de emplazamiento

Consejo

Para un tutorial completo paso a paso, consulta Mostrar un Banner por ID de emplazamiento.

• web
• swift
• android
• react native
• unity
• cordova
• flutter
• roku

Crea un elemento contenedor para el Banner. Asegúrate de establecer su ancho y alto.

1

<div id="global-banner-container" style="width: 100%; height: 450px;"></div>

• javascript
• react

Si estás utilizando JavaScript estándar con el SDK Web de Braze, llama al método insertBanner para reemplazar el HTML interno del elemento contenedor.

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

import * as braze from "@braze/web-sdk";

braze.initialize("sdk-api-key", {
  baseUrl: "sdk-base-url",
  allowUserSuppliedJavascript: true, // banners require you to opt-in to user-supplied javascript
});

braze.subscribeToBannersUpdates((banners) => {
  // get this placement's banner. If it's `null` the user did not qualify for one.
  const globalBanner = braze.getBanner("global_banner");
  if (!globalBanner) {
    return;
  }

  // choose where in the DOM you want to insert the banner HTML
  const container = document.getElementById("global-banner-container");

  // Insert the banner which replaces the innerHTML of that container
  braze.insertBanner(globalBanner, container);

  // Special handling if the user is part of a Control Variant
  if (globalBanner.isControl) {
    // hide or collapse the container
    container.style.display = "none";
  }
});

braze.requestBannersRefresh(["global_banner", "navigation_square_banner"]);

Si estás utilizando React con el SDK Web de Braze, llama al método insertBanner con un ref para reemplazar el HTML interno del elemento contenedor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import { useRef } from 'react';
import * as braze from "@braze/web-sdk";

export default function App() {
    const bannerRef = useRef<HTMLDivElement>(null);

    useEffect(() => {
       const globalBanner = braze.getBanner("global_banner");
       if (!globalBanner || globalBanner.isControl) {
           // hide the container
       } else {
           // insert the banner to the container node
           braze.insertBanner(globalBanner, bannerRef.current);
       }
    }, []);
    return <div ref={bannerRef}></div>
}

Consejo

Para rastrear impresiones, asegúrate de llamar a insertBanner para isControl. Después puedes ocultar o contraer tu contenedor.

Después de una actualización, el SDK actualiza un BannerUIView o BannerView solo cuando el contenido en caché de ese emplazamiento cambia (se añade, elimina o actualiza). Los Banners mostrados sin cambios permanecen tal cual. Llamar a changeUser() actualiza todas las vistas de Banner registradas.

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

// To get access to the Banner model object:
let globalBanner: Braze.Banner?
AppDelegate.braze?.banners.getBanner(for: "global_banner", { banner in
  self.globalBanner = banner
})

// UIKit implementation:
// If you simply want the Banner view, initialize a `UIView` with the placement ID:
if let braze = AppDelegate.braze {
  let bannerUIView = BrazeBannerUI.BannerUIView(
    placementId: "global_banner",
    braze: braze,
    // iOS does not perform automatic resizing or visibility changes.
    // Use the `processContentUpdates` parameter to adjust the size and visibility of your Banner according to your use case.
    processContentUpdates: { result in
      switch result {
      case .success(let updates):
        if let height = updates.height {
          // Adjust the visibility and/or height.
        }
      case .failure(let error):
        // Handle the error.
      }
    }
  )
}

// SwiftUI implementation:
// Similarly, if you want a Banner view in SwiftUI, use the corresponding `BannerView` initializer:
if let braze = AppDelegate.braze {
  let bannerView = BrazeBannerUI.BannerView(
    placementId: "global_banner",
    braze: braze,
    // iOS does not perform automatic resizing or visibility changes.
    // Use the `processContentUpdates` parameter to adjust the size and visibility of your Banner according to your use case.
    processContentUpdates: { result in
      switch result {
      case .success(let updates):
        if let height = updates.height {
          // Adjust the visibility and/or height according to your parent controller.
        }
      case .failure(let error):
        // Handle the error.
      }
    }
  )
}

Después de una actualización, el SDK actualiza un BannerView solo cuando el contenido en caché de ese emplazamiento cambia (se añade, elimina o actualiza). Los Banners mostrados sin cambios permanecen tal cual. Llamar a changeUser() sigue actualizando todos los BannerView registrados.

• java
• kotlin

Para obtener el Banner en código Java, usa:

1

Banner globalBanner = Braze.getInstance(context).getBanner("global_banner");

Puedes crear Banners en el diseño de tus vistas de Android incluyendo este XML:

1
2
3
4
5

<com.braze.ui.banners.BannerView
    android:id="@+id/global_banner_id"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:placementId="global_banner" />

Si estás utilizando Android Views, usa este XML:

1
2
3
4
5

<com.braze.ui.banners.BannerView
    android:id="@+id/global_banner_id"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:placementId="global_banner" />

Para usar Jetpack Compose, añade el artefacto com.braze:android-sdk-jetpack-compose a tu módulo de aplicación. Usa la misma versión que tus otras dependencias del SDK Android de Braze. Este módulo es independiente de android-sdk-ui y proporciona el composable Banner bajo com.braze.jetpackcompose.banners.

Nota

Algunas bibliotecas de Compose UI definen su propio composable Banner. Importa com.braze.jetpackcompose.banners.Banner explícitamente para asegurarte de llamar a la API de Braze.

1
2
3
4
5
6

import com.braze.jetpackcompose.banners.Banner

@Composable
fun myBannerSlot() {
    Banner(placementId = "global_banner")
}

Opcionalmente, pasa heightCallback para recibir la altura renderizada en dp cuando el tamaño del banner cambie. Para más información, consulta la KDoc de Banner.

Si no añades el módulo de Jetpack Compose, envuelve BannerView en AndroidView:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import android.view.ViewGroup
import androidx.compose.runtime.Composable
import androidx.compose.ui.viewinterop.AndroidView
import com.braze.ui.banners.BannerView

@Composable
fun myBannerSlot() {
    AndroidView(
        factory = { context ->
            BannerView(context, "global_banner").apply {
                layoutParams = ViewGroup.LayoutParams(
                    ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.WRAP_CONTENT
                )
            }
        },
        update = { it.placementId = "global_banner" }
    )
}

Para obtener el Banner en Kotlin, usa:

1

val banner = Braze.getInstance(context).getBanner("global_banner")

Si estás utilizando la nueva arquitectura de React Native, necesitas registrar BrazeBannerView como un componente Fabric en tu AppDelegate.mm.

1
2
3
4
5
6
7
8

#ifdef RCT_NEW_ARCH_ENABLED
/// Register the `BrazeBannerView` for use as a Fabric component.
- (NSDictionary<NSString *,Class<RCTComponentViewProtocol>> *)thirdPartyFabricComponents {
  NSMutableDictionary * dictionary = [super thirdPartyFabricComponents].mutableCopy;
  dictionary[@"BrazeBannerView"] = [BrazeBannerView class];
  return dictionary;
}
#endif

Para la integración más sencilla, añade el siguiente fragmento de JavaScript XML (JSX) en tu jerarquía de vistas, proporcionando solo el ID de emplazamiento.

1
2
3

<Braze.BrazeBannerView
  placementId='global_banner'
/>

Para obtener el modelo de datos del Banner en React Native, o para comprobar la presencia de ese emplazamiento en la caché de tu usuario, usa:

1

const banner = await Braze.getBanner("global_banner");

1

This feature is not currently supported on Unity.

1

This feature is not currently supported on Cordova.

Para la integración más sencilla, añade el siguiente widget en tu jerarquía de vistas, proporcionando solo el ID de emplazamiento.

1
2
3
4

BrazeBannerView(
  placementId: "global_banner",
),
To get the Banner's data model in Flutter, use:

Puedes usar el método getBanner para comprobar la presencia de ese emplazamiento en la caché de tu usuario.

1
2
3
4
5
6
7

braze.getBanner("global_banner").then((banner) {
  if (banner == null) {
    // Handle null cases.
  } else {
    print(banner.toString());
  }
});

1

This feature is not currently supported on Roku.

Paso 5: Enviar un Banner de prueba (opcional)

Antes de lanzar una Campaign de Banner, puedes enviar un Banner de prueba para verificar tu integración. Los Banners de prueba se almacenan en una caché en memoria separada y no persisten entre reinicios de la aplicación. Aunque no se necesita configuración adicional, tu dispositivo de prueba debe ser capaz de recibir notificaciones push en primer plano para poder mostrar la prueba.

Nota

Los Banners de prueba son como cualquier otro banner, excepto que se eliminan en la siguiente sesión de la aplicación.

Registrar impresiones

Braze registra automáticamente las impresiones de los Banners que están a la vista cuando utilizas métodos del SDK para insertar un Banner—así que no es necesario realizar el seguimiento de las impresiones de forma manual.

Registro de clics

El método utilizado para registrar los clics en los Banner depende de cómo se renderiza tu Banner y de dónde se encuentra tu controlador de clics.

Contenido estándar del Banner (automático)

Si utilizas los métodos predeterminados del SDK listos para usar para insertar Banners, y tu Banner utiliza componentes estándar del editor (imágenes, botones, texto), los clics se rastrean automáticamente. El SDK adjunta receptores de clics a estos elementos y no se necesita código adicional.

Bloques de código personalizado

Si tu Banner utiliza el bloque de editor Código personalizado en el panel de Braze, debes usar brazeBridge.logClick() para registrar los clics desde ese HTML personalizado. Esto aplica incluso cuando usas métodos del SDK para renderizar el Banner, porque el SDK no puede adjuntar automáticamente receptores a los elementos dentro de tu código personalizado.

1
2
3

<button onclick="brazeBridge.logClick()">
  Click me
</button>

Para la referencia completa, consulta Código personalizado y pont JavaScript para Banners. El brazeBridge proporciona una capa de comunicación entre el HTML interno del Banner y el SDK de Braze principal.

Implementaciones de interfaz de usuario personalizadas (headless)

Si estás construyendo una interfaz de usuario completamente personalizada utilizando las propiedades personalizadas del Banner en lugar de renderizar el HTML del Banner, debes registrar manualmente los clics y las impresiones desde el código de tu aplicación. Dado que el SDK no está renderizando el Banner, no tiene forma de rastrear automáticamente las interacciones con tus elementos de interfaz de usuario personalizados.

Para las firmas de métodos y detalles completos, consulta la documentación de referencia del SDK de Braze.

Registro de impresiones

Llama al método de impresión de Banner de la plataforma cuando tu interfaz de usuario personalizada considere que el Banner ha sido “visto”. Construye una lógica robusta para determinar qué cuenta como una impresión y evitar eventos duplicados; por ejemplo, registra solo cuando el Banner entra en la ventana de visualización (o equivalente), y no registres de nuevo cuando el mismo Banner vuelva a desplazarse a la vista o cuando tu componente se vuelva a renderizar sin un nuevo evento de visualización.

• web
• android
• swift
• react native
• flutter

1
2
3
4
5
6
7

import * as braze from "@braze/web-sdk";

// Log impression when your custom UI considers the banner viewed (for example, once when it enters viewport)
const banner = braze.getBanner("placement_id_homepage_top");
if (banner) {
  braze.logBannerImpressions([banner]);
}

1
2

// Log impression when your custom UI considers the banner viewed (for example, once when it enters viewport)
Braze.getInstance(context).logBannerImpression("placement_id_homepage_top")

1
2

// Log impression when your custom UI considers the banner viewed (for example, once when it enters viewport)
Braze.getInstance(context).logBannerImpression("placement_id_homepage_top");

1
2
3
4

// Retrieve a banner and log an impression on it (for example, once when it enters viewport)
braze.banners.getBanner(for: "placement_id_homepage_top") { banner in
  banner?.context.logImpression()
}

1
2

// Log impression when your custom UI considers the banner viewed (for example, once when it enters viewport)
Braze.logBannerImpression("placement_id_homepage_top");

1
2

// Log impression when your custom UI considers the banner viewed (for example, once when it enters viewport)
braze.logBannerImpression("placement_id_homepage_top");

Registro de clics

Llama al método de clic de Banner de la plataforma cuando el usuario toque tu Banner personalizado (o un botón específico). Pasa el buttonId opcional cuando el clic corresponda a un botón específico para que los análisis puedan atribuir el clic correctamente.

• web
• android
• swift
• react native
• flutter

1
2
3
4

import * as braze from "@braze/web-sdk";

// Log click
braze.logBannerClick("placement_id_homepage_top", buttonId);  // buttonID is optional

1
2

// Log click
Braze.getInstance(context).logBannerClick("placement_id_homepage_top", buttonId)  // buttonID parameter can be null

1
2

// Log click
Braze.getInstance(context).logBannerClick("placement_id_homepage_top", buttonId);  // buttonID parameter can be null

1
2
3
4

// Retrieve a banner and log a click on it
braze.banners.getBanner(for: "placement_id_homepage_top") { banner in
  banner?.context.logClick(buttonId: buttonId)  // buttonID is optional
}

1
2

// Log click
Braze.logBannerClick("placement_id_homepage_top", buttonId);  // buttonID is optional

1
2

// Log click
braze.logBannerClicked("placement_id_homepage_top", buttonId);  // buttonID parameter can be null

Registrar descartes

Los descartes de banners eliminan programáticamente un banner de una ubicación cuando un usuario lo descarta de forma activa. Cuando se descarta, el banner se suprime para ese usuario. La próxima vez que se actualice la lista de ubicaciones, se devuelve un nuevo banner si el usuario es elegible para uno.

Requisitos previos

Estas son las versiones mínimas del SDK requeridas para registrar descartes de banners:

Integraciones

Integraciones estándar de banners (editor de arrastrar y soltar)

Si tu banner utiliza el editor de arrastrar y soltar e incluye un componente de botón de descarte, no se requiere código adicional. Cuando un usuario hace clic en el botón de descarte, el mensaje se oculta, se desencadena un descarte y luego se registra un evento de descarte para análisis.

Bloques de código personalizado

Si tu banner utiliza el bloque de editor Código personalizado, puedes desencadenar un descarte directamente desde dentro del HTML del banner usando brazeBridge.closeMessage().

1
2
3

<button onclick="brazeBridge.closeMessage()">
  Dismiss
</button>

Descartar un banner programáticamente

Si estás utilizando el BrazeBannerView estándar con el botón de descarte creado en el editor de arrastrar y soltar, no se requiere código adicional; el descarte se gestiona automáticamente.

Para integraciones de interfaz de usuario personalizadas, puedes llamar al método de descarte directamente en tu instancia de Braze para descartar un banner programáticamente y registrar un evento de descarte. El método de descarte es seguro para llamar varias veces: el SDK ignora las llamadas duplicadas para el mismo banner.

Estas son las versiones mínimas del SDK requeridas para descartar un banner programáticamente:

• web
• android
• swift
• react native
• flutter

1
2
3
4
5
6
7
8

import * as braze from "@braze/web-sdk";

const banners = braze.getAllBanners();
const banner = banners["global_banner"];

if (banner) {
  braze.dismissBanner(banner);
}

1
2
3
4
5
6
7
8

import * as braze from "@braze/web-sdk";

const banners = braze.getAllBanners();
const banner = banners["global_banner"];

if (banner) {
  braze.dismissBanner(banner);
}

1

Braze.getInstance(context).dismissBanner("your-placement-id");

1

Braze.getInstance(context).dismissBanner("your-placement-id")

1
2
3
4
5

// Preferred: dismiss via context.
banner.context?.dismiss()

// Fallback: if context is unavailable.
banner.dismiss(using: braze)

1

Braze.dismissBanner("your-placement-id");

1

braze.dismissBanner("your-placement-id");

Registrar análisis personalizados al descartar un banner

Para ejecutar lógica personalizada cuando se descarta un banner, como registrar análisis, usa la devolución de llamada de descarte de tu SDK. La devolución de llamada recibe un objeto de evento con el placementId, stableKey y trackingId del banner.

• web
• android
• swift
• react native
• flutter

Usa Banner.subscribeToDismissedEvent() para ejecutar lógica personalizada cuando se descarta un banner específico. Suscríbete al evento antes de mostrar el banner.

Nota

Banner.subscribeToDismissedEvent() requiere Web SDK 6.9.0 o posterior. En versiones anteriores, usa braze.subscribeToBannersUpdates() y detecta el descarte comprobando si el banner ya no está presente en el mapa de banners actualizado.

• javascript
• react

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import * as braze from "@braze/web-sdk";

braze.subscribeToBannersUpdates((banners) => {
  const banner = banners["global_banner"];

  if (banner) {
    banner.subscribeToDismissedEvent(() => {
      // Run any custom logic here, such as logging custom analytics
      console.log("Banner was dismissed");
    });
  }
});

braze.requestBannersRefresh(["global_banner"]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import { useEffect } from "react";
import * as braze from "@braze/web-sdk";

useEffect(() => {
  const subscriptionId = braze.subscribeToBannersUpdates((banners) => {
    const banner = banners["global_banner"];

    if (banner) {
      banner.subscribeToDismissedEvent(() => {
        // Run any custom logic here, such as logging custom analytics
        console.log("Banner was dismissed");
      });
    }
  });

  braze.requestBannersRefresh(["global_banner"]);

  return () => {
    braze.removeSubscription(subscriptionId);
  };
}, []);

Establece la propiedad opcional onDismissCallback en BannerView.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import android.util.Log;
import com.braze.ui.banners.BannerView;
import kotlin.Unit;

// After obtaining your BannerView instance (for example from XML via findViewById, or `new BannerView(context, "global_banner")`)

bannerView.setOnDismissCallback((snapshot) -> {
  Log.d(TAG, "placementId: " + snapshot.getPlacementId()
    + ", stableKey: " + snapshot.getStableKey()
    + ", trackingId: " + snapshot.getTrackingId());

  // Run any custom logic here, such as logging custom analytics
  return Unit.INSTANCE;
});

1
2
3
4
5
6
7
8
9
10

import android.util.Log
import com.braze.ui.banners.BannerView

// After obtaining your BannerView instance (for example via findViewById or `BannerView(context, "global_banner")`)

bannerView.onDismissCallback = { snapshot ->
  Log.d(TAG, "placementId: ${snapshot.placementId}, stableKey: ${snapshot.stableKey}, trackingId: ${snapshot.trackingId}")

  // Run any custom logic here, such as logging custom analytics
}

1
2
3
4
5
6
7
8
9

// After initializing your banner view instance using UIKit or SwiftUI

bannerView.onDismiss = { event in
  print("Banner dismissed — placementId: \(event.placementId ?? "unknown")")
  print("  stableKey: \(event.stableKey ?? "unknown")")
  print("  trackingId: \(event.trackingId ?? "unknown")")

  // Run any custom logic here, such as logging custom analytics
}

Establece la propiedad onDismiss en Braze.BrazeBannerView para ejecutar lógica personalizada cuando se descarta un banner.

1
2
3
4
5
6
7
8
9

import Braze from "@braze/react-native-sdk";

<Braze.BrazeBannerView
  placementId="global_banner"
  onDismiss={(event) => {
    console.log("placementId:", event.placementId, "stableKey:", event.stableKey, "trackingId:", event.trackingId);
    // Run any custom logic here, such as logging custom analytics
  }}
/>

Establece el parámetro onDismiss en BrazeBannerView para ejecutar lógica personalizada cuando se descarta un banner.

1
2
3
4
5
6
7

BrazeBannerView(
  placementId: 'global_banner',
  onDismiss: (BrazeBannerDismissEvent event) {
    print('placementId: ${event.placementId}, stableKey: ${event.stableKey}, trackingId: ${event.trackingId}');
    // Run any custom logic here, such as logging custom analytics
  },
)

Límite de almacenamiento de descartes pendientes

Los eventos de descarte se almacenan localmente como entradas pendientes hasta que puedan sincronizarse con el servidor de Braze en la siguiente llamada a requestBannersRefresh.

Advertencia

En casos excepcionales en los que se acumula un gran número de descartes sin una sincronización exitosa, los descartes pendientes más antiguos pueden eliminarse. Si esto ocurre, los banners descartados previamente pueden reaparecer hasta que se complete la siguiente sincronización exitosa. Para minimizar este riesgo, llama a requestBannersRefresh cada vez que tu aplicación recupere la conectividad de red.

Dimensiones y tamaño

Esto es lo que necesitas saber sobre las dimensiones y el tamaño de los Banner:

• Aunque el creador te permite previsualizar los Banner en diferentes dimensiones, esa información no se guarda ni se envía al SDK.
• El HTML ocupará todo el ancho del contenedor en el que se renderiza.
• Te recomendamos crear un elemento de dimensiones fijas y probar esas dimensiones en el creador.

Propiedades personalizadas

Puedes utilizar propiedades personalizadas de tu campaña de banners para recuperar datos clave-valor a través del SDK y modificar el comportamiento o la apariencia de tu aplicación. Por ejemplo, podrías:

• Envía metadatos para tus análisis o integraciones de terceros.
• Usa metadatos como un timestamp u objeto JSON para desencadenar lógica condicional.
• Controla el comportamiento de un Banner basándote en metadatos incluidos como ratio o format.

Requisitos previos

Debes añadir propiedades personalizadas a tu campaña de banners. Además, estas son las versiones mínimas del SDK necesarias para acceder a las propiedades personalizadas:

Acceder a las propiedades personalizadas

Para acceder a las propiedades personalizadas de un banner, utiliza uno de los siguientes métodos según el tipo de propiedad definido en el panel. Si la clave no coincide con una propiedad de ese tipo o no existe, el método devuelve null.

• web
• swift
• android
• react native
• flutter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Returns the Banner instance
const banner = braze.getBanner("placement_id_homepage_top");

// banner may be undefined or null
if (banner) {

  // Returns the string property
  const stringProperty = banner.getStringProperty("color");

  // Returns the boolean property
  const booleanProperty = banner.getBooleanProperty("expanded");

  // Returns the number property
  const numberProperty = banner.getNumberProperty("height");

  // Returns the timestamp property (as a number)
  const timestampProperty = banner.getTimestampProperty("account_start");

  // Returns the image URL property as a string of the URL
  const imageProperty = banner.getImageProperty("homepage_icon");

  // Returns the JSON object property
  const jsonObjectProperty = banner.getJsonProperty("footer_settings");
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// Passes the specified banner to the completion handler
AppDelegate.braze?.banners.getBanner(for: "placement_id_homepage_top") { banner in
  // Returns the string property
  let stringProperty: String? = banner.stringProperty(key: "color")

  // Returns the boolean property
  let booleanProperty: Bool? = banner.boolProperty(key: "expanded")

  // Returns the number property as a double
  let numberProperty: Double? = banner.numberProperty(key: "height")

  // Returns the Unix UTC millisecond timestamp property as an integer
  let timestampProperty: Int? = banner.timestampProperty(key: "account_start")

  // Returns the image property as a String of the image URL
  let imageProperty: String? = banner.imageProperty(key: "homepage_icon")

  // Returns the JSON object property as a [String: Any] dictionary
  let jsonObjectProperty: [String: Any]? = banner.jsonObjectProperty(key: "footer_settings")
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Returns the Banner instance
Banner banner = Braze.getInstance(context).getBanner("placement_id_homepage_top");

// banner may be undefined or null
if (banner != null) {
  // Returns the string property
  String stringProperty = banner.getStringProperty("color");

  // Returns the boolean property
  Boolean booleanProperty = banner.getBooleanProperty("expanded");

  // Returns the number property
  Number numberProperty = banner.getNumberProperty("height");

  // Returns the timestamp property (as a Long)
  Long timestampProperty = banner.getTimestampProperty("account_start");

  // Returns the image URL property as a String of the URL
  String imageProperty = banner.getImageProperty("homepage_icon");

  // Returns the JSON object property as a JSONObject
  JSONObject jsonObjectProperty = banner.getJSONProperty("footer_settings");
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// Returns the Banner instance
val banner: Banner = Braze.getInstance(context).getBanner("placement_id_homepage_top") ?: return

// Returns the string property
val stringProperty: String? = banner.getStringProperty("color")

// Returns the boolean property
val booleanProperty: Boolean? = banner.getBooleanProperty("expanded")

// Returns the number property
val numberProperty: Number? = banner.getNumberProperty("height")

// Returns the timestamp property (as a Long)
val timestampProperty: Long? = banner.getTimestampProperty("account_start")

// Returns the image URL property as a String of the URL
val imageProperty: String? = banner.getImageProperty("homepage_icon")

// Returns the JSON object property as a JSONObject
val jsonObjectProperty: JSONObject? = banner.getJSONProperty("footer_settings")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Get the Banner instance
const banner = await Braze.getBanner('placement_id_homepage_top');
if (!banner) return;

// Get the string property
const stringProperty = banner.getStringProperty('color');

// Get the boolean property
const booleanProperty = banner.getBooleanProperty('expanded');

// Get the number property
const numberProperty = banner.getNumberProperty('height');

// Get the timestamp property (as a number)
const timestampProperty = banner.getTimestampProperty('account_start');

// Get the image URL property as a string
const imageProperty = banner.getImageProperty('homepage_icon');

// Get the JSON object property
const jsonObjectProperty = banner.getJSONProperty('footer_settings');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// Fetch the banner asynchronously
_braze.getBanner(placementId).then(('placement_id_homepage_top') {
  // Get the string property
  final String? stringProperty = banner?.getStringProperty('color');

  // Get the boolean property
  final bool? booleanProperty = banner?.getBooleanProperty('expanded');

  // Get the number property
  final num? numberProperty = banner?.getNumberProperty('height');

  // Get the timestamp property
  final int? timestampProperty = banner?.getTimestampProperty('account_start');

  // Get the image URL property
  final String? imageProperty = banner?.getImageProperty('homepage_icon');

  // Get the JSON object property
  final Map<String, dynamic>? jsonObjectProperty = banner?.getJSONProperty('footer_settings');

  // Use these properties as needed in your UI or logic
});