Guia

Coloque um widget de eSIM no seu site com uma tag de script

O widget da Atli põe uma loja completa de eSIM de viagem e seu código de parceiro numa tag de script. Como instalar, estilizar, medir vendas e testar.

Uma página da web num navegador com o widget de eSIM da Atli incorporado abaixo do artigo, listando destinos e preços, ao lado do mascote azul com asas da Atli segurando cartões de planos

O widget da Atli permite adicionar uma loja completa de eSIM de viagem ao seu site com uma única tag de script. Os visitantes podem buscar destinos, comparar planos, fazer o pagamento e receber o código QR do eSIM sem sair da sua página. O seu código de parceiro vem incluído no script para que as compras elegíveis sejam atribuídas à sua conta.

Incorporar não custa nada e não exige etapa de build. A Atli cuida do catálogo, do pagamento e da entrega do eSIM. A instalação exige apenas um contêiner e uma tag de script.

Esta página roda o widget de verdade:

Como adicionar o widget a uma página

Entre em partners.heyatli.com e abra Integrações. O card Widget incorporado mostra o código para o seu site com o seu código de parceiro já incluído. Personalizar abre o criador do widget em partners.heyatli.com/pt/dev/atli-widget, onde você pode mudar qualquer configuração e copiar o código de novo.

O card Widget incorporado na página Integrações de partners.heyatli.com, com o código para o seu site e os botões Visualizar e Personalizar

Se preferir adicionar o código diretamente, troque YOUR_CODE pelo seu código de parceiro:

HTML
<div id="heyatli-esim-checkout-container"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#heyatli-esim-checkout-container"
  data-referral="YOUR_CODE"
  defer
></script>

Cole-o no HTML da página onde a loja deve aparecer. O widget ocupa toda a largura do contêiner e cresce até a altura do que estiver mostrando. Não há altura para definir. Sem o <div> e o data-target, ele aparece logo depois da tag de script.

O script tem cerca de 17 KB e não precisa de mais nada instalado. Ele carrega a loja num iframe servido por embed.heyatli.com, e esse iframe não consegue ler a sua página nem os cookies e o armazenamento dela. Os dados do cartão vão para o formulário de pagamento da Stripe dentro do iframe.

Como abrir o widget num destino

Para páginas sobre um país específico, você pode configurar o widget para mostrar os planos desse destino. Esta versão abre no Japão para um guia em alemão e mostra os preços em euros:

HTML
<div id="japan-esim"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#japan-esim"
  data-referral="YOUR_CODE"
  data-destination="jp"
  data-lang="de"
  data-lang-priority="widget"
  data-currency="EUR"
  defer
></script>
O widget da Atli aberto no Japão em alemão, com preços em euros e planos ilimitados de 5 a 30 dias, cada um com um botão eSIM kaufen

data-destination aceita um código de país de duas letras (jp), o nome de um país em qualquer um dos idiomas do widget (Japan, 日本), uma região (europe, south_east_asia) ou o ID de um plano. O ID de um plano abre o checkout desse plano. O widget só abre um destino quando encontra uma correspondência válida. Caso contrário, mostra a tela inicial padrão. De um jeito ou de outro, os visitantes continuam podendo buscar qualquer destino.

data-favorites preenche a aba Top com até 32 destinos escolhidos por você e mantém a ordem em que você os listar. Por exemplo: data-favorites="jp, kr, tw, asia".

Configurações do widget

Todas as configurações são opcionais. Na tag de script, cada uma é um atributo data-. Em JavaScript, é o mesmo nome em camelCase: data-lang-priority vira langPriority.

AtributoO que faz
data-referralO seu código de parceiro. Clientes novos que compram ficam vinculados a você.
data-destinationAbre num destino ou plano.
data-favoritesAté 32 destinos para a aba Top, separados por vírgula.
data-langO idioma do widget. Sem ele, vale o idioma do navegador do visitante.
data-lang-prioritywidget mantém o seu idioma mesmo que o visitante tenha escolhido outro e esconde o menu de idiomas.
data-currencyA moeda dos preços e do pagamento. USD por padrão.
data-currency-prioritywidget mantém a sua moeda mesmo que o visitante tenha escolhido outra.
data-themelight ou dark. Sem ele, vale a configuração do aparelho do visitante.
data-theme-prioritywidget mantém o seu tema e esconde a configuração de tema.
data-cssO endereço https:// da sua própria folha de estilo para o widget.
data-bootAbre numa das telas do próprio visitante: esims, credits, vouchers, refer, settings, payment-methods, groups ou profile. esim abre a página de instalação do eSIM compartilhado cujo código você passa em data-lpa, e essa página não exige conta.
data-anonymous-cardstrue permite que visitantes sem login salvem um cartão neste navegador. Desligado por padrão.
data-stripe-linkfalse tira o Stripe Link do formulário de pagamento.
data-analyticsoff impede o widget de carregar o próprio analytics.
data-consentall, analytics ou none, conforme o que o seu banner de cookies coletou.
data-envstaging roda o widget no Sandbox da Atli. Deixe de fora numa página no ar.

