Sobre o Web Braze SDK

O Web Braze SDK permite coletar dados de análise e exibir mensagens no app avançadas, mensagens de push e Content Cards para os seus usuários web. Para saber mais, consulte a documentação de referência do JavaScript da Braze.

Nota

Este guia usa exemplos de código do SDK da Braze para Web 4.0.0+. Para fazer upgrade para a versão mais recente do SDK para Web, consulte o Guia de atualização do SDK.

Integre o Web SDK

Você pode integrar o Web Braze SDK usando os seguintes métodos. Para opções adicionais, veja outros métodos de integração.

• Integração baseada em código: Integre o Web Braze SDK diretamente no seu código usando seu gerenciador de pacotes preferido ou o CDN da Braze. Isso dá a você controle total sobre como o SDK é carregado e configurado.
• Google Tag Manager: Uma solução sem código que permite integrar o Web Braze SDK sem modificar o código do seu site. Para saber mais, veja Google Tag Manager com o SDK da Braze.

Importante

Recomendamos usar o método de integração NPM. Os benefícios incluem armazenar as bibliotecas do SDK localmente no seu website, oferecer imunidade contra extensões de bloqueio de anúncios e contribuir para tempos de carregamento mais rápidos como parte do suporte a bundlers.

• integração baseada em código
• google tag manager

Etapa 1: Instale a biblioteca da Braze

Você pode instalar a biblioteca da Braze usando um dos seguintes métodos. No entanto, se o seu site usa uma Content-Security-Policy, revise a Content Security Policy antes de continuar.

Importante

Embora a maioria dos bloqueadores de anúncios não bloqueie o Web Braze SDK, alguns bloqueadores mais restritivos podem causar problemas.

• package manager
• braze cdn

Se o seu site usa gerenciadores de pacotes NPM ou Yarn, você pode adicionar o pacote NPM da Braze como dependência.

As definições de Typescript estão incluídas a partir da v3.0.0. Para notas sobre a atualização de 2.x para 3.x, veja nosso changelog.

1
2
3

npm install --save @braze/web-sdk
# or, using yarn:
# yarn add @braze/web-sdk

Uma vez instalada, você pode importar (import) ou requerer (require) a biblioteca da maneira habitual:

1
2
3

import * as braze from "@braze/web-sdk";
// or, using `require`
const braze = require("@braze/web-sdk");

Adicione o Web Braze SDK diretamente ao seu HTML referenciando nosso script hospedado no CDN, que carrega a biblioteca de forma assíncrona.

Importante

A configuração padrão de Impedir rastreamento entre sites no Safari pode impedir que tipos de mensagens no app, como Banners e Content Cards, sejam exibidos ao usar o método de integração por CDN. Para evitar esse problema, use o método de integração NPM para que o Safari não classifique essas mensagens como tráfego entre sites e seus usuários web possam vê-las em todos os navegadores compatíveis.

Etapa 2: Inicialize o SDK

Após adicionar o Web Braze SDK ao seu website, inicialize a biblioteca com a chave de API e a URL do endpoint do SDK encontrados em Configurações > Configurações do app no dashboard da Braze. Para uma lista completa de opções para braze.initialize(), junto com nossos outros métodos JavaScript, veja a documentação JavaScript da Braze.

Nota

Domínios personalizados para solicitações do Web SDK não são suportados: o baseUrl do Web SDK deve ser um endpoint de SDK da Braze (por exemplo, sdk.iad-05.braze.com). A Braze não suporta o roteamento de tráfego do Web SDK por meio de um domínio de propriedade do cliente via registros CNAME. Se você precisa que as solicitações do Web SDK se originem do seu próprio domínio, entre em contato com o suporte da 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

// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE",
    enableLogging: false, // set to `true` for debugging
    allowUserSuppliedJavascript: false, // set to `true` to support custom HTML messages
});

// Enable automatic display of in-app messages
// Required if you want in-app messages to display automatically when triggered
braze.automaticallyShowInAppMessages();

// if you use Content Cards
braze.subscribeToContentCardsUpdates(function(cards){
    // cards have been updated
});

// optionally set the current user's external ID before starting a new session
// you can also call `changeUser` later in the session after the user logs in
if (isLoggedIn){
    braze.changeUser(userIdentifier);
}

