Guida

Aggiungi un widget eSIM al tuo sito con un solo tag script

Il widget Atli è uno store di eSIM da viaggio con il tuo codice partner. Come installarlo, cambiarne lo stile, tracciare le vendite e testarlo in Sandbox.

Una pagina web nel browser con il widget di Atli eSIM incorporato sotto l'articolo, che elenca destinazioni e prezzi, accanto alla mascotte blu alata di Atli con in mano le schede dei piani

Il widget di Atli ti permette di aggiungere al tuo sito uno store completo di eSIM da viaggio con un solo tag script. I visitatori possono cercare destinazioni, confrontare i piani, effettuare il pagamento e ricevere il codice QR della loro eSIM senza lasciare la tua pagina. Il tuo codice partner è incluso nello script, così gli acquisti idonei vengono attribuiti al tuo account.

Incorporarlo non costa nulla e non richiede nessuna fase di build. Atli gestisce il catalogo, il pagamento e la consegna della eSIM. L’installazione richiede solo un contenitore e un tag script.

Questa pagina ospita il widget vero:

Aggiungere il widget a una pagina

Accedi a partners.heyatli.com e apri Integrazioni. Il riquadro Widget incorporato mostra il codice per il tuo sito con il tuo codice partner già inserito. Il pulsante Personalizza apre il configuratore del widget su partners.heyatli.com/it/dev/atli-widget, dove puoi cambiare ogni impostazione e copiare di nuovo il codice.

Il riquadro Widget incorporato nella pagina Integrazioni di partners.heyatli.com, con il codice per il tuo sito e i pulsanti Anteprima e Personalizza

Se preferisci aggiungere il codice direttamente, sostituisci YOUR_CODE con il tuo codice partner:

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>

Incollalo nell’HTML della pagina nel punto in cui deve comparire lo store. Il widget occupa tutta la larghezza del suo contenitore e cresce in altezza in base a quello che mostra. Non c’è nessuna altezza da impostare. Se togli il <div> e data-target, il widget compare subito dopo il tag script.

Lo script pesa circa 17 KB e non richiede di installare nient’altro. Carica lo store in un frame da embed.heyatli.com, e quel frame non può leggere la tua pagina, i suoi cookie o il suo storage. I dati della carta finiscono nel modulo di pagamento di Stripe dentro il frame.

Aprire il widget su una destinazione

Per le pagine dedicate a un paese, puoi configurare il widget in modo che mostri i piani di quella destinazione. Questa versione si apre sul Giappone per una guida in tedesco e mostra i prezzi in euro:

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>
Il widget di Atli aperto sul Giappone in tedesco, con prezzi in euro e piani illimitati da 5 a 30 giorni, ciascuno con un pulsante eSIM kaufen

data-destination accetta un codice paese di due lettere (jp), il nome di un paese in una qualsiasi delle lingue del widget (Japan, 日本), una regione (europe, south_east_asia) o l’ID di un piano. Un ID di piano apre il checkout di quel piano. Il widget apre una destinazione solo quando trova una corrispondenza valida. Altrimenti mostra la schermata iniziale predefinita. In ogni caso i visitatori possono cercare tutte le destinazioni.

data-favorites riempie la scheda Top con un massimo di 32 destinazioni scelte da te e le mantiene nell’ordine in cui le elenchi. Per esempio: data-favorites="jp, kr, tw, asia".

Impostazioni del widget

Tutte le impostazioni sono facoltative. Nel tag script ognuna è un attributo data-. In JavaScript ha lo stesso nome in camelCase: data-lang-priority diventa langPriority.

