Skip to content

Mensagens no app com HTML personalizado

Embora nossas mensagens no app padrão possam ser personalizadas de diversas formas, você pode obter ainda mais controle sobre a aparência das suas campanhas usando mensagens projetadas e criadas com HTML, CSS e JavaScript. Com uma composição simples, você pode desbloquear funcionalidades e identidade visual personalizadas para atender a qualquer necessidade.

Esse tipo de mensagem está disponível no editor tradicional.

Como funciona

As mensagens no app em HTML permitem maior controle sobre a aparência e o estilo de uma mensagem, incluindo:

  • Fontes e estilos personalizados
  • Vídeos
  • Múltiplas imagens
  • Comportamentos ao clicar
  • Componentes interativos
  • Animações personalizadas

As mensagens HTML personalizadas podem usar os métodos do JavaScript Bridge para registrar eventos, definir atributos personalizados, fechar a mensagem e muito mais! Confira nosso repositório no GitHub, que contém instruções detalhadas sobre como usar e personalizar mensagens no app em HTML de acordo com suas necessidades, além de um conjunto de modelos de mensagens no app em HTML5 para ajudar você a começar.

Ambientes de renderização

As mensagens no app em HTML personalizadas são renderizadas diretamente no navegador na web, mas dentro de uma WebView da plataforma no iOS e Android. Como cada ambiente usa um mecanismo de renderização diferente, o mesmo HTML e CSS podem apresentar pequenas diferenças visuais entre plataformas, especialmente em layouts de colunas, fontes e espaçamento.

Para minimizar diferenças entre plataformas:

  • Use valores CSS explícitos em vez de depender dos padrões do navegador
  • Inclua uma meta tag de viewport (por exemplo, <meta name="viewport" content="width=device-width, initial-scale=1">)
  • Teste em dispositivos reais com envios de teste

Codificação de caracteres

Ao criar mensagens no app com HTML personalizado que contenham caracteres especiais — como script cirílico, caracteres acentuados ou outros textos não ASCII — inclua a codificação UTF-8 no seu HTML para garantir a exibição correta. Sem a codificação UTF-8, esses caracteres podem aparecer quebrados ou ausentes quando renderizados na webview.

Para ativar a codificação UTF-8, adicione a seguinte meta tag dentro da seção <head> do seu HTML:

1

<meta charset="UTF-8">

Isso força a codificação UTF-8, que é o conjunto de caracteres esperado para webviews que exibem mensagens no app.

JavaScript bridge

Custom HTML in-app messages and Banners support a JavaScript “bridge” to interface with the Braze SDK, allowing you to trigger custom Braze actions when users click on elements with links or otherwise engage with your content. These methods exist with the global brazeBridge or appboyBridge variable.

For example, to log a custom attribute and custom event, then close the message, you could use the following JavaScript within your custom HTML:

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

<button id="button">Set Favorite Color</button>
<script>
// Wait for the `brazeBridge` ready event, "ab.BridgeReady"
window.addEventListener("ab.BridgeReady", function(){
  // Event handler when the button is clicked
  document.querySelector("#button").onclick = function(){
    // Track Button 1 clicks for analytics
    // Note: This requires Android SDK v8.0.0, Web SDK v2.5.0, Swift SDK v5.4.0, and iOS SDK v3.23.0
    brazeBridge.logClick("0");
    // Set the user's custom attribute
    brazeBridge.getUser().setCustomUserAttribute("favorite color", "blue");
    // Track a custom event
    brazeBridge.logCustomEvent("completed survey");
    // Send the enqueued data to Braze
    brazeBridge.requestImmediateDataFlush();
    // Close the message
    brazeBridge.closeMessage();
  };
}, false);
</script>

JavaScript Bridge methods

The following JavaScript methods are supported within custom HTML for in-app messages and Banners:

Nome do método Descrição
brazeBridge.closeMessage() Fecha a mensagem atual. O comportamento varia conforme o canal:

In-App Messages: fecha apenas a interface. Nenhuma dispensa é registrada e nenhuma supressão do lado do servidor ocorre.

Banners: equivalente a chamar logBannerDismissal. Isso registra uma dispensa do Banner, remove o Banner da interface e suprime o Banner para o usuário. Também reativa quaisquer assinantes ativos de subscribeToBannersUpdates. Não chame este método se a mensagem já estiver em processo de fechamento ou se for fechar automaticamente devido ao processamento de um deep link.
window.addEventListener("ab.BridgeReady", function(){...}, false) Método de retorno de chamada para quando o brazeBridge tiver terminado de carregar. Todo o código JavaScript deve ser executado dentro desta função de retorno de chamada.
brazeBridge.requestImmediateDataFlush() Envia dados em fila para os servidores da Braze. Documentos JS
brazeBridge.logClick(button_id_string) Registra um clique de botão para um ID de botão específico. Quando button_id_string estiver em branco, um clique no corpo será registrado em vez disso. A button_id_string pode ser passada como button_id em eventos de cliques em mensagens no app via Currents.

