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 emplazamientos en tu aplicación

Para actualizar emplazamientos, llama a requestBannersRefresh() para 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 conocer cuántos emplazamientos puedes solicitar por actualización, consulta Acerca de las solicitudes de emplazamiento. Puedes actualizar distintos conjuntos de emplazamientos a lo largo del tiempo (por ejemplo, los emplazamientos de 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 más recientes 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 la suscripción a eventos de Banner varía según la plataforma:

• iOS y Android: subscribeToBannersEvents() en Android (o subscribeToEvents() en Swift) registra un controlador de eventos. 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 subscribeToBannersEvents() (o el obsoleto 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 reinician tras 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

  Web: 7.0.0+  

Usa subscribeToBannersEvents para escuchar eventos de Banner, y luego llama a requestBannersRefresh para obtener emplazamientos. El SDK llama a tu controlador con un objeto de evento. Usa event.type en un switch para manejar cada tipo de evento. Para más información sobre los valores de evento, consulta Suscripciones a eventos.

• javascript
• react

Si usas JavaScript vanilla con el SDK de Braze para Web, registra tu controlador antes de llamar a requestBannersRefresh.

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
54
55
56
57

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

const placementIds = ["global_banner", "navigation_square_banner"];

// - Available in version 7.0.0+
const subscriptionId = braze.subscribeToBannersEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
      // Sent once, right away, with the Banners that are already cached.
      // Render them now instead of waiting for the network.
      console.log("Cached Banners:", Object.keys(event.cacheSnapshot.banners));
      break;

    case braze.ChannelEventType.CACHE_LOAD:
      // The cache changed without a refresh, such as after changeUser().
      // The snapshot can be empty, so clear Banners from the previous user.
      console.log("Cache reloaded:", Object.keys(event.cacheSnapshot.banners));
      break;

    case braze.ChannelEventType.DATA_UPDATED:
      // A refresh finished, even if nothing changed, or a Banner was dismissed.
      console.log("Banners were updated:", event.reason);
      break;

    case braze.ChannelEventType.ERROR:
      switch (event.retryState) {
        case braze.RetryState.SDK_WILL_RETRY:
          // The SDK is retrying. Keep the current Banners and wait.
          break;
        case braze.RetryState.INTEGRATOR_MAY_RETRY: {
          // The SDK stopped retrying. Try again later, and limit how often you retry.
          const delayMs = event.rateLimitedUntil
            ? Math.max(event.rateLimitedUntil.getTime() - Date.now(), 0)
            : 30000;
          setTimeout(() => braze.requestBannersRefresh(placementIds), delayMs);
          break;
        }
        case braze.RetryState.DO_NOT_RETRY:
          // The failure is final. For example, Banners are disabled for this workspace.
          if (event.reason === braze.ChannelErrorReason.FEATURE_DISABLED) {
            // Hide the Banner containers.
          }
          break;
      }
      break;
  }
});

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

// Always refresh after your subscriber function has been registered
braze.requestBannersRefresh(placementIds);

// Remove the subscription when you no longer need it
// braze.removeSubscription(subscriptionId);

Si usas React con el SDK de Braze para Web, configura subscribeToBannersEvents 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
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

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

