Skip to content

Gerenciar posicionamentos de Banner

Aprenda como criar e gerenciar posicionamentos de Banner no SDK da Braze, incluindo o acesso às suas propriedades exclusivas e o registro de impressões. Para mais informações gerais, veja Sobre Banners.

Sobre solicitações de posicionamento

Quando você cria posicionamentos no seu app ou site, seu app envia uma solicitação para a Braze buscar mensagens de Banner para cada posicionamento.

  • Você pode solicitar até 10 posicionamentos por solicitação de atualização.
  • Para cada posicionamento, a Braze retorna o Banner de maior prioridade que o usuário é elegível para receber.
  • Se mais de 10 posicionamentos forem solicitados em uma atualização, apenas os primeiros 10 são retornados; os demais são descartados.

Por exemplo, um app pode solicitar três posicionamentos em uma solicitação de atualização: homepage_promo, cart_abandonment e seasonal_offer. Cada solicitação retorna o Banner mais relevante para aquele posicionamento.

Limite de taxa para solicitações de atualização

Se você estiver em versões mais antigas do SDK (antes do Swift 13.1.0, Android 38.0.0, Web 6.1.0, React Native 17.0.0 e Flutter 15.0.0), apenas uma solicitação de atualização é permitida por sessão de usuário.

Se você estiver em versões mínimas mais novas do SDK (Swift 13.1.0+, Android 38.0.0+, Web 6.1.0+, React Native 17.0.0+ e Flutter 15.0.0+), as solicitações de atualização são controladas por um algoritmo de token bucket para evitar polling excessivo:

  • Cada sessão de usuário começa com cinco tokens de atualização.
  • Os tokens são reabastecidos a uma taxa de um token a cada 180 segundos (3 minutos).

Cada chamada explícita para requestBannersRefresh consome um token. A atualização automática que ocorre no início de uma nova sessão ou quando changeUser é chamado não consome um token, pois essa atualização é uma publicação do último Banner em cache para aquele usuário. Se você tentar uma atualização quando não houver tokens disponíveis, o SDK não faz a solicitação e registra um erro até que um token seja reabastecido. Isso é importante para atualizações durante a sessão e atualizações acionadas por eventos. Para implementar atualizações dinâmicas (por exemplo, após um usuário completar uma ação na mesma página), chame o método de atualização após o evento personalizado ser registrado, mas observe a postergação necessária para a Braze ingerir e processar o evento antes que o usuário se qualifique para uma Campaign de Banner diferente.

Criar um posicionamento

Pré-requisitos

Estas são as versões mínimas do SDK necessárias para criar posicionamentos de Banner:

Etapa 1: Criar posicionamentos no Braze

Se ainda não o fez, você precisará criar posicionamentos de banner no Braze, que são usados para definir os locais em seu app ou site que podem exibir banners. Para criar um posicionamento, acesse Settings > Banners Placements ( Configurações > Posicionamentos de banners) e selecione Create Placement (Criar posicionamento).

Seção Banner Placements para criar IDs de posicionamento.

Dê um nome à sua colocação e atribua uma ID de colocação. Certifique-se de consultar outras equipes antes de atribuir uma ID, pois ela será usada durante todo o ciclo de vida do cartão e não deve ser alterada posteriormente. Para saber mais, consulte Placement IDs.

Os detalhes de posicionamento que designam um banner serão exibidos na barra lateral esquerda para campanhas de promoção de vendas na primavera.

Etapa 2: Atualize os posicionamentos no seu app

Para atualizar os posicionamentos, chame o método de atualização do seu SDK (requestBannersRefresh() na Web e Android, ou requestRefresh() no Swift).

O comportamento de atualização de Banner tem dois caminhos:

  1. Atualização explícita: Você pode chamar o método de atualização a qualquer momento durante uma sessão ativa.
  2. Atualização automática em nova sessão: Depois de fazer pelo menos uma solicitação de atualização explícita, o SDK pode solicitar novamente os IDs de posicionamento mais recentes quando uma nova sessão da Braze é iniciada (por exemplo, após changeUser() ou após um tempo limite de sessão).

O papel de subscribeToBannersUpdates() difere por plataforma:

  • iOS e Android: subscribeToBannersUpdates() (ou subscribeToUpdates() no Swift) registra um retorno de chamada de atualização. A atualização automática no início da sessão não depende da inscrição estar ativa.
  • Web: A atualização automática no início da sessão está vinculada ao registro de subscribeToBannersUpdates(). Sem uma inscrição ativa, o SDK não repete automaticamente a atualização em uma nova sessão.

Em todos os casos, você deve fazer pelo menos uma solicitação de atualização explícita por ciclo de vida do app para que o SDK saiba quais IDs de posicionamento manter atualizados. Os Banners não são buscados automaticamente na primeira inicialização sem essa chamada inicial, e os IDs de posicionamento rastreados são redefinidos após a reinicialização do app.

As atualizações automáticas no início da sessão não consomem um token de limite de frequência.

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.

Etapa 3: Ouça as atualizações

