Sobre o SDK Braze para Web

O SDK Braze para Web permite coletar análises e exibir mensagens ricas no app, push e mensagens de cartão de conteúdo para seus usuários da web. Para mais informações, veja Braze JavaScript referência de documentação.

Integrar o Web SDK

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

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

• code-based integration
• google tag manager

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

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

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

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 da Braze para Web inclua detecção embutida 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 SDK da Web 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

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.

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

Para ativar rapidamente o registro, adicione ?brazeLogging=true como um parâmetro ao URL do seu site. Como alternativa, é possível ativar o registro básico ou personalizado. Para uma visão centralizada em todas as plataformas, veja Registro detalhado.

Registro básico

• before initialization
• after initialization

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

Registro personalizado

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

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

Substitua STRING por sua mensagem como um único parâmetro 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

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

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

Mantenha-se atualizado com a versão mais recente seguindo nosso feed de versões com o leitor de RSS ou serviço de sua preferência e consulte nosso changelog para obter uma contabilidade completa do histórico de versões do Web SDK. Para fazer upgrade do SDK da Braze para Web:

• Atualize a versão da biblioteca do 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 gerenciador de pacotes.
• Se você tiver o 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 site, mas o local pode ser personalizado em algumas integrações. Você deve acessar o diretório raiz para hospedar um arquivo de service worker.

Você deve atualizar esses dois arquivos em coordenação um com o outro para um funcionamento adequado.

Outros métodos de integração

Páginas Móveis Aceleradas (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}"
>

Definição de Módulo Assíncrono (AMD)

Desativar suporte

Se o seu site usa RequireJS ou outro carregador de módulo AMD, mas você prefere carregar o Braze Web SDK através de uma das outras opções nesta lista, você pode carregar uma versão da biblioteca que não inclui suporte a AMD. Essa versão da biblioteca pode ser carregada no seguinte local da CDN:

Carregador de módulo

Se você usa o RequireJS ou outros carregadores de módulos da AMD, recomendamos que hospede uma cópia da nossa biblioteca e faça referência a ela como 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 por push na Web (consulte: este problema no GitHub). Há outras soluções alternativas de código aberto que você pode tentar e que não foram testadas pelo Braze.

Framework Jest

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

1
2
3
4
5
"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}

Frameworks SSR

Se você usar um framework de Renderização do Lado do Servidor (SSR) como Next.js, pode encontrar erros porque o SDK foi projetado para ser executado em um ambiente de navegador. Você pode resolver esses problemas importando dinamicamente o SDK.

Você pode manter os benefícios do tree-shaking ao fazer isso exportando as partes do SDK de que precisa em um arquivo separado e, em seguida, importando dinamicamente esse arquivo para o seu componente.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// MyComponent/braze-exports.js
// export the parts of the SDK you need here
export { initialize, openSession } from "@braze/web-sdk";

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

Como alternativa, se estiver usando o Webpack para empacotar seu app, poderá aproveitar os comentários mágicos para importar dinamicamente apenas as partes do SDK de que precisa.

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

Tealium iQ

O Tealium iQ oferece uma integração básica do Braze pronta para uso. Para configurar a integração, procure o Braze na interface do Tealium Tag Management e forneça a chave de API do Web SDK em 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 seu gerente de conta Tealium.

Vite

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

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

Outros gerenciadores de tags

O 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.