Integração do SDK do Braze

Sobre o SDK do Braze Web

O SDK do Web Braze permite coletar análises de dados e exibir mensagens no app, mensagens push e de cartão de conteúdo para seus usuários da Internet. Para saber mais, consulte a documentação de referência do Braze .

Integração do SDK da Web

Etapa 1: Instalar a biblioteca do Braze

Você pode instalar a biblioteca Braze usando um dos seguintes métodos. Se o seu site usa um Content-Security-Policy, consulte nosso guia de cabeçalhos de política de segurança de conteúdo antes de instalar a biblioteca.

• gerenciador de pacotes
• google tag manager
• braze cdn

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

Etapa 2: Inicializar o SDK (opcional)

Se tiver configurado suas opções de inicialização da Braze em um Tag Manager, você poderá pular esta etapa.

Caso contrário, depois que o Braze Web SDK for adicionado ao seu site, inicialize a biblioteca com a chave de API e o URL do endpoint de SDK encontrados em Configurações > Configurações do aplicativo em seu dashboard do Braze. Para obter uma lista completa de opções para braze.initialize(), juntamente com nossos outros métodos JavaScript, consulte a documentação do Braze JavaScript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
});

// optionally show all in-app messages without custom handling
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();

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.

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

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

Ao fazer referência ao Braze Web SDK a partir de nossa rede de fornecimento de conteúdo, por exemplo, https://js.appboycdn.com/web-sdk/a.a/braze.min.js (conforme recomendado por nossas instruções de integração padrão), seus usuários receberão pequenas atualizações (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 atualizarem seu site.

No entanto, quando lançamos alterações importantes, solicitamos que você faça upgrade do SDK da Braze para Web manualmente para garantir que nada em sua integração seja afetado por quaisquer alterações significativas. Além disso, se você baixar nosso SDK e hospedá-lo você mesmo, não receberá nenhuma atualização de versão automaticamente e deverá fazer upgrade manualmente para receber os recursos e as 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.

Esses dois arquivos devem ser atualizados em coordenação um com o outro para a funcionalidade adequada.

Google Tag Manager

O Google Tag Manager (GTM) permite adicionar, remover e editar remotamente tags em seu site sem precisar de uma versão de código de produção ou de recursos de engenharia. O Braze oferece os seguintes modelos de GTM:

Ambas as tags podem ser adicionadas ao seu espaço de trabalho a partir da galeria da comunidade do Google ou pesquisando por Braze ao adicionar uma nova tag a partir dos modelos da comunidade.

Política de consentimento do usuário da UE atualizada do Google

Como parte da Política de consentimento do usuário da UE do Google, os seguintes atributos booleanos personalizados precisam ser registrados nos perfis de usuário:

• $google_ad_user_data
• $google_ad_personalization

Se estiver configurando-os por meio da integração com o GTM, os atributos personalizados exigirão a criação de uma tag HTML personalizada. A seguir, um exemplo de como registrar esses valores como tipos de dados booleanos (não como strings):

1
2
3
<script>
window.braze.getUser().setCustomUserAttribute("$google_ad_personalization", true);
</script>

Para saber mais, consulte Sincronização do público do Google.

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

AMD: Desativar o suporte

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

AMD: Carregador de módulos

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
require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

Elétrons

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.

Estrutura 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)"
  ]
}

Estruturas de SSR

Se você usar uma estrutura de renderização do lado do servidor (SSR), como Next.js, poderá encontrar erros porque o SDK foi criado 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 obter mais detalhes ou suporte aprofundado à configuração do Tealium, consulte nossa documentação de integração ou entre em contato com seu gerente de conta do 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.