Este método foi introduzido no Android SDK v8.0.0, Web SDK v2.5.0 e iOS SDK v3.23.0.

O button_id_string aceita apenas caracteres alfanuméricos, espaços, traços e sublinhados. Adicionar um caractere com acento (por exemplo, ö, â, ê) quebra o rastreamento de cliques do botão, fazendo com que a string do botão não apareça na seção de análise de dados da Campaign e os cliques não sejam contabilizados.
brazeBridge.logCustomEvent(eventName,eventProperties) Registra um evento personalizado. Documentos JS
brazeBridge.logPurchase(productId, price, currencyCode, quantity, purchaseProperties) Registra uma compra. Documentos JS
brazeBridge.getUser().addAlias(alias, label) Adiciona um alias a um usuário. Introduzido no Web SDK v2.7.0, Android v8.1.0 e iOS SDK v3.26.0. Documentos JS
brazeBridge.getUser().addToCustomAttributeArray(key, value) Adiciona a um array de atributo personalizado. Documentos JS
brazeBridge.getUser().addToSubscriptionGroup(subscriptionGroupId) Adiciona um usuário a um grupo de inscrições de e-mail ou SMS. Documentos JS.

Este método foi introduzido no Android SDK v15.0.0, Web SDK v3.4.0 e iOS SDK v4.3.3.
brazeBridge.getUser().removeFromSubscriptionGroup(subscriptionGroupId) Remove um usuário de um grupo de inscrições de e-mail ou SMS. Documentos JS.

Este método foi introduzido no Android SDK v15.0.0, Web SDK v3.4.0 e iOS SDK v4.3.3.
brazeBridge.getUser().setFirstName(firstName) Define o nome de um usuário. Documentos JS
brazeBridge.getUser().setLastName(lastName) Define o sobrenome de um usuário. Documentos JS
brazeBridge.getUser().setEmail(email) Define o endereço de e-mail de um usuário. Documentos JS
brazeBridge.getUser().setGender(gender) Define o gênero de um usuário. Documentos JS
brazeBridge.getUser().setDateOfBirth(year, month, day) Define a data de nascimento de um usuário. Documentos JS
brazeBridge.getUser().setCountry(country) Define o país de um usuário. Documentos JS
brazeBridge.getUser().setHomeCity(city) Define a cidade de um usuário. Documentos JS
brazeBridge.getUser().setEmailNotificationSubscriptionType(notificationSubscriptionType) Define o status de inscrição para notificação por e-mail. Documentos JS
brazeBridge.getUser().setPushNotificationSubscriptionType(notificationSubscriptionType) Define o status de inscrição para notificação por push. Documentos JS
brazeBridge.getUser().setPhoneNumber(phoneNumber) Define o número de telefone de um usuário. Documentos JS
brazeBridge.getUser().setCustomUserAttribute(key, value, merge) Define um atributo de usuário personalizado. Documentos JS
brazeBridge.getUser().removeFromCustomAttributeArray(key, value) Remove um atributo de usuário personalizado. Documentos JS
brazeBridge.getUser().incrementCustomUserAttribute(key, incrementValue) Incrementa um atributo de usuário personalizado. Documentos JS
brazeBridge.getUser().setLanguage(language) Define o idioma de um usuário. Introduzido no Android SDK v5.0.0 e Web SDK v2.6.0. Documentos JS
brazeBridge.getUser().setCustomLocationAttribute(key, latitude, longitude) Define um atributo de local personalizado. Introduzido no Android SDK v5.0.0. Documentos JS
brazeBridge.web.registerAppboyPushMessages(successCallback, deniedCallback) Registra para web push (apenas na web). Este método não faz nada quando chamado em um ambiente que não seja web. Documentos JS
brazeBridge.requestPushPermission(successCallback, deniedCallback) Registra para push em Web, iOS e Android. Nota: os retornos de chamada do método são compatíveis apenas com a web. Este método foi introduzido a partir do Web SDK v4.0.0, Android SDK v21.0.0 e Swift SDK v5.4.0. Documentos JS
brazeBridge.changeUser(id, sdkAuthSignature?) Identifica o usuário com um ID único. Documentos JS

Este método foi introduzido no Web SDK v4.3.0.

Button click tracking

Use the brazeBridge.logClick(button_id) method to track clicks in your custom HTML.

For in-app messages, you can programmatically track “Button 1”, “Button 2”, and “Body Clicks” using brazeBridge.logClick('0'), brazeBridge.logClick('1'), or brazeBridge.logClick(), respectively.

