Configuração inicial do SDK para a Web

Este artigo de referência aborda como instalar o SDK da Braze para Web. O SDK da Braze para Web permite que você colete análises de dados e exiba mensagens no app, push e mensagens de cartão de conteúdo para seus usuários da Internet. Consulte nossa Documentação para obter uma referência técnica completa.

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

Depois que o SDK da Braze para Web for adicionado ao seu site, inicialize a biblioteca com a chave de API e o endpoint de SDK encontrados em Configurações > App Configurações de app em seu dashboard da Braze.

Para obter uma lista completa de opções para braze.initialize(), juntamente com nossos outros métodos JavaScript, consulte nossa documentação 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();

Etapa 3: Configure as notificações por push (opcional)

Para configurar notificações por push para o SDK da Braze para Web, é necessária uma configuração adicional. Para obter um passo a passo completo, consulte Notificações por push para web.

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.

Métodos alternativos de integração

Estruturas de renderização no lado do servidor

Se você usar uma estrutura de renderização no lado do servidor, como Next.js, poderá encontrar erros, pois 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();
    });
}, []);

Suporte do 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']
},

Suporte do 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.

Carregador de módulos AMD

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

Alternativa Sem instalação de AMD

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 acima, é 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:

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.

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.

Solução de problemas da 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)"
  ]
}