// `openSession` should be called last - after `changeUser` and `automaticallyShowInAppMessages`
braze.openSession();

Importante

Exibição de In-App Messages: Para exibir In-App Messages automaticamente quando são disparadas, você deve chamar braze.automaticallyShowInAppMessages(). Sem essa chamada, as In-App Messages não são exibidas automaticamente. Se você deseja gerenciar a exibição de mensagens manualmente, remova essa chamada e use braze.subscribeToInAppMessage() em vez disso. Para saber mais, veja Desativando disparos automáticos.

Solução de problemas com sessões ausentes para usuários anônimos

Se você está enfrentando comportamento de “sessão ausente”, ou se não consegue rastrear a sessão de usuários que permanecem anônimos na web, verifique se sua integração chama braze.openSession() durante a inicialização.

• Cenário: Usuários anônimos podem retornar um ID da Braze, mas os dados da sessão estão em branco ou ausentes.
• Causa: A implementação não chama braze.openSession().
• Resolução: Sempre chame braze.openSession() após a inicialização (e após braze.changeUser() se você definir um ID externo).

Para saber mais, veja Etapa 2: Inicialize o SDK.

Importante

Usuários anônimos em dispositivos móveis ou web podem ser contabilizados no seu MAU. Como resultado, você pode querer carregar ou inicializar o SDK condicionalmente para excluir esses usuários da sua contagem de MAU.

Pré-requisitos

Antes de usar este método de integração, você precisará criar uma conta e um contêiner para o Google Tag Manager.

Etapa 1: Abra a galeria de modelos de tag

No Google Tag Manager, escolha seu espaço de trabalho e selecione Templates. No painel Tag Template, selecione Search Gallery.

Etapa 2: Adicione o modelo de tag de inicialização

Na galeria de modelos, procure por braze-inc e selecione Braze Initialization Tag.

Selecione Add to workspace > Add.

Etapa 3: Configure a tag

Na seção Templates, selecione o modelo recém-adicionado.

Selecione o ícone de lápis para abrir o menu suspenso Tag Configuration.

Insira as informações mínimas necessárias:

Campo	Descrição
API Key	Sua chave de API da Braze, encontrada no dashboard da Braze em Settings > App Settings.
API Endpoint	A URL do seu endpoint REST. Seu endpoint dependerá da URL da Braze para sua instância.
SDK Version	A versão MAJOR.MINOR mais recente do SDK Web da Braze listada no changelog. Por exemplo, se a versão mais recente for 4.1.2, digite 4.1. Para saber mais, consulte Sobre o gerenciamento de versões do SDK.

Para configurações adicionais de inicialização, selecione Braze Initialization Options e escolha as opções que você precisar.

Etapa 4: Escolha as opções de inicialização

A Braze Initialization Tag expõe as seguintes opções. A maioria delas mapeia diretamente para as InitializationOptions do SDK Web, e algumas correspondem a métodos do SDK Web que a tag chamará durante a inicialização. Selecione as opções que correspondem às suas necessidades de integração:

Opção GTM	Configuração ou método do SDK Web	Descrição
Allow HTML In-App Messages	allowUserSuppliedJavascript	Ativa mensagens no app em HTML, Banners e ações de clique em JavaScript fornecidas pelo usuário. Necessário para mensagens no app em HTML e Banners que usam HTML personalizado. Ative isso apenas quando confiar no conteúdo HTML e JavaScript, pois permite a execução de JavaScript fornecido pelo usuário.
App Version Number	appVersion, appVersionNumber	Versão do app para segmentação (por exemplo, 1.2.3.4).
Automatically Open New Session	braze.openSession()	Abre uma nova sessão após o SDK ser inicializado, chamando este método automaticamente.
Automatically show new in app messages	braze.automaticallyShowInAppMessages()	Exibe automaticamente novas mensagens no app quando elas chegam do servidor, chamando este método após a inicialização.
Disable Automatic Push Token Maintenance	disablePushTokenMaintenance	Impede que o SDK sincronize tokens por push com o backend da Braze em novas sessões.
Disable Automatic Service Worker Registration	manageServiceWorkerExternally	Use se você registrar e controlar o service worker por conta própria.
Disable Cookies	noCookies	Usa localStorage em vez de cookies para dados de usuário/sessão. Impede o reconhecimento entre subdomínios.
Disable Font Awesome	doNotLoadFontAwesome	Impede que o SDK carregue o Font Awesome da rede de distribuição de conteúdo (CDN). Use se seu site já tiver o Font Awesome.
Enable SDK Authentication	enableSdkAuthentication	Ativa a autenticação do SDK.
Enable Web SDK Logging	enableLogging	Ativa o registro no console para depuração. Remova antes de ir para produção.
Minimum Interval Between Triggered Messages	minimumIntervalBetweenTriggerActionsInSeconds	Segundos mínimos entre ações-gatilho (padrão: 30).
Open Cards in New Tab	openCardsInNewTab	Abre links de cartões de conteúdo em uma nova guia ao usar a interface padrão do feed.
Service Worker Location	serviceWorkerLocation	Caminho personalizado para o arquivo do service worker (padrão: /service-worker.js).
Session Timeout (seconds)	sessionTimeoutInSeconds	Tempo limite da sessão em segundos (padrão: 1800).

