Administrar la ubicación de los banners

Aprende a crear y administrar ubicaciones de banners 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 banners.

Acerca de las solicitudes de colocació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 usuario que es elegible para recibirlo.
• 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, ycart_abandonment 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 contenedor de tokens 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 arequestBannersRefresh consume un token. 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 actualizaciones que se desencadenan 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 campaña de Banner diferente.

Crear una colocación

Requisitos previos

Estas son las versiones mínimas del SDK necesarias para crear ubicaciones de banners:

Paso 1: Crear colocaciones en Braze

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

Dale un nombre a tu colocación y asígnale un ID de colocació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 colocación.

Paso 2: Actualiza las ubicaciones en tu aplicación

Las ubicaciones se pueden actualizar llamando a los métodos de actualización que se describen a continuación. Estas ubicaciones se almacenarán automáticamente en caché cuando expire la sesión de un usuario o cuando cambies los identificadores de los usuarios utilizando elchangeUsermétodo .

• 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.requestRefresh(placementIds: ["global_banner", "navigation_square_banner"])

1
2
3
4
ArrayList<String> listOfBanners = new ArrayList<>();
listOfBanners.add("global_banner");
listOfBanners.add("navigation_square_banner");
Braze.getInstance(context).requestBannersRefresh(listOfBanners);

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: Escucha las actualizaciones

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

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

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

1
2
3
4
5
let cancellable = brazeClient.braze()?.banners.subscribeToUpdates { banners in
  banners.forEach { placementId, banner in
    print("Received banner: \(banner) with placement ID: \(placementId)")
  }
}

1
2
3
4
5
Braze.getInstance(context).subscribeToBannersUpdates(banners -> {
  for (Banner banner : banners.getBanners()) {
    Log.d(TAG, "Received banner: " + banner.getPlacementId());
  }
});

1
2
3
4
5
Braze.getInstance(context).subscribeToBannersUpdates { update ->
  for (banner in update.banners) {
    Log.d(TAG, "Received banner: " + banner.placementId)
  }
}

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: Inserta utilizando el ID de ubicación.

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

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

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

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

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
// To get access to the Banner model object:
let globalBanner: Braze.Banner?
AppDelegate.braze?.banners.getBanner(for: "global_banner", { banner in
  self.globalBanner = banner
})

// If you simply want the Banner view, you may 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.
      }
    }
  )
}

// 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.
      }
    }
  )
}

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

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" />

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" />

1
Banner(placementId = "global_banner")

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

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

1
2
3
<Braze.BrazeBannerView
  placementID='global_banner'
/>

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.

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

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 campaña de banners, puedes enviar un banner de prueba para verificar tu integración. Los banners de prueba se almacenarán en una caché independiente en memoria y no se conservarán tras reiniciar la aplicación. Aunque no se necesita ninguna configuración adicional, tu dispositivo de prueba debe ser capaz de recibir notificaciones push en primer plano para poder mostrar la prueba.

Impresiones de registro

Braze registra automáticamente las impresiones de los banners que están a la vista cuando utilizas métodos SDK para insertar un banner, por lo que no es necesario realizar un seguimiento manual de las impresiones.

Registro de clics

El método utilizado para registrar los clics en los banners depende de cómo se muestre el banner y de la ubicación del controlador de clics.

Contenido estándar del banner (automático)

Si utilizas métodos SDK predeterminados y listos para usar para insertar banners, y tu banner utiliza componentes de editor estándar (imágenes, botones, texto), los clics se registran automáticamente. El SDK añade detectores de clics a estos elementos, sin necesidad de código adicional.

Bloques de código personalizados

Si tu banner utiliza el bloque de editor de código personalizado en el panel de Braze, debes utilizarbrazeBridge.logClick() para registrar los clics desde ese HTML personalizado. Esto se aplica incluso cuando se utilizan métodos SDK para renderizar el banner, ya que el SDK no puede adjuntar automáticamente escuchas a elementos dentro de tu código personalizado.

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

Para obtener la referencia completa, consulta Código personalizado y puente JavaScript para banners. brazeBridgeProporciona una capa de comunicación entre el HTML interno de Banner y el SDK principal de Braze.

Implementaciones de interfaz de usuario personalizadas (sin interfaz gráfica)

Si estás creando una interfaz de usuario totalmente 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 muestra el banner, no tiene forma de realizar un seguimiento automático de las interacciones con tus elementos de interfaz de usuario personalizados.

Utiliza ellogClick()método en el objeto Banner.

Dimensiones y tamaños

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

• Aunque el compositor te permite realizar una vista previa de los banners 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 muestre.
• Recomendamos crear un elemento de dimensiones fijas y probar esas dimensiones en Composer.

Propiedades personalizadas

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

• Envía metadatos para tus análisis o integraciones de terceros.
• Utiliza metadatos como untimestamp o un objeto JSON para desencadear la lógica condicional.
• Controla el comportamiento de un banner basándote en metadatos incluidos comoratio o format.

Requisitos previos

Tendrás que añadir propiedades personalizadas a tu campaña de Banner. 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
});