useEffect(() => {
  const placementIds = ["global_banner", "navigation_square_banner"];

  // - Available in version 7.0.0+
  const subscriptionId = braze.subscribeToBannersEvents((event) => {
    switch (event.type) {
      case braze.ChannelEventType.CACHE_REPLAY:
      case braze.ChannelEventType.CACHE_LOAD:
        // Cached Banners, sent right away on subscribe or after the cache reloads
        console.log("Cached Banners:", Object.keys(event.cacheSnapshot.banners));
        break;

      case braze.ChannelEventType.DATA_UPDATED:
        // A refresh finished, even if nothing changed, or a Banner was dismissed
        console.log("Banners were updated:", event.reason);
        break;

      case braze.ChannelEventType.ERROR:
        if (event.retryState === braze.RetryState.INTEGRATOR_MAY_RETRY) {
          // The SDK stopped retrying. Try again later, and limit how often you retry.
          const delayMs = event.rateLimitedUntil
            ? Math.max(event.rateLimitedUntil.getTime() - Date.now(), 0)
            : 30000;
          setTimeout(() => braze.requestBannersRefresh(placementIds), delayMs);
        }
        break;
    }
  });

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

  // Always refresh after your subscriber function has been registered
  braze.requestBannersRefresh(placementIds);

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

Para saber cuándo se activa cada evento y qué significa cada motivo de actualización, estado de reintento, acción de análisis y motivo de error, consulta Suscripciones a eventos.

event.cacheSnapshot.banners es un objeto que asigna cada ID de emplazamiento a su Banner. Puede incluir emplazamientos de actualizaciones anteriores, no solo los ID de emplazamiento de tu llamada más reciente a requestBannersRefresh. Si solo te interesan ciertos emplazamientos, lee esos ID de emplazamiento del snapshot y omite el resto.

Usa subscribeToBannersEvents en el SDK de Web 7.0.0 y posteriores. subscribeToBannersUpdates es el patrón anterior, obsoleto a partir de la versión 7.0.0. El patrón anterior solo entrega los Banners actuales, por lo que no puede informarte de por qué cambiaron los Banners o cuándo falló una actualización.

  Swift: 19.0.0+  

Nota

Tu listener de actualización de banner refleja el estado del 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. Una vez que hayas registrado tu listener, llama a requestBannersRefresh para los emplazamientos que deseas sincronizar desde 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
25
26
27

// - Available in version 19.0.0+
let placementIds = ["global_banner", "navigation_square_banner"]
let cancellable = brazeClient.braze()?.banners.subscribeToEvents { event in
  switch event {
  case .cacheReplay(let cacheSnapshot), .cacheLoad(let cacheSnapshot):
    cacheSnapshot.banners.forEach { placementId, banner in
      print("Received banner: \(banner) with placement ID: \(placementId)")
    }
  case .dataUpdated(let cacheSnapshot, let reason):
    cacheSnapshot.banners.forEach { placementId, banner in
      print("Received banner: \(banner) with placement ID: \(placementId)")
    }
  default:
    break
  }
}
// Always refresh after your subscriber is registered
brazeClient.braze()?.banners.requestBannersRefresh(placementIds: placementIds)

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)

Usa subscribeToEvents(_:) en el SDK de Swift 19.0.0 y posteriores. subscribeToUpdates(_:) es el patrón anterior, obsoleto a partir de la versión 19.0.0.

Para saber cuándo se activa cada evento y qué significa cada motivo de actualización, estado de reintento, acción de análisis y motivo de error, consulta Suscripciones a eventos.

  Android: 44.0.0+  

Nota

Tu controlador de eventos de banner refleja el estado del banner en memoria del SDK. Un solo evento 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 controlador y omite el resto. Una vez que hayas registrado tu suscriptor, llama a requestBannersRefresh para los emplazamientos que deseas sincronizar desde Braze.

• java
• kotlin

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

ArrayList<String> placementIds = new ArrayList<>();
placementIds.add("global_banner");
placementIds.add("navigation_square_banner");

// - Available in version 44.0.0+
Braze.getInstance(context).subscribeToBannersEvents(event -> {
  if (event instanceof BannersEvent.CacheReplay) {
    logBanners(((BannersEvent.CacheReplay) event).getCacheSnapshot());
  } else if (event instanceof BannersEvent.CacheLoad) {
    logBanners(((BannersEvent.CacheLoad) event).getCacheSnapshot());
  } else if (event instanceof BannersEvent.DataUpdated) {
    logBanners(((BannersEvent.DataUpdated) event).getCacheSnapshot());
  }
});
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds);

Braze.getInstance(context).subscribeToBannersUpdates(event -> {
  for (Banner banner : event.getBanners()) {
    Log.d(TAG, "Received banner: " + banner.getPlacementId());
  }
});
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds);

private void logBanners(BannersCacheSnapshot cacheSnapshot) {
  for (Banner banner : cacheSnapshot.getBanners().values()) {
    Log.d(TAG, "Received banner: " + banner.getPlacementId());
  }
}

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

val placementIds = listOf("global_banner", "navigation_square_banner")

// - Available in version 44.0.0+
Braze.getInstance(context).subscribeToBannersEvents { event ->
  when (event) {
    is BannersEvent.CacheReplay -> logBanners(event.cacheSnapshot)
    is BannersEvent.CacheLoad -> logBanners(event.cacheSnapshot)
    is BannersEvent.DataUpdated -> logBanners(event.cacheSnapshot)
    else -> {}
  }
}
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds)

Braze.getInstance(context).subscribeToBannersUpdates { event ->
  event.banners.forEach { banner ->
    Log.d(TAG, "Received banner: ${banner.placementId}")
  }
}
// Always refresh after your subscriber is registered
Braze.getInstance(context).requestBannersRefresh(placementIds)

private fun logBanners(cacheSnapshot: BannersCacheSnapshot) {
  cacheSnapshot.banners.values.forEach { banner ->
    Log.d(TAG, "Received banner: ${banner.placementId}")
  }
}

Los eventos llegan en un hilo en segundo plano. Cambia al hilo principal antes de actualizar las vistas.

Usa subscribeToBannersEvents en el SDK de Android 44.0.0 y posteriores. subscribeToBannersUpdates es el patrón anterior, obsoleto a partir de la versión 44.0.0.

Para saber cuándo se activa cada evento y qué significa cada motivo de actualización, estado de reintento, acción de análisis y motivo de error, consulta Suscripciones a eventos.

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 usando 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 usas JavaScript vanilla con el SDK de Braze para Web, 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
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
54
55
56
57
58

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