Nota

Para ativar mensagens no app em HTML personalizado ao usar a Braze Initialization Tag no Google Tag Manager, selecione Allow HTML In-App Messages em Braze Initialization Options. Essa caixa de seleção mapeia para a opção de inicialização allowUserSuppliedJavascript em braze.initialize() e a define como true. A Braze Initialization Tag do Google Tag Manager usa esse rótulo em vez do nome da opção.

Para opções não expostas no modelo GTM (como contentSecurityNonce, localization ou devicePropertyAllowlist), use a inicialização em tempo de execução.

Etapa 5: Defina para disparar em todas as páginas

A tag de inicialização deve ser executada em todas as páginas do seu site. Isso permite que você use métodos do SDK da Braze e registre análise de dados de web push.

Importante

Sequenciamento de tags: A Braze Initialization Tag deve ser disparada antes de qualquer outra tag que chame métodos do SDK da Braze (como braze.getUser() ou braze.logCustomEvent()). Se eventos personalizados, atributos de usuário ou outras chamadas de métodos da Braze forem disparados antes de o SDK ser inicializado, você poderá encontrar erros como Uncaught TypeError: Cannot read properties of undefined (reading 'getUser'). Para garantir o sequenciamento correto, configure sua Braze Initialization Tag como uma tag de configuração ou use o recurso de sequenciamento de tags do GTM para garantir que ela seja disparada primeiro. Para saber mais, consulte Sequenciamento de tags para tags de ação da Braze.

Etapa 6: Verifique sua integração

Você pode verificar sua integração usando qualquer uma das seguintes opções:

• Opção 1: Usando a ferramenta de depuração do Google Tag Manager, você pode verificar se a Braze Initialization Tag está disparando corretamente nas suas páginas ou eventos configurados.
• Opção 2: Verifique se há solicitações de rede feitas para a Braze a partir da sua página web. Além disso, a biblioteca global window.braze deve agora estar definida.

Filtrando tráfego de bots

O MAU pode incluir uma porcentagem de usuários bots, o que inflaciona sua contagem de usuários ativos mensais. Embora o SDK Braze para Web inclua detecção integrada para alguns crawlers web comuns (como bots de motores de busca e bots de pré-visualização de redes sociais), é especialmente importante permanecer proativo com soluções robustas para detectar bots, já que atualizações do SDK sozinhas não podem detectar consistentemente todos os novos bots.

Limitações da detecção de bots do lado do SDK

O Web SDK inclui detecção básica de bots baseada em user-agent que filtra crawlers conhecidos. No entanto, essa abordagem tem limitações:

• Novos bots surgem constantemente: Empresas de IA e outros atores criam regularmente novos bots que podem se disfarçar para evitar a detecção.
• Falsificação de user-agent: Bots sofisticados podem imitar user-agents de navegadores legítimos.
• Bots personalizados: Usuários não técnicos agora podem criar facilmente bots usando grandes modelos de linguagem (LLMs), tornando o comportamento dos bots imprevisível.

Implementando filtragem de bots

Importante

As soluções descritas abaixo são sugestões gerais. Adapte a lógica de filtragem de bots ao seu ambiente e padrões de tráfego únicos.