AttributoCosa fa
data-referralIl tuo codice partner. I nuovi clienti che comprano vengono associati a te.
data-destinationApre il widget su una destinazione o su un piano.
data-favoritesFino a 32 destinazioni separate da virgole per la scheda Top.
data-langLa lingua del widget. Se manca, vale la lingua del browser del visitatore.
data-lang-prioritywidget mantiene la tua lingua anche se il visitatore ne ha scelta un’altra e nasconde il menu della lingua.
data-currencyLa valuta per prezzi e pagamento. Il valore predefinito è USD.
data-currency-prioritywidget mantiene la tua valuta anche se il visitatore ne ha scelta un’altra.
data-themelight o dark. Se manca, vale l’impostazione del dispositivo del visitatore.
data-theme-prioritywidget mantiene il tuo tema e nasconde l’impostazione del tema.
data-cssL’indirizzo https:// del tuo foglio di stile per il widget.
data-bootApre il widget su una delle schermate personali del visitatore: esims, credits, vouchers, refer, settings, payment-methods, groups o profile. esim apre la pagina di installazione della eSIM condivisa il cui codice passi in data-lpa, e quella pagina non richiede un account.
data-anonymous-cardstrue permette ai visitatori che non hanno fatto l’accesso di salvare una carta nel browser che stanno usando. Disattivato di default.
data-stripe-linkfalse toglie Stripe Link dal modulo di pagamento.
data-analyticsoff impedisce al widget di caricare i propri analytics.
data-consentRiporta il consenso raccolto dal tuo banner dei cookie: all, analytics o none.
data-envstaging fa girare il widget sulla Sandbox di Atli. Non usarlo su una pagina online.

Il widget supporta 15 lingue: en inglese, pt portoghese, es spagnolo, fr francese, it italiano, de tedesco, pl polacco, ru russo, zh cinese, ko coreano, ja giapponese, id indonesiano, vi vietnamita, ms malese e ar arabo. Mostra i prezzi in AUD, CAD, EUR, GBP, HKD, JPY, KRW, SGD, TWD, USD e VND. I valori non supportati vengono ignorati. Per esempio, con data-currency="EUROS" il widget usa USD, che è la valuta predefinita.

Aggiungere il widget a una single-page app

Il tag script inizializza il widget al caricamento della pagina, ma non reagisce automaticamente ai cambi di routing della tua applicazione. In React, Vue, Next.js o in qualsiasi app che cambia pagina senza ricaricamento, carica lo script una volta nell’HTML e monta il widget dal tuo codice:

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 accetta un selettore CSS o un elemento. update() unisce quello che passi alle impostazioni correnti e non ricarica il frame. In React il widget va dentro un effect:

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} />;
}

In sviluppo lo Strict Mode di React esegue ogni effect, lo ripulisce e lo esegue di nuovo. Includi destroy() nella funzione di cleanup per evitare istanze duplicate del widget.

Cambiare lo stile del widget con CSS

Passa a data-css l’indirizzo https:// completo di un foglio di stile sul tuo sito. Il widget lo carica dentro il suo frame dopo i propri stili, quindi i selettori semplici vincono senza !important. Se il file non si carica, il widget mantiene l’aspetto predefinito.

Una riga resta fuori dalla tua portata. Ogni schermata termina con un footer Offerto da Atli | Assistenza che il tuo foglio di stile non può modificare né nascondere. Un foglio di stile che lo nasconde, lo sbiadisce, lo taglia o lo copre viene scartato, il widget torna all’aspetto predefinito per il resto della visita e la console del browser spiega perché.

Parti dalle variabili CSS del widget. I visitatori possono vedere il tema chiaro o quello scuro. Imposta le variabili per entrambi:

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 sono esempi pronti e commentati che coprono tutte le variabili più comuni. I campi della carta stanno nel frame di Stripe, dove nessun foglio di stile può arrivare. Quando il widget costruisce il modulo di pagamento, passa invece a Stripe i tuoi colori di accento, testo e superficie, il tuo font e il raggio degli angoli.

La stessa pagina del Giappone nel widget di Atli in quattro versioni: l'aspetto chiaro predefinito, il tema scuro, sunset.css con pulsanti arancioni e caratteri con grazie, e mono.css a spaziatura fissa con pulsanti grigi

La personalizzazione con CSS ti permette di adattare il widget all’identità visiva del tuo sito. Per il pieno controllo dell’interfaccia usa l’API di Atli, che richiede uno sviluppo aggiuntivo.

Tracciare gli acquisti con gli eventi del widget