// - Available in version 7.0.0+
braze.subscribeToBannersEvents((event) => {
  const container = document.getElementById("global-banner-container");

  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
    case braze.ChannelEventType.CACHE_LOAD:
    case braze.ChannelEventType.DATA_UPDATED: {
      // get this placement's banner. If it's missing the user did not qualify for one.
      const globalBanner = event.cacheSnapshot.banners["global_banner"];
      if (!globalBanner) {
        container.style.display = "none";
        return;
      }

      // 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
      container.style.display = globalBanner.isControl ? "none" : "";
      break;
    }
    case braze.ChannelEventType.ERROR:
      if (event.reason === braze.ChannelErrorReason.FEATURE_DISABLED) {
        // Banners are disabled, so hide the container
        container.style.display = "none";
      }
      break;
  }
});

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

  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"]);

Usa subscribeToBannersEvents en el SDK de Web 7.0.0 y posteriores. subscribeToBannersUpdates es el patrón anterior, obsoleto a partir de la versión 7.0.0.

Si usas React con el SDK de Braze para Web, 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 registrar impresiones, asegúrate de llamar a insertBanner para isControl. Luego puedes ocultar o colapsar 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 que no cambiaron 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 que no cambiaron permanecen tal cual. Llamar a changeUser() sigue actualizando cada BannerView registrado.

• 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 layout 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 usas Android Views, utiliza 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 las demás dependencias del SDK de Android de Braze. Este módulo es independiente de android-sdk-ui e incluye el composable Banner en com.braze.jetpackcompose.banners.

Nota

Algunas bibliotecas de UI de Compose 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 cambie el tamaño del banner. Como referencia, consulta la documentación 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 usas la nueva arquitectura de React Native, necesitas registrar BrazeBannerView como 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 usas métodos del SDK para insertar un Banner—así que no es necesario rastrear las impresiones de forma manual.

Registro de clics

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

Contenido estándar de Banner (automático)

Si estás utilizando los métodos predeterminados del SDK para insertar Banners, y tu Banner usa componentes estándar del editor (imágenes, botones, texto), los clics se rastrean automáticamente. El SDK adjunta escuchadores 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 Custom Code en el panel de Braze, debes usar brazeBridge.logClick() para registrar los clics desde dentro de ese HTML personalizado. Esto aplica incluso cuando usas métodos del SDK para renderizar el Banner, porque el SDK no puede adjuntar automáticamente escuchadores 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. Debido a que el SDK no está renderizando el Banner, no tiene forma de rastrear automáticamente las interacciones con los elementos de tu interfaz de usuario personalizada.

Para las firmas de métodos y los 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 fue “visto”. Construye una lógica robusta para lo que cuenta como una impresión y así 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 ser visible al hacer scroll 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 pulse tu Banner personalizado (o un botón específico). Pasa el buttonId opcional cuando el clic sea en 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 activamente. 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 necesarias para registrar los 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 Custom Code, puedes desencadenar un descarte directamente desde el HTML del banner usando brazeBridge.closeMessage().

1
2
3

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

Descartar un banner programáticamente

Si estás usando 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 maneja 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. Es seguro llamar al método de descarte varias veces: el SDK ignora las llamadas duplicadas para el mismo banner.

Estas son las versiones mínimas del SDK necesarias 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. En Web SDK 7.0.0 o posterior, también puedes escuchar el evento DISMISS de braze.subscribeToBannersEvents().

• javascript
• react

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

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

// - Available in version 7.0.0+
braze.subscribeToBannersEvents((event) => {
  if (
    event.type !== braze.ChannelEventType.CACHE_REPLAY &&
    event.type !== braze.ChannelEventType.CACHE_LOAD &&
    event.type !== braze.ChannelEventType.DATA_UPDATED
  ) {
    return;
  }

  const banner = event.cacheSnapshot.banners["global_banner"];

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

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"]);

Usa subscribeToBannersEvents en Web SDK 7.0.0 y posteriores. subscribeToBannersUpdates es el patrón anterior, obsoleto a partir de la versión 7.0.0.

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

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

useEffect(() => {
  // - Available in version 7.0.0+
  const subscriptionId = braze.subscribeToBannersEvents((event) => {
    if (
      event.type !== braze.ChannelEventType.CACHE_REPLAY &&
      event.type !== braze.ChannelEventType.CACHE_LOAD &&
      event.type !== braze.ChannelEventType.DATA_UPDATED
    ) {
      return;
    }

    const banner = event.cacheSnapshot.banners["global_banner"];

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

  const deprecatedSubscriptionId = 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);
    braze.removeSubscription(deprecatedSubscriptionId);
  };
}, []);

Usa subscribeToBannersEvents en Web SDK 7.0.0 y posteriores. subscribeToBannersUpdates es el patrón anterior, obsoleto a partir de la versión 7.0.0.

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 pueden 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 anteriormente 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 renderice.
• 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
});