Se você estiver usando JavaScript puro com o SDK Web da Braze, use subscribeToBannersUpdates para ouvir atualizações de posicionamento e, em seguida, chame requestBannersRefresh para buscá-las.

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

Se você estiver usando React com o SDK Web da Braze, configure subscribeToBannersUpdates dentro de um hook useEffect e chame requestBannersRefresh após registrar seu ouvinte.

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
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.requestRefresh(placementIds: placementIds)

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.

Etapa 4: Inserir usando o ID do posicionamento

Crie um elemento contêiner para o Banner. Certifique-se de definir sua largura e altura.

1

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

Se você estiver usando JavaScript puro com o SDK Web da Braze, chame o método insertBanner para substituir o HTML interno do elemento contêiner.

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

Se você estiver usando React com o SDK Web da Braze, chame o método insertBanner com um ref para substituir o HTML interno do elemento contêiner.

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

Para obter o Banner no código Java, use:

1

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

Você pode criar Banners no layout das suas views Android incluindo 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" />

Se estiver usando Android Views, use 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, adicione o artefato com.braze:android-sdk-jetpack-compose ao módulo do seu app. Use a mesma versão das suas outras dependências do SDK Android da Braze. Esse módulo é separado do android-sdk-ui e inclui o composable Banner em com.braze.jetpackcompose.banners.

1
2
3
4
5
6

import com.braze.jetpackcompose.banners.Banner

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

Opcionalmente, passe heightCallback para receber a altura renderizada em dp quando o tamanho do banner mudar. Para referência, consulte a documentação KDoc do Banner.

Se você não adicionar o módulo Jetpack Compose, envolva BannerView em 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 obter o Banner em Kotlin, use:

1

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

Se você estiver usando a Nova Arquitetura do React Native, será necessário registrar BrazeBannerView como um componente Fabric no seu 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 a integração mais simples, adicione o seguinte trecho de JavaScript XML (JSX) na sua hierarquia de views, fornecendo apenas o ID do posicionamento.

1
2
3

<Braze.BrazeBannerView
  placementId='global_banner'
/>

Para obter o modelo de dados do Banner no React Native, ou para verificar a presença desse posicionamento no cache do seu usuário, use:

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 a integração mais simples, adicione o seguinte widget na sua hierarquia de views, fornecendo apenas o ID do posicionamento.

1
2
3
4

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

Você pode usar o método getBanner para verificar a presença desse posicionamento no cache do seu usuário.

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.

Etapa 5: Envie um Banner de teste (opcional)

Antes de lançar uma campanha de Banner, você pode enviar um Banner de teste para verificar sua integração. Banners de teste são armazenados em um cache separado na memória e não persistem entre reinicializações do app. Embora nenhuma configuração extra seja necessária, seu dispositivo de teste deve ser capaz de receber notificações por push em primeiro plano para que possa exibir o teste.

Registrar impressões

A Braze registra automaticamente impressões para Banners que estão visíveis quando você usa métodos do SDK para inserir um Banner—portanto, não há necessidade de rastrear impressões manualmente.

Registrar cliques

O método usado para registrar cliques em Banners depende de como seu Banner é renderizado e onde seu manipulador de cliques está localizado.

Conteúdo padrão do Banner (automático)

Se você estiver usando métodos padrão do SDK, prontos para uso, para inserir Banners, e seu Banner usar componentes padrão do editor (imagens, botões, texto), os cliques são rastreados automaticamente. O SDK anexa ouvintes de cliques a esses elementos, e nenhum código adicional é necessário.

Blocos de código personalizado

Se seu Banner usar o bloco de editor Custom Code no dashboard da Braze, você deve usar brazeBridge.logClick() para registrar cliques a partir desse HTML personalizado. Isso se aplica mesmo ao usar métodos do SDK para renderizar o Banner, porque o SDK não pode anexar ouvintes automaticamente a elementos dentro do seu código personalizado.

1
2
3

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

Para a referência completa, veja Código personalizado e ponte JavaScript para Banners. O brazeBridge fornece uma camada de comunicação entre o HTML interno do Banner e o SDK da Braze pai.

Implementações de UI personalizadas (headless)

Se você estiver construindo uma UI totalmente personalizada usando as propriedades personalizadas do Banner em vez de renderizar o HTML do Banner, você deve registrar manualmente cliques e impressões a partir do código do seu aplicativo. Como o SDK não está renderizando o Banner, ele não tem como rastrear automaticamente as interações com seus elementos de UI personalizados.

Para assinaturas de métodos e detalhes completos, consulte a documentação de referência do SDK da Braze.

Registrar impressões

Chame o método de impressão de Banner da plataforma quando sua UI personalizada considerar o Banner como “visualizado”. Construa uma lógica robusta para o que conta como uma impressão, a fim de evitar eventos duplicados — por exemplo, registre apenas quando o Banner entrar na viewport (ou equivalente), e não registre novamente quando o mesmo Banner voltar a aparecer na tela ao rolar ou quando seu componente re-renderizar sem um novo evento de visualização.

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

Referência do SDK Web

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

Referência do SDK Android

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

Referência do SDK Swift

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