O widget oferece suporte a 15 idiomas: en inglês, pt português, es espanhol, fr francês, it italiano, de alemão, pl polonês, ru russo, zh chinês, ko coreano, ja japonês, id indonésio, vi vietnamita, ms malaio e ar árabe. Ele mostra preços em AUD, CAD, EUR, GBP, HKD, JPY, KRW, SGD, TWD, USD e VND. Valores não suportados são ignorados. Por exemplo, com data-currency="EUROS" o widget usa USD por padrão.

Como adicionar o widget a uma SPA

A tag de script inicializa o widget quando a página carrega, mas não reage automaticamente às mudanças de rota da sua aplicação. Em React, Vue, Next.js ou qualquer app que troca de página sem recarregar, carregue o script uma vez no HTML e monte o widget pelo seu código:

HTML
<script src="https://embed.heyatli.com/embed.js"></script>
JavaScript
const widget = HeyAtli.init({
  target: '#esim',
  referral: 'YOUR_CODE',
  destination: 'jp',
  lang: 'de',
  currency: 'EUR',
});

// Change settings later without rebuilding the frame
widget.update({ destination: 'th' });

// Remove it when the page goes away
widget.destroy();

target aceita um seletor CSS ou um elemento. update() mescla o que você passar às configurações atuais e não recarrega o iframe. Em React, o widget vai dentro de um efeito:

JSX
import { useEffect, useRef } from 'react';

export function EsimStore({ destination }) {
  const ref = useRef(null);

  useEffect(() => {
    const widget = window.HeyAtli.init({
      target: ref.current,
      referral: 'YOUR_CODE',
      destination,
    });
    return () => widget.destroy();
  }, [destination]);

  return <div ref={ref} />;
}

Em desenvolvimento, o Strict Mode do React executa cada efeito, faz a limpeza e executa de novo. Inclua destroy() na função de limpeza para evitar instâncias duplicadas do widget.

Como estilizar o widget com CSS

Passe para data-css o endereço https:// completo de uma folha de estilo do seu site. O widget a carrega dentro do iframe depois dos próprios estilos, então seletores simples vencem sem !important. Se o arquivo não carregar, o widget mantém o visual padrão.

Uma linha fica fora do seu alcance. Toda tela termina num rodapé Desenvolvido por Atli | Suporte que a sua folha de estilo não consegue reestilizar nem esconder. Uma folha de estilo que esconde, esmaece, corta ou cobre esse rodapé é descartada, o widget volta ao visual padrão pelo resto da visita, e o console do navegador explica o motivo.

Comece pelas variáveis CSS do widget. Os visitantes podem ver o tema claro ou o escuro. Defina as variáveis para os dois:

CSS
.atli-widget {
  --atli-font-family: 'Inter', system-ui, sans-serif;
  --atli-color-accent: #0f766e;
  --atli-color-accent-hover: #115e59;
  --atli-color-accent-text: #ffffff;
  --atli-radius-md: 6px;
}

.atli-widget[data-theme='dark'] {
  --atli-color-accent: #2dd4bf;
  --atli-color-accent-hover: #5eead4;
  --atli-color-accent-text: #042f2e;
}

sunset.css e mono.css são exemplos comentados que cobrem todas as variáveis comuns. Os campos do cartão ficam no iframe da própria Stripe, onde nenhuma folha de estilo chega. Em vez disso, quando monta o formulário de pagamento, o widget passa para a Stripe as suas cores de destaque, de texto e de superfície, a sua fonte e o arredondamento dos cantos.

A mesma página do Japão no widget da Atli em quatro versões: o visual claro padrão, o tema escuro, o sunset.css com botões laranja e fonte serifada e o mono.css em fonte monoespaçada com botões cinza

A personalização com CSS permite adaptar o widget à identidade visual do seu site. Para ter controle total da interface, use a API da Atli, que exige desenvolvimento adicional.