A solução mais robusta é implementar sua própria lógica de filtragem de bots antes de inicializar o SDK da Braze. As abordagens comuns incluem:

Exigir interação do usuário

Considere atrasar a inicialização do SDK até que um usuário realize uma interação significativa, como aceitar um banner de consentimento de cookies, rolar ou clicar. Essa abordagem é frequentemente mais fácil de implementar e pode ser altamente eficaz na filtragem de tráfego de bots.

Importante

Atrasar a inicialização do SDK até a interação do usuário pode fazer com que Banners e Content Cards também não sejam exibidos até que essa interação ocorra.

Detecção personalizada de bots

Implemente detecção personalizada com base em seus padrões específicos de tráfego de bots, como:

• Analisando strings de user-agent em busca de padrões que você identificou no seu tráfego
• Verificando indicadores de navegador headless
• Usando serviços de detecção de bots de terceiros
• Monitorando sinais comportamentais específicos do seu site

Exemplo de inicialização condicional:

1
2
3
4
5
6
7
8

// Only initialize Braze if your custom bot detection determines this is not a bot
if (!isLikelyBot()) {
  braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
  });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
}

Melhores práticas

• Analise regularmente seus dados de MAU e padrões de tráfego da web para identificar novos comportamentos de bots.
• Teste minuciosamente para garantir que seu filtro de bots não impeça que usuários legítimos sejam rastreados.
• Atualize sua lógica de filtragem com base nos padrões de tráfego de bots que você observa em seu ambiente.

Configurações opcionais

Registro de logs

Para ativar rapidamente o registro de logs, você pode adicionar ?brazeLogging=true como um parâmetro na URL do seu website. Alternativamente, você pode ativar o registro básico ou personalizado. Para uma visão geral centralizada em todas as plataformas, consulte Registro detalhado.

Registro básico

• antes da inicialização
• após a inicialização

1

enableLogging: true

1
2
3
4
5

braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
    enableLogging: true
});
braze.openSession();

1
2
3
4
5
6

braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
});
braze.openSession();
...
braze.toggleLogging();

Importante

Os logs básicos são visíveis para todos os usuários, então considere desativá-los ou mudar para setLogger antes de liberar seu código para produção.

Registro personalizado

Use setLogger para registrar mensagens de depuração personalizadas no console JavaScript. Diferentemente dos logs básicos, esses logs não são visíveis para os usuários.

1

setLogger(loggerFunction: (message: STRING) => void): void

Substitua STRING pela sua mensagem como um único parâmetro de string. Seu método deve ser semelhante ao seguinte:

1
2
3
4
5

braze.initialize('API-KEY');
braze.setLogger(function(message) {
    console.log("Braze Custom Logger: " + message);
});
braze.openSession();

Fazendo upgrade do SDK

Nota

Este guia usa exemplos de código do SDK da Braze para Web 4.0.0+. Para fazer upgrade para a versão mais recente do SDK para Web, consulte o Guia de atualização do SDK.

Quando você referencia o SDK da Braze para Web a partir de nossa rede de distribuição de conteúdo (CDN), por exemplo, https://js.appboycdn.com/web-sdk/a.a/braze.min.js (conforme recomendado por nossas instruções padrão de integração), seus usuários recebem automaticamente atualizações menores (correções de bugs e recursos compatíveis com versões anteriores, versões a.a.a até a.a.z neste exemplo) quando atualizam seu site.

No entanto, quando lançamos alterações importantes, exigimos que você faça o upgrade do SDK da Braze para Web manualmente, para garantir que mudanças que possam causar incompatibilidades não afetem sua integração. Além disso, se você baixar nosso SDK e hospedá-lo por conta própria, não receberá nenhuma atualização de versão automaticamente e deverá fazer o upgrade manualmente para receber os recursos e correções de bugs mais recentes.

Você pode se manter atualizado com nossos lançamentos mais recentes acompanhando nosso feed de lançamentos com o leitor de RSS ou serviço de sua preferência, e consultar nosso changelog para um registro completo do histórico de lançamentos do SDK para Web. Para fazer upgrade do SDK da Braze para Web:

• Atualize a versão da biblioteca da Braze alterando o número da versão em https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js, ou nas dependências do seu gerenciador de pacotes.
• Se você tem web push integrado, atualize o arquivo do service worker em seu site. Por padrão, ele está localizado em /service-worker.js no diretório raiz do seu site, mas o local pode ser personalizado em algumas integrações. Você precisa ter acesso ao diretório raiz para hospedar um arquivo de service worker.