Clicks Method Supported
Body click brazeBridge.logClick() In-app messages and Banners
Button 1 brazeBridge.logClick('0') In-app messages only
Button 2 brazeBridge.logClick('1') In-app messages only
Custom button tracking brazeBridge.logClick('your custom name here') In-app messages and Banners

For in-app messages, you can track multiple button click events per impression. For example, to close a message and log a Button 2 click:

1

<a href="#" onclick="brazeBridge.logClick('1');brazeBridge.closeMessage()">✖</a>

You can also track new custom button names—up to 100 unique names per campaign. For example, brazeBridge.logClick('blue button') or brazeBridge.logClick('viewed carousel page 3').

Limitations (in-app messages only)

  • You can have up to 100 unique button IDs per campaign.
  • Button IDs can have up to 255 characters each.
  • Button IDs can only include letters, numbers, spaces, dashes, and underscores.

Além do JavaScript personalizado, os SDKs da Braze também podem enviar dados de análise com esses atalhos de URL convenientes. Note que esses parâmetros de consulta e esquemas de URL diferenciam maiúsculas de minúsculas.

Rastreamento de clique em botão (descontinuado)

Para registrar cliques em botões na análise de mensagens no app, você pode adicionar abButtonId como parâmetro de consulta a qualquer deep link, URL de redirecionamento ou elemento âncora <a>. Use ?abButtonId=0 para registrar um clique no “Botão 1” e ?abButtonId=1 para registrar um clique no “Botão 2”.

Assim como outros parâmetros de URL, o primeiro parâmetro deve começar com um ponto de interrogação ?, enquanto os parâmetros subsequentes devem ser separados por um “e” comercial &.

Exemplos de URLs

  • https://example.com/?abButtonId=0 - Clique no Botão 1
  • https://example.com/?abButtonId=1 - Clique no Botão 2
  • https://example.com/?utm_source=braze&abButtonId=0 - Clique no Botão 1 com outros parâmetros de URL existentes
  • myApp://deep-link?page=home&abButtonId=1 - Deep link mobile com clique no Botão 2
  • <a href="https://example.com/?abButtonId=1"> - Elemento âncora <a> com clique no Botão 2

Para abrir links fora do seu app em uma nova janela, defina ?abExternalOpen=true. A mensagem será fechada antes de abrir o link.

Para deep linking, a Braze abrirá sua URL independentemente do valor de abExternalOpen.

Para que a Braze trate seu link HTTP ou HTTPS como um deep link, defina ?abDeepLink=true.

Quando esse parâmetro de string de consulta está ausente ou definido como false, a Braze tentará abrir o link web em um navegador de internet interno dentro do app host.

Fechar mensagem no app

Para fechar uma mensagem no app, você pode usar o método JavaScript brazeBridge.closeMessage().

Por exemplo, <a onclick="brazeBridge.closeMessage()" href="#">Fechar</a> fechará a mensagem no app.

Upload de HTML com prévia

Ao criar mensagens no app com HTML personalizado, você pode visualizar seu conteúdo interativo diretamente na Braze.

O painel de prévia de mensagens do editor mostra uma prévia realista que renderiza o JavaScript incluído na sua mensagem. Você pode visualizar e interagir com suas mensagens personalizadas no painel de prévia clicando na paginação, enviando formulários ou pesquisas, assistindo a animações JavaScript e muito mais!

Interagindo com a prévia de HTML ao deslizar entre as páginas.

Criando uma campaign

Arquivos de ativos

Ao criar mensagens no app com código personalizado usando upload de HTML, você pode fazer upload de ativos da campaign para a biblioteca de mídia para referenciá-los na sua mensagem.

Os seguintes tipos de arquivo são compatíveis para upload:

Tipo de arquivo Extensão do arquivo
Arquivos de fonte .ttf, .woff, .otf, .woff2
Imagens SVG .svg
Arquivos JavaScript .js
Arquivos CSS .css

A Braze recomenda fazer upload de ativos para a biblioteca de mídia por dois motivos:

  1. Ativos adicionados a uma campaign pela biblioteca de mídia permitem que suas mensagens sejam exibidas mesmo quando o usuário estiver offline ou com uma conexão de internet ruim.
  2. Ativos enviados para a Braze podem ser reutilizados em diferentes campaigns.
Adicionando arquivos de ativos

Você pode adicionar ativos novos ou existentes à sua campaign.

Para adicionar novos ativos à sua campaign, use a seção de arrastar e soltar para fazer upload de um arquivo. Ativos adicionados nesta seção também serão automaticamente adicionados à biblioteca de mídia. Para adicionar ativos que você já enviou para a biblioteca de mídia, selecione Adicionar da Biblioteca de Mídia.

Após seus ativos serem adicionados, eles aparecerão na seção Ativos para esta campaign.