Como acompanhar compras com os eventos do widget

O widget emite eventos que o seu site pode usar para acompanhar a atividade dos visitantes e as compras. Para mandar as compras para o seu analytics, monte o widget com HeyAtli.init() e escute purchase.completed. Este handler entrega cada compra ao Google Tag Manager no formato de e-commerce do GA4:

JavaScript
const widget = HeyAtli.init({ target: '#esim', referral: 'YOUR_CODE' });

widget.on('purchase.completed', function (detail) {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ ecommerce: null });
  window.dataLayer.push({
    event: 'purchase',
    ecommerce: {
      transaction_id: detail.transactionId,
      value: detail.value,
      currency: detail.currency,
      items: detail.items,
    },
  });
});

items chega no formato de item do GA4, então vai para o dataLayer sem mudanças. value vem na unidade principal da moeda e traz 12.99 em vez de 1299. O primeiro push limpa o objeto ecommerce anterior, como o Google recomenda antes de cada evento de e-commerce.

Entre os outros eventos estão checkout.opened, payment.started e payment.failed. Um handler recebe (detail, info), e info.action dá o nome do evento, então widget.on('*', handler) consegue repassar todos eles. Para registrar cada evento no console do navegador, adicione debug: true ao init() ou data-debug="true" à tag de script.

Os eventos só chegam a domínios que estão na lista de permissões da Atli. Estão nela heyatli.com e localhost, então você pode desenvolver na sua própria máquina. É também por isso que um handler que funciona em localhost pode parar de receber eventos no seu site no ar. Peça a [email protected] que inclua o seu domínio. O widget continua processando compras mesmo quando o rastreamento de eventos não está disponível.

Como testar no Sandbox

Adicione data-env="staging", ou env: 'staging' em HeyAtli.init(), para rodar o widget no Sandbox da Atli. Um selo Sandbox aparece no canto, e o banner de teste mostra discretamente o seu código de parceiro para você conferir se a página o pegou. Pague com o cartão de teste da Stripe 4242 4242 4242 4242, qualquer data de validade futura e qualquer código de segurança. As contas do Sandbox são separadas das contas reais. Os eSIMs do Sandbox vêm de uma operadora de teste, então não podem ser instalados num celular, e as vendas no Sandbox nunca rendem comissão.

O widget usa o ambiente de produção por padrão. Remova data-env="staging" antes de publicar, porque o Sandbox só aceita pagamentos de teste.

Como as vendas do widget são creditadas

Um visitante que compra no widget fica vinculado a você quando entra na conta ou paga, a não ser que o código de outro parceiro ou uma compra anterior tenha vindo antes. O widget guarda o seu código no navegador do visitante por 72 horas, então quem volta no dia seguinte ainda conta. Depois dessa primeira compra o vínculo é permanente, e as compras seguintes na mesma conta da Atli também contam para você.

Os preços são os mesmos da loja da Atli, e um desconto do seu código aparece no checkout. O guia do programa de afiliados da Atli explica ganhos e pagamentos.

Perguntas frequentes

O widget da Atli custa alguma coisa?
Não. Incorporar é grátis, e a Atli recebe o pagamento e entrega o eSIM. Você ganha a sua comissão sobre o que os seus visitantes compram.
Preciso ter conta própria na Stripe?
Não. O widget cobra na conta Stripe da Atli dentro do próprio iframe, então os dados do cartão nunca chegam ao seu site. É o nome da Atli que aparece na fatura do cartão do comprador.
Os visitantes conseguem instalar o eSIM pelo widget?
Sim. Depois do pagamento, os visitantes recebem o código QR do eSIM, os links de instalação para iPhone e Android e os dados para a instalação manual. Os nossos guias para iPhone e Android mostram os passos no celular.
Posso limitar o widget aos países sobre os quais escrevo?
Em parte. data-destination abre o widget num destino, e data-favorites preenche a aba Top com até 32 destinos escolhidos por você. Os visitantes continuam podendo buscar no catálogo inteiro.
O widget deixa a minha página mais lenta?
Não no carregamento. O script de carregamento tem cerca de 17 KB, e a loja em si espera até o iframe se aproximar da parte visível da página. Se o widget aparecer perto do fim de um artigo, o conteúdo dele é carregado à medida que o visitante chega perto dessa seção.
Posso colocar dois widgets na mesma página?
Sim. Dê a cada um o próprio contêiner e a própria tag de script, ou chame HeyAtli.init() uma vez para cada contêiner.