Consulte o repositório do SDK React Native para as assinaturas de métodos mais recentes.

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

Referência do SDK Flutter

Registrar cliques

Chame o método de clique de Banner da plataforma quando o usuário tocar no seu Banner personalizado (ou em um botão específico). Passe o buttonId opcional quando o clique for em um botão específico, para que a análise de dados possa atribuir o clique corretamente.

1
2
3
4

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

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

Referência do SDK Web

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

Referência do SDK Android

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
}

Referência do SDK Swift

1
2

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

Consulte o repositório do SDK React Native para as assinaturas de métodos mais recentes.

1
2

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

Referência do SDK Flutter

Registrar dispensas

As dispensas de Banner removem programaticamente um Banner de um posicionamento quando um usuário o dispensa ativamente. Uma vez dispensado, o Banner é suprimido para aquele usuário. Na próxima vez que a lista de posicionamentos for atualizada, um novo banner será retornado se o usuário for elegível para um.

Pré-requisitos

Estas são as versões mínimas do SDK necessárias para registrar dispensas de Banner:

Integrações

Integrações padrão de Banner (editor de arrastar e soltar)

Se seu Banner usar o editor de arrastar e soltar e incluir um componente de botão de dispensa, nenhum código adicional é necessário. Quando um usuário clicar no botão de dispensa, a mensagem será ocultada, uma dispensa será acionada e um evento de dispensa será registrado para análise de dados.

Blocos de código personalizado

Se seu Banner usar o bloco de editor Custom Code, você pode acionar uma dispensa diretamente de dentro do HTML do Banner usando brazeBridge.closeMessage().

1
2
3

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

Dispensar um banner programaticamente

Se você estiver usando o BrazeBannerView padrão com o botão de dispensa criado no editor de arrastar e soltar, nenhum código adicional é necessário; a dispensa é tratada automaticamente.

Para integrações de UI personalizadas, você pode chamar o método de dispensa diretamente na sua instância da Braze para dispensar programaticamente um banner e registrar um evento de dispensa. O método de dispensa pode ser chamado várias vezes com segurança — o SDK ignora chamadas duplicadas para o mesmo banner.

Estas são as versões mínimas do SDK necessárias para dispensar um banner programaticamente:

Passe o objeto Banner para braze.dismissBanner(). Você pode obter o objeto Banner a partir de braze.getAllBanners() ou de um retorno de chamada de subscribeToBannersUpdates.

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

Use dismiss() no contexto do banner quando disponível. Esse método é idempotente e dispara o retorno de chamada onDismiss automaticamente. Se o contexto não estiver disponível, chame dismiss(using:) diretamente no banner. Ambos os métodos devem ser chamados a partir da thread principal.

1
2
3
4
5

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

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

Em Objective-C, esses métodos estão disponíveis como [banner.context dismiss] e [banner dismissUsing:braze].

1

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

1

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

Registrar análise de dados personalizada na dispensa do banner

Para executar lógica personalizada quando um banner é dispensado — como registrar análise de dados — use o retorno de chamada de dispensa do seu SDK. O retorno de chamada recebe um objeto de evento com o placementId, stableKey e trackingId do banner.

Use Banner.subscribeToDismissedEvent() para executar lógica personalizada quando um banner específico é dispensado. Inscreva-se no evento antes de exibir o banner.

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

Defina a propriedade opcional onDismissCallback em BannerView.

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
}

Defina a prop onDismiss em Braze.BrazeBannerView para executar lógica personalizada quando um banner é dispensado.

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

Defina o parâmetro onDismiss em BrazeBannerView para executar lógica personalizada quando um banner é dispensado.

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

Limite de armazenamento de dispensas pendentes

Os eventos de dispensa são armazenados localmente como entradas pendentes até que possam ser sincronizados com o servidor da Braze na próxima chamada de requestBannersRefresh.

Dimensões e tamanhos

Aqui está o que você precisa saber sobre dimensões e tamanhos do Banner:

  • Embora o criador permita que você visualize Banners em diferentes dimensões, essa informação não é salva ou enviada para o SDK.
  • O HTML ocupará toda a largura do contêiner em que for renderizado.
  • Recomendamos criar um elemento de dimensão fixa e testar essas dimensões no criador.

Propriedades personalizadas

Você pode usar propriedades personalizadas da sua campanha de Banner para recuperar dados chave-valor através do SDK e modificar o comportamento ou a aparência do seu app. Por exemplo, você poderia:

  • Enviar metadados para suas análises de terceiros ou integrações.
  • Usar metadados como um timestamp ou objeto JSON para acionar lógica condicional.
  • Controlar o comportamento de um banner com base em metadados incluídos como ratio ou format.

Pré-requisitos

Você precisará adicionar propriedades personalizadas à sua campanha de Banner. Além disso, estas são as versões mínimas do SDK necessárias para acessar propriedades personalizadas:

Acessar propriedades personalizadas

Para acessar as propriedades personalizadas de um banner, use um dos seguintes métodos com base no tipo da propriedade definido no dashboard. Se a chave não corresponder a uma propriedade desse tipo ou não existir, o método retorna null.

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
});
New Stuff!