Você precisa atualizar esses dois arquivos de forma coordenada para garantir o funcionamento correto.

Outros métodos de integração

Accelerated Mobile Pages (AMP)

1

<script async custom-element="amp-web-push" src="https://cdn.ampproject.org/v0/amp-web-push-0.1.js"></script>

1
2
3
4
5
6
7
8
9

<!-- A subscription widget -->
<amp-web-push-widget visibility="unsubscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.subscribe">Subscribe to Notifications</button>
</amp-web-push-widget>

<!-- An unsubscription widget -->
<amp-web-push-widget visibility="subscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.unsubscribe">Unsubscribe from Notifications</button>
</amp-web-push-widget>

1
2
3
4
5
6
7

<amp-web-push
layout="nodisplay"
id="amp-web-push"
helper-iframe-url="FILE_PATH_TO_YOUR_HELPER_IFRAME"
permission-dialog-url="FILE_PATH_TO_YOUR_PERMISSION_DIALOG"
service-worker-url="FILE_PATH_TO_YOUR_SERVICE_WORKER?apiKey={YOUR_API_KEY}&baseUrl={YOUR_BASE_URL}"
>

Asynchronous Module Definition (AMD)

Desativar suporte

Se o seu site usa RequireJS ou outro carregador de módulos AMD, mas você prefere carregar o SDK Web da Braze por meio de uma das outras opções desta lista, é possível carregar uma versão da biblioteca que não inclui suporte a AMD. Essa versão da biblioteca pode ser carregada a partir do seguinte local de CDN:

Carregador de módulos

Se você usa RequireJS ou outros carregadores de módulos AMD, recomendamos hospedar localmente uma cópia da nossa biblioteca e referenciá-la como você faria com outros recursos:

1
2
3
4
5
6

require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  // Required if you want in-app messages to display automatically
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

Electron

O Electron não oferece suporte oficial a notificações web push (consulte esta issue no GitHub). Existem outras soluções alternativas de código aberto que você pode experimentar, mas que não foram testadas pela Braze.

Framework Jest

Ao usar o Jest, você pode ver um erro semelhante a SyntaxError: Unexpected token 'export'. Para corrigir isso, ajuste a configuração no package.json para ignorar o SDK da Braze:

1
2
3
4
5

"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}

Frameworks SSR

O Web SDK é executado em um ambiente de navegador. Em frameworks SSR, inicialize a Braze em um componente exclusivamente do lado do cliente para que seu servidor nunca execute o código do SDK.

Importação dinâmica agnóstica de framework

Se o seu framework não está listado nesta seção, você pode importar a Braze dinamicamente a partir de um hook de ciclo de vida exclusivo do cliente.

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

// MyComponent/braze-exports.js
// Export the parts of the SDK that you need.
export { initialize, openSession } from "@braze/web-sdk";

