FAQ Smart App Banner — Configuração no Site (VTEX)
Passo a passo para exibir, no site mobile da sua loja VTEX, uma faixa que convida o visitante a abrir o seu app, ou a baixá-lo na loja de aplicativos caso ainda não esteja instalado.
Entendendo o Smart App Banner
Saiba o que é o banner, como ele se comporta para o visitante do seu site e por que, na VTEX, a instalação precisa ser feita por um desenvolvedor.
O Smart App Banner é uma faixa fixa no topo do site que aparece para quem está navegando pelo celular, convidando o visitante a continuar a experiência no app da sua marca. É uma forma simples de levar o tráfego do site mobile para o aplicativo. Ao tocar em “Abrir”, o comportamento é o seguinte:
1
Se o app já estiver instalado no aparelho, ele é aberto diretamente.
2
Se o app ainda não estiver instalado, o visitante é levado para a página do app na App Store (iPhone) ou no Google Play (Android) para fazer o download.
3
Se o visitante tocar no “×”, o banner é fechado e não aparece mais durante aquela visita ao site.
Diferente de outras plataformas, na VTEX o Smart App Banner não é ativado por um campo do painel administrativo, nem por uma tag de HTML personalizado no Google Tag Manager: o app oficial de Google Tag Manager da VTEX bloqueia esse tipo de tag por padrão. O caminho suportado pela própria VTEX para rodar um script em todas as páginas da loja é um Pixel App, um app do VTEX IO criado a partir do template oficial da VTEX (vtex-apps/pixel-app-template).
Antes de Começar
Reúna as informações e os acessos necessários antes de iniciar a implementação. Isso evita interrupções no meio do processo.
Separe os itens abaixo antes de acionar o desenvolvedor responsável pela sua loja:
1
Link do app na App Store (iOS): o endereço da página do seu app na loja da Apple, no formato https://apps.apple.com/.../app/nome-do-app/id000000000.
2
Link do app no Google Play (Android): o endereço da página do seu app na loja do Google, no formato https://play.google.com/store/apps/details?id=....
3
Deep link (URL scheme) do app: o endereço que abre o app diretamente a partir do site (ex.: nomedoapp://). Essa informação é fornecida pelo time técnico da Eitri; se ainda não tiver recebido, solicite ao time.
4
Ícone do app: imagem quadrada, recomendado 96 × 96 px ou maior, hospedada em uma URL pública acessível pelo site (por exemplo, no gerenciador de arquivos da própria VTEX).
5
Desenvolvedor com acesso ao VTEX IO da loja: com o VTEX IO CLI (toolbelt) configurado e permissão para instalar apps na conta da loja.
Sim. É possível implementar o banner apenas para o sistema operacional em que o app já está publicado, por exemplo só para iPhone enquanto o app Android ainda não está disponível.
1
Na configuração do Pixel App, preencha apenas o link da loja em que o app já está publicado e deixe o outro campo em branco.
2
O código de referência (veja Qual código devo usar?) já trata esse cenário: o banner não é exibido no sistema operacional que estiver com o link em branco.
3
Quando o app for publicado na outra loja, basta preencher o link correspondente nas configurações do Pixel App. Não é necessário um novo deploy.
Implementação
Passo a passo técnico para o desenvolvedor responsável pela sua loja VTEX, com o código de referência e as orientações de teste.
Crie o Pixel App a partir do template oficial da VTEX (vtex-apps/pixel-app-template), vinculado à conta VTEX da sua loja.
2
Cadastre as configurações do app (settings, editáveis depois pelo painel administrativo): link da App Store, link do Google Play, deep link e URL do ícone. Assim, esses valores podem ser atualizados no futuro sem precisar de um novo deploy.
3
Cole o HTML, o CSS e o JavaScript do código de referência (veja Qual código devo usar?) no arquivo pixel/head.html do app, substituindo os valores entre {{ }} pelas configurações cadastradas no passo anterior.
Publique o app e promova o workspace para produção (master), seguindo o fluxo de deploy padrão da sua loja.
Abaixo está o código de referência, dividido em HTML, CSS e JavaScript. Ele já inclui os ajustes descritos em O que verificar antes de publicar o banner?, como o cancelamento do redirecionamento para a loja quando o app abre de fato.
Antes de usar
Substitua os valores entre {{ }} pelos dados do seu app (ou pelas configurações equivalentes do Pixel App, se seguido o passo 2 de Como implementar o Smart App Banner na VTEX?):
{{ICONE_DO_APP}}: URL pública do ícone do app.
{{URL_APP_STORE}}: link do app na App Store.
{{URL_GOOGLE_PLAY}}: link do app no Google Play (deixe em branco se o app Android ainda não existir).
{{DEEP_LINK}}: deep link do app fornecido pelo time técnico da Eitri (ex.: nomedoapp://).
HTML
<div id="smart-app-banner" class="smart-app-banner">
<div class="smart-app-banner__icon">
<img src="{{ICONE_DO_APP}}" alt="App">
</div>
<div class="smart-app-banner__content">
<strong>Abra no aplicativo</strong>
<span>Tenha uma experiência melhor no app</span>
</div>
<button id="smart-app-banner-button">Abrir</button>
<button id="smart-app-banner-close" class="smart-app-banner__close" aria-label="Fechar">×</button>
</div>
const APP_STORE_URL = '{{URL_APP_STORE}}'
// Deixe em branco ('') se o app Android ainda não estiver publicado:
// o banner não será exibido em aparelhos Android até ser preenchido.
const PLAY_STORE_URL = '{{URL_GOOGLE_PLAY}}'
const DEEP_LINK_SCHEME = '{{DEEP_LINK}}'
const banner = document.getElementById('smart-app-banner')
const openButton = document.getElementById('smart-app-banner-button')
const closeButton = document.getElementById('smart-app-banner-close')
const userAgent = navigator.userAgent || navigator.vendor || window.opera
const isIOS = /iPad|iPhone|iPod/.test(userAgent) && !window.MSStream
const isAndroid = /Android/i.test(userAgent)
function getStoreUrl() {
if (isIOS) return APP_STORE_URL
if (isAndroid) return PLAY_STORE_URL
return null
}
// Exibe o banner só em celulares cujo sistema tenha o link da loja preenchido.
if (!getStoreUrl()) banner.remove()
function openApp() {
const storeUrl = getStoreUrl()
if (!storeUrl) return
// Cancela o redirecionamento para a loja se o usuário realmente
// sair da aba (o app abriu) e voltar depois.
let didHide = false
const onHide = () => { if (document.hidden) didHide = true }
document.addEventListener('visibilitychange', onHide)
window.location.href = DEEP_LINK_SCHEME
setTimeout(() => {
document.removeEventListener('visibilitychange', onHide)
if (!didHide) window.location.href = storeUrl
}, 1500)
}
openButton.addEventListener('click', openApp)
closeButton.addEventListener('click', () => {
banner.remove()
sessionStorage.setItem('smart-app-banner-closed', 'true')
})
if (sessionStorage.getItem('smart-app-banner-closed') === 'true') {
banner.remove()
}
O teste deve ser feito em um workspace de desenvolvimento da VTEX e em celulares reais, para garantir que o banner aparece corretamente e que os botões funcionam como esperado.
1
Instale o Pixel App em um workspace de desenvolvimento da sua loja (nunca direto em produção).
2
Abra o link desse workspace em um iPhone com Safari e confira se o banner aparece no topo do site.
3
Com o app instalado, toque em “Abrir” e confirme que o app é aberto. Volte ao navegador e confirme que você não foi redirecionado para a App Store.
4
Com o app desinstalado, toque em “Abrir” e confirme que você é levado para a página do app na App Store.
5
Toque no “×” e confirme que o banner some e não reaparece ao navegar por outras páginas.
6
Se o app Android já estiver publicado, repita os passos 2 a 5 em um aparelho Android com Chrome.
7
Abra o site no computador e confirme que o banner não aparece.
Pontos de Atenção
Comportamentos que vale conhecer e validar antes de publicar o banner em produção.
Alguns comportamentos dependem do aparelho e do navegador do visitante. Confira cada ponto abaixo e confirme com o seu time se o resultado é o esperado.
Retorno do app para o navegador
Quando o app abre de fato, o redirecionamento para a loja de aplicativos poderia disparar por engano quando o visitante volta ao navegador. O código de referência (veja Qual código devo usar?) já evita isso, cancelando o redirecionamento quando a aba do navegador fica oculta.
Aparelhos Android
No Chrome para Android, abrir o app por deep link (URL scheme) tende a ser menos confiável do que no iPhone. Se o app não abrir nos seus testes, converse com o time técnico da Eitri sobre alternativas, como uma intent URL do Android ou App Links, caso o app tenha esse recurso configurado.
iPad
iPads com iPadOS 13 ou mais recente se identificam como Safari de computador. Com a lógica atual, o banner não aparece nesses aparelhos. Confirme com o seu time se esse comportamento é o esperado.
Fechamento do banner
Ao tocar no “×”, o banner fica oculto apenas durante a sessão do navegador: ele volta a aparecer em uma nova visita ao site. Confirme com o seu time se esse comportamento é o desejado.
Sim. O código de referência traz um visual neutro, que pode ser adaptado à identidade da sua marca. Os principais pontos de personalização são:
1
Textos: no HTML, altere o título (“Abra no aplicativo”), o subtítulo (“Tenha uma experiência melhor no app”) e o texto do botão (“Abrir”).
2
Cor do botão: no CSS, altere o valor de background do seletor #smart-app-banner-button para a cor da sua marca.
3
Cores de fundo e de texto: no CSS, ajuste background do .smart-app-banner e os valores de color do título e do subtítulo.
Finalização
Últimos passos após publicar o Smart App Banner no site da sua loja.
Parabéns! Com o banner publicado, os visitantes do seu site mobile passam a ser convidados a continuar a experiência no app.
1
Acesse o site de produção pelo celular e confirme que o banner aparece e funciona como nos testes.
2
Quando o app for publicado em uma nova loja (por exemplo, Google Play), preencha o link correspondente nas configurações do Pixel App e teste novamente.
3
Comunique à equipe da Eitri que o banner foi publicado.