Se o nome de um arquivo de ativo corresponder ao de um ativo HTML local, ele será substituído automaticamente (por exemplo, cat.png é enviado e <img src="cat.png" /> existe).

Caso contrário, passe o mouse sobre um ativo da lista e selecione Copiar para copiar a URL do arquivo para a área de transferência. Em seguida, cole a URL do ativo copiado no seu HTML como faria normalmente ao referenciar um ativo remoto.

Editor de HTML

As alterações que você fizer no HTML são renderizadas automaticamente no painel de prévia conforme você digita. Quaisquer métodos JavaScript brazeBridge que você usar no seu HTML não atualizarão perfis de usuário durante a prévia no dashboard.

Rastreamento de botões

Você pode rastrear o desempenho dentro da sua mensagem no app com código personalizado usando o método JavaScript brazeBridge.logClick(button_id). Isso permite rastrear programaticamente “Botão 1”, “Botão 2” e “Cliques no corpo” usando brazeBridge.logClick('0'), brazeBridge.logClick('1') ou brazeBridge.logClick(), respectivamente.

Cliques Método
Botão 1 brazeBridge.logClick('0')
Botão 2 brazeBridge.logClick('1')
Clique no corpo brazeBridge.logClick()
Rastreamento de botão personalizado brazeBridge.logClick('your custom name here')

Use brazeBridge.logClick(button_id) para mensagens HTML com prévia quando você precisar de mais de dois botões rastreados. Botão 1 e Botão 2 correspondem a '0' e '1'; botões adicionais usam IDs personalizados (até 100 IDs únicos por campaign). Para restrições de caracteres em IDs de botões, consulte Rastreamento de botões.

Se um botão na sua mensagem no app com HTML personalizado não carregar ao ser clicado, verifique se o link usa uma URL válida ou um esquema de deep link compatível. URLs malformadas ou esquemas personalizados não compatíveis podem impedir que a ação de clique seja concluída.

Cliques no corpo ao fechar a mensagem

Chamar brazeBridge.closeMessage() fecha a mensagem, mas não registra análise de dados por conta própria. Para registrar um clique no corpo quando o usuário fecha a mensagem, chame brazeBridge.logClick() antes de brazeBridge.closeMessage() para que o registro de cliques permaneça consistente entre as plataformas.

HTML personalizado não renderiza no Android (arquivos zip do Windows)

Se sua mensagem no app com HTML personalizado renderiza na prévia, mas não é exibida em dispositivos Android, verifique como seus arquivos HTML e de ativos foram empacotados. Alguns utilitários de zip do Windows adicionam entradas de diretório (caminhos de pastas) dentro do arquivo em vez de colocar os arquivos no nível raiz.

O Android pode falhar ao carregar ativos referenciados com caminhos relativos quando o zip inclui entradas de diretório aninhadas. Para corrigir isso:

  1. Extraia seus arquivos HTML, CSS, JavaScript e de imagem para uma única pasta.
  2. Selecione todos os arquivos (não a pasta pai) ao criar o arquivo zip.
  3. Confirme que os caminhos no seu HTML referenciam arquivos na raiz do zip (por exemplo, style.css, não assets/style.css), ou ajuste os caminhos para corresponder à estrutura simplificada.
  4. Faça o upload do zip novamente e envie uma mensagem de teste para um dispositivo Android.

Alternativamente, faça upload dos ativos pela biblioteca de mídia em vez de empacotá-los em um arquivo zip.

Alterações incompatíveis com versões anteriores

  1. O deep link braze://close, que era anteriormente compatível com apps móveis, foi removido em favor do JavaScript brazeBridge.closeMessage(). Isso permite mensagens HTML multiplataforma, já que a web não é compatível com deep links.

  2. O rastreamento automático de cliques, que usava ?abButtonId=0 para IDs de botões, e o rastreamento de “clique no corpo” em botões de fechar foram removidos. Os exemplos de código a seguir mostram como alterar seu HTML para usar nossos novos métodos JavaScript de rastreamento de cliques:

    Antes Depois
    <a href="braze://close">Close Button</a> <a href="#" onclick="brazeBridge.logClick();brazeBridge.closeMessage()">Close Button</a>
    <a href="braze://close?abButtonId=0">Close Button</a> <a href="#" onclick="brazeBridge.logClick('0');brazeBridge.closeMessage()">Close Button</a>
    <a href="app://deeplink?abButtonId=0">Track button 1</a> <a href="app://deeplink" onclick="brazeBridge.logClick('0')">Track button 1</a>
    <script>
    location.href = "braze://close?abButtonId=1"
    </script>    		 <script>
    window.addEventListener("ab.BridgeReady", function(){
      brazeBridge.logClick("1");
      brazeBridge.closeMessage();
    });
    </script>
New Stuff!