// MyComponent/MyComponent.js
useEffect(() => {
    import("./braze-exports.js").then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Se você está usando webpack, é possível importar dinamicamente apenas exportações específicas do SDK.

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

// MyComponent.js
useEffect(() => {
    import(
        /* webpackExports: ["initialize", "openSession"] */
        "@braze/web-sdk"
    ).then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Hook compartilhado para Next.js e Remix

Crie um hook reutilizável useBraze e chame-o próximo à raiz do seu app.

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

// hooks/useBraze.ts
import { useEffect, useRef } from "react";

export function useBraze() {
  const didInit = useRef(false);

  useEffect(() => {
    if (didInit.current) {
      return;
    }
    didInit.current = true;

    import("@braze/web-sdk")
      .then((braze) => {
        const initialized = braze.initialize("YOUR-API-KEY-HERE", {
          // Use your Braze Web SDK endpoint, such as sdk.iad-01.braze.com.
          baseUrl: "YOUR-SDK-ENDPOINT",
          enableLogging: false,
        });
        if (!initialized) {
          return;
        }

        // Optional: Identify signed-in users before opening a session.
        // braze.changeUser("external-id");

        // Optional: Automatically display in-app messages.
        // braze.automaticallyShowInAppMessages();
        braze.openSession();
      })
      .catch((error) => {
        console.error("Unable to load Braze SDK:", error);
      });
  }, []);
}

Next.js (App Router)

Chame useBraze em um componente de cliente que envolve seu app.

1
2
3
4
5
6
7
8
9
10

// app/components/AppRoot.tsx
"use client";

import type { ReactNode } from "react";
import { useBraze } from "../hooks/useBraze";

export function AppRoot({ children }: { children: ReactNode }) {
  useBraze();
  return <>{children}</>;
}

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

// app/layout.tsx
import type { ReactNode } from "react";
import { AppRoot } from "./components/AppRoot";

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AppRoot>{children}</AppRoot>
      </body>
    </html>
  );
}

Next.js (Pages Router)

Chame useBraze no topo do seu componente de app personalizado.

1
2
3
4
5
6
7
8
9
10
11

// pages/_app.tsx
import type { AppProps } from "next/app";
import { useBraze } from "../hooks/useBraze";

export default function App({ Component, pageProps }: AppProps) {
  useBraze();

  return (
    <Component {...pageProps} />
  );
}

Remix

Chame useBraze no topo do componente da rota raiz.

Para exemplos de validação local do Remix, execute PORT=4013 npm run dev.

1
2
3
4
5
6
7
8
9

// app/root.tsx
import { Outlet } from "@remix-run/react";
import { useBraze } from "./hooks/useBraze";

export default function App() {
  useBraze();

  return <Outlet />;
}

Registrando eventos e atualizando usuários

Depois que useBraze inicializa o SDK na raiz do seu app, outros componentes do lado do cliente podem chamar métodos da Braze. Um padrão comum é chamá-los dentro de ações do usuário, como onClick ou onSubmit. No exemplo, os métodos do SDK são carregados dentro do manipulador de clique em vez de no topo do arquivo. Isso mantém o Web SDK fora do código do servidor e carrega apenas o necessário para aquela ação. O comentário webpackExports informa ao webpack quais métodos incluir, mantendo seu bundle menor.

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

// app/components/BuyButton.tsx
"use client";

export function BuyButton() {
  const handleClick = async () => {
    const { logCustomEvent, logPurchase, getUser } = await import(
      /* webpackExports: ["logCustomEvent", "logPurchase", "getUser"] */
      "@braze/web-sdk"
    );

    getUser()?.setCustomUserAttribute("last_purchase_date", "2026-05-04");
    logCustomEvent("clicked_buy", { source: "product_page" });
    logPurchase("sku_123", 19.99, "USD");
  };

  return <button onClick={handleClick}>Buy</button>;
}

Este exemplo mostra um componente BuyButton que registra atividade quando alguém clica em Buy. Primeiro, ele importa apenas logCustomEvent, logPurchase e getUser no momento do clique. Em seguida, atualiza um atributo do usuário, registra um evento personalizado e registra uma compra. Esse padrão ajuda a manter a inicialização centralizada em useBraze, enquanto ainda rastreia ações significativas de qualquer componente do lado do cliente.

Se você está usando Remix com Vite e as importações pela raiz do pacote falham em tempo de execução, use a solução alternativa existente do Vite. Para saber mais, consulte Vite.

Para uma lista completa dos métodos disponíveis, consulte a documentação de referência JavaScript da Braze.

Tealium iQ

O Tealium iQ oferece uma integração básica e pronta para uso com a Braze. Para configurar a integração, procure Braze na interface do Tealium Tag Management e forneça a chave de API do Web SDK a partir do seu dashboard.

Para mais detalhes ou suporte aprofundado de configuração do Tealium, confira nossa documentação de integração ou entre em contato com o seu gerente de conta do Tealium.

Vite

Se você usa Vite e vê um aviso sobre dependências circulares ou Uncaught TypeError: Class extends value undefined is not a constructor or null, pode ser necessário excluir o SDK da Braze da descoberta de dependências:

1
2
3

optimizeDeps: {
    exclude: ['@braze/web-sdk']
},

Outros gerenciadores de tags

A Braze também pode ser compatível com outras soluções de gerenciamento de tags seguindo nossas instruções de integração em uma tag HTML personalizada. Entre em contato com um representante da Braze se precisar de ajuda para avaliar essas soluções.