Tutorial: Mostrar un banner por ID de ubicación
Sigue el código de ejemplo de este tutorial para mostrar banners utilizando su ID de ubicación. Para obtener información más general, consulta Banners.
Requisitos previos
Antes de comenzar este tutorial, comprueba que tu SDK de Braze cumple los requisitos mínimos de versión:
Mostrar banners para el SDK Web
Estamos probando este nuevo formato de tutorial. Dinos qué opinan — sus comentarios nos ayudan a mejorar las guías futuras.
1. Habilitar la depuración (opcional) {#1-enable-debugging-optional}
Para facilitar la solución de problemas durante el desarrollo, considera habilitar la depuración.
2. Suscribirse a eventos de Banner {#2-subscribe-to-banner-events}
Utiliza subscribeToBannersEvents() en el SDK Web 7.0.0 o posterior para registrar un controlador. El controlador se ejecuta cuando la caché de banners se reproduce, se recarga o se actualiza, o cuando se produce un error. Dentro del controlador, lee la ubicación desde event.cacheSnapshot.banners. subscribeToBannersUpdates() es el patrón anterior, obsoleto a partir de la versión 7.0.0. Para ver la lista completa de eventos, consulta Suscripciones a eventos.
3. Insertar el banner y gestionar los grupos de control {#3-insert-the-banner-and-handle-control-groups}
Utiliza braze.insertBanner(banner, container) para insertar un banner cuando se devuelve. Para mantener tu diseño limpio, oculta o contrae los banners que forman parte de un grupo de control (por ejemplo, cuando isControl es true).
4. Actualizar tus banners {#4-refresh-your-banners}
Después de inicializar el SDK, llama a requestBannersRefresh(["global_banner", ...]) para asegurarte de que los banners se actualizan al inicio de cada sesión.
También puedes llamar a esta función en cualquier momento para actualizar las ubicaciones de banners más adelante.
5. Añadir un contenedor para tu banner {#5-add-a-container-for-your-banner}
En tu HTML, añade un nuevo elemento <div> y asígnale un id corto relacionado con el banner, como global-banner-container. Braze utilizará este <div> para insertar tu banner en la página.
Requisitos previos
Antes de comenzar este tutorial, comprueba que tu SDK de Braze cumple los requisitos mínimos de versión:
Mostrar banners para el SDK de Android
Estamos probando este nuevo formato de tutorial. Dinos qué opinan — sus comentarios nos ayudan a mejorar las guías futuras.
1. Habilitar la depuración (opcional) {#1-enable-debugging-optional}
Para facilitar la solución de problemas durante el desarrollo, considera habilitar la depuración.
2. Suscribirse a los eventos de banner {#2-subscribe-to-banner-events}
Usa subscribeToBannersEvents() para registrar un controlador que se ejecuta cuando la caché de banners se reproduce o se actualiza. BannersCacheSnapshot.banners es un mapa de ID de ubicación a Banner.
Para ver la lista completa de eventos que puedes recibir, consulta Suscripciones a eventos.
3. Definir BannerView en tu banners.xml {#3-define-bannerview-in-your-bannersxml}
En banners.xml, declara un <com.braze.ui.banners.BannerView> con app:placementId="PLACEMENT_ID" y establece android:layout_height en 0dp. La vista permanece en el diseño sin altura hasta que el banner informa de la altura de su contenido, así la pantalla no reserva espacio vacío antes de que se cargue un banner.
Después de una actualización, el SDK actualiza un BannerView solo cuando cambia el contenido de esa ubicación. Los banners mostrados que no cambian se quedan como están.
4. Actualizar la altura del banner {#4-update-the-banner-height}
Establece heightCallback en el BannerView. La devolución de llamada recibe la altura del banner en dp. Aplica tú mismo esa altura a la vista: convierte los dp a píxeles y, a continuación, establece la altura del diseño.
El HTML del banner informa de su altura a través de una interfaz JavaScript, por lo que heightCallback puede ejecutarse fuera del hilo principal. Actualiza la vista dentro de bannerView.post para que el cambio se ejecute en el hilo principal.
Una altura de 0.0 significa que no hay contenido que mostrar. El SDK informa 0.0 cuando la ubicación no tiene banner, el banner está en un grupo de control o el banner se descartó. Aplica también 0.0, para que la vista se contraiga y permanezca en el diseño para el siguiente banner.
5. Limitar la altura del banner {#5-limit-the-banner-height}
Establece un límite para la altura que aplicas. En este ejemplo, min(heightDp, 80.0) mantiene el banner en 80 dp o menos.
6. Actualizar tus ubicaciones {#6-refresh-your-placements}
Después de inicializar el SDK de Braze, llama a requestBannersRefresh(["PLACEMENT_ID"]) para obtener el contenido de banner más reciente para esa ubicación.
Esta llamada se combina con la caché de banners existente. Solo se añaden, actualizan o eliminan los ID de ubicación que solicitas. Los banners en caché de otras ubicaciones permanecen en la caché y caducan en su fecha de caducidad original. Si el servidor no devuelve ningún banner para una ubicación solicitada, esa ubicación se elimina de la caché.
Para usar Jetpack Compose, añade el artefacto com.braze:android-sdk-jetpack-compose al módulo de tu aplicación. Usa la misma versión que tus otras dependencias del SDK de Braze para Android.
1. Habilitar la depuración (opcional)
Para facilitar la solución de problemas durante el desarrollo, considera habilitar la depuración.
2. Suscribirse a los eventos de banner
Llama a subscribeToBannersEvents y conserva el suscriptor para poder eliminarlo cuando el composable salga de la pantalla. Establece hasBannerForPlacement cuando CacheReplay, CacheLoad o DataUpdated contengan esta ubicación. En un ErrorEvent con FeatureDisabled, establece hasBannerForPlacement en false.
Los eventos de banner llegan en un hilo en segundo plano. Publica las actualizaciones de la interfaz de usuario en el hilo principal.
Para saber cuándo se activa cada evento, consulta Suscripciones a eventos.
3. Actualizar tus ubicaciones {#3-refresh-your-placements}
Después de registrar el suscriptor, llama a requestBannersRefresh(["PLACEMENT_ID"]) para obtener el contenido de banner más reciente para esa ubicación. Elimina el suscriptor con removeSingleSubscription cuando ya no lo necesites.
4. Mostrar el banner solo cuando esté en la caché {#4-only-show-the-banner-after-it-is-in-the-cache}
Muestra Banner solo cuando hasBannerForPlacement sea verdadero. La ubicación permanece fuera de tu diseño hasta que la caché contenga un banner para ella.
Importa com.braze.jetpackcompose.banners.Banner. Otras bibliotecas de Compose definen su propio composable Banner.
5. Actualizar la altura del banner {#5-update-the-banner-height}
Pasa heightCallback a Banner. La devolución de llamada recibe la altura del banner en dp. Guárdala en contentHeight y aplícala con Modifier.height. Banner deja el dimensionamiento en manos de tu diseño.
heightCallback puede ejecutarse fuera del hilo principal. Publica la actualización de estado en el hilo principal antes de cambiar contentHeight.
Una altura de 0.0 significa que no hay contenido que mostrar y evita espacios vacíos en tu interfaz de usuario. El SDK informa 0.0 cuando la ubicación no tiene banner, el banner está en un grupo de control o el banner se descartó.
6. Limitar la altura del banner {#6-limit-the-banner-height}
Establece un límite para la altura que aplicas. En este ejemplo, min(contentHeight, 80.0) mantiene el banner en 80 dp o menos.
Requisitos previos
Antes de comenzar este tutorial, comprueba que tu SDK de Braze cumple los requisitos mínimos de versión:
Mostrar banners para el SDK de Swift
Estamos probando este nuevo formato de tutorial. Dinos qué opinan — sus comentarios nos ayudan a mejorar las guías futuras.
1. Habilitar depuración (opcional) {#1-enable-debugging-optional} {#1-enable-debugging-optional}
Para facilitar la solución de problemas durante el desarrollo, considera habilitar la depuración.
2. Suscribirse a eventos de banner {#2-subscribe-to-banner-events} {#2-subscribe-to-banner-events}
Usa subscribeToEvents para registrar un controlador que se ejecute cuando la caché de banner se reproduzca, se recargue o se actualice, o cuando se produzca un error. cacheSnapshot.banners es un diccionario de ID de ubicación a Banner. Mantén una referencia fuerte al Braze.Cancellable devuelto, porque el SDK cancela la suscripción cuando se desasigna.
Para saber cuándo se activa cada evento, consulta Suscripciones a eventos.
3. Actualizar tus ubicaciones {#3-refresh-your-placements} {#3-refresh-your-placements}
Después de registrar tu suscripción, llama a requestBannersRefresh(placementIds: ["PLACEMENT_ID"]) para actualizar el contenido del banner al inicio de cada sesión.
4. Inicializar el banner y proporcionar una devolución de llamada {#4-initialize-the-banner-and-provide-a-callback} {#4-initialize-the-banner-and-provide-a-callback}
Crea una instancia de BrazeBannerUI.BannerUIView con tu objeto Braze y el ID de ubicación, y proporciona una devolución de llamada processContentUpdates para mostrar el banner y actualizar su restricción de altura en función de la altura del contenido proporcionada.
5. Habilitar restricciones de Auto Layout {#5-enable-auto-layout-constraints} {#5-enable-auto-layout-constraints}
Oculta la vista de banner de forma predeterminada y luego deshabilita la traducción de máscara de redimensionamiento automático para habilitar las restricciones de Auto Layout.
6. Anclar contenido y establecer restricciones de altura {#6-anchor-content-and-set-height-constraints} {#6-anchor-content-and-set-height-constraints}
Ancla tu contenido principal a la parte superior usando Auto Layout y coloca la vista de banner después de él. Fija los bordes izquierdo, derecho e inferior del banner al área segura, y establece una restricción de altura inicial de 0 que se actualizará cuando se cargue el contenido.
1. Habilitar depuración (opcional) {#1-enable-debugging-optional}
Para facilitar la solución de problemas durante el desarrollo, considera habilitar la depuración.
2. Actualizar tus ubicaciones {#2-refresh-your-placements} {#2-refresh-your-placements}
Después de inicializar el SDK de Braze, llama a requestBannersRefresh(placementIds: ["PLACEMENT_ID"]) para actualizar el contenido del banner al inicio de cada sesión.
3. Crear un componente de vista {#3-create-a-view-component} {#3-create-a-view-component}
Crea un componente de vista SwiftUI reutilizable que muestre los banners disponibles y contenga el contenido principal de tu aplicación si es necesario.
4. Suscribirse a eventos de banner {#4-subscribe-to-banner-events} {#4-subscribe-to-banner-events}
En .onAppear, usa subscribeToEvents para registrar un controlador que establezca hasBannerForPlacement cada vez que la caché de banner se reproduzca, se recargue o se actualice. Mantén una referencia fuerte al Braze.Cancellable devuelto en tu estado, porque el SDK cancela la suscripción cuando se desasigna.
Para saber cuándo se activa cada evento, consulta Suscripciones a eventos.
5. Mostrar BannerView solo después de que se cargue {#5-only-show-bannerview-after-it-loads} {#5-only-show-bannerview-after-it-loads}
Para evitar espacios en blanco en tu interfaz de usuario, muestra BrazeBannerUI.BannerView solo si hay un banner presente y el SDK está inicializado.
6. Actualizar dinámicamente la altura del banner {#6-dynamically-update-banner-height} {#6-dynamically-update-banner-height}
Usa la devolución de llamada processContentUpdates para obtener la altura del contenido del banner en cuanto se cargue. Actualiza el estado de tu SwiftUI (contentHeight) y aplica una restricción .frame(height:) con la altura proporcionada.
7. Limitar la altura del banner {#7-limit-the-banner-height} {#7-limit-the-banner-height}
Para asegurarte de que tu banner nunca exceda la altura máxima, aplica un modificador .frame(height: min(contentHeight, 80)). Esto mantendrá tu interfaz de usuario visualmente equilibrada independientemente del contenido del banner.