Il widget emette eventi che il tuo sito può usare per tracciare l’attività dei visitatori e gli acquisti. Per mandare gli acquisti ai tuoi analytics, montalo con HeyAtli.init() e ascolta purchase.completed. Questo handler passa ogni acquisto a Google Tag Manager nel formato ecommerce di 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 arriva già nel formato degli item di GA4, quindi va nel dataLayer così com’è. value è nell’unità principale della valuta e vale 12.99 anziché 1299. Il primo push svuota l’oggetto ecommerce precedente, come Google consiglia di fare prima di ogni evento ecommerce.

Tra gli altri eventi ci sono checkout.opened, payment.started e payment.failed. Un handler riceve (detail, info) e info.action contiene il nome dell’evento, quindi widget.on('*', handler) può inoltrarli tutti. Per vedere tutti gli eventi nella console del browser, aggiungi debug: true a init() oppure data-debug="true" al tag script.

Gli eventi arrivano solo ai domini presenti nell’allowlist di Atli. Nella lista ci sono heyatli.com e localhost, quindi puoi sviluppare sulla tua macchina. È anche il motivo per cui un handler che funziona su localhost può smettere di ricevere eventi sul sito online. Scrivi a [email protected] per far aggiungere il tuo dominio. Il widget può elaborare gli acquisti anche quando il tracciamento degli eventi non è disponibile.

Testare in Sandbox

Per far girare il widget sulla Sandbox di Atli aggiungi data-env="staging" oppure env: 'staging' in HeyAtli.init(). In un angolo compare un’etichetta Sandbox, e il tuo codice partner appare sbiadito nel banner di test, così puoi controllare che la pagina lo stia usando. Paga con la carta di test di Stripe 4242 4242 4242 4242, una qualsiasi data di scadenza futura e un codice di sicurezza qualsiasi. Gli account della Sandbox sono separati da quelli reali. Le eSIM della Sandbox vengono da un operatore di test, quindi non si possono installare su un telefono, e le vendite in Sandbox non generano mai commissioni.

Per impostazione predefinita il widget usa l’ambiente di produzione. Rimuovi data-env="staging" prima di pubblicare, perché la Sandbox accetta solo pagamenti di test.

Come vengono attribuite le vendite del widget

Un visitatore che compra nel widget viene associato a te quando accede o paga, a meno che non siano arrivati prima il codice di un altro partner o un suo acquisto precedente. Il widget ricorda il tuo codice nel browser del visitatore per 72 ore, quindi chi torna il giorno dopo conta ancora. Dopo quel primo acquisto l’associazione è permanente, e anche gli acquisti successivi sullo stesso account Atli contano per te.

I prezzi sono gli stessi dello store di Atli, e lo sconto del tuo codice compare al checkout. La guida al programma di affiliazione Atli spiega guadagni e pagamenti.

Domande frequenti

Il widget di Atli costa qualcosa?
No. Incorporarlo è gratis, e il pagamento e la consegna della eSIM li gestisce Atli. Tu guadagni la tua quota su quello che comprano i tuoi visitatori.
Mi serve un mio account Stripe?
No. Il widget incassa sull’account Stripe di Atli dentro il proprio frame, quindi i dati della carta non arrivano mai al tuo sito. Sull’estratto conto di chi compra compare il nome di Atli.
I visitatori possono installare la eSIM dal widget?
Sì. Dopo il pagamento i visitatori ricevono il codice QR della loro eSIM, i link di installazione per iPhone e Android e i dati per l’installazione manuale. Le nostre guide per iPhone e Android spiegano i passaggi sul telefono.
Posso limitare il widget ai paesi di cui scrivo?
In parte. data-destination lo apre su una destinazione e data-favorites riempie la scheda Top con un massimo di 32 destinazioni scelte da te. I visitatori possono comunque cercare nell’intero catalogo.
Il widget rallenta la mia pagina?
Non al caricamento. Il loader pesa circa 17 KB e lo store vero e proprio aspetta che il frame si avvicini alla parte visibile della pagina. Se il widget si trova verso la fine di un articolo, il suo contenuto si carica man mano che il visitatore scorre verso quella sezione.
Posso mettere due widget nella stessa pagina?
Sì. Dai a ciascuno il suo contenitore e il suo tag script, oppure chiama HeyAtli.init() una volta per ogni contenitore.