
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.

Se preferisci aggiungere il codice direttamente, sostituisci YOUR_CODE con il tuo codice partner:
<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:
<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>
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.
| Attributo | Cosa fa |
|---|---|
data-referral | Il tuo codice partner. I nuovi clienti che comprano vengono associati a te. |
data-destination | Apre il widget su una destinazione o su un piano. |
data-favorites | Fino a 32 destinazioni separate da virgole per la scheda Top. |
data-lang | La lingua del widget. Se manca, vale la lingua del browser del visitatore. |
data-lang-priority | widget mantiene la tua lingua anche se il visitatore ne ha scelta un’altra e nasconde il menu della lingua. |
data-currency | La valuta per prezzi e pagamento. Il valore predefinito è USD. |
data-currency-priority | widget mantiene la tua valuta anche se il visitatore ne ha scelta un’altra. |
data-theme | light o dark. Se manca, vale l’impostazione del dispositivo del visitatore. |
data-theme-priority | widget mantiene il tuo tema e nasconde l’impostazione del tema. |
data-css | L’indirizzo https:// del tuo foglio di stile per il widget. |
data-boot | Apre 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-cards | true permette ai visitatori che non hanno fatto l’accesso di salvare una carta nel browser che stanno usando. Disattivato di default. |
data-stripe-link | false toglie Stripe Link dal modulo di pagamento. |
data-analytics | off impedisce al widget di caricare i propri analytics. |
data-consent | Riporta il consenso raccolto dal tuo banner dei cookie: all, analytics o none. |
data-env | staging 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:
<script src="https://embed.heyatli.com/embed.js"></script>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:
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:
.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 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:
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?
Mi serve un mio account Stripe?
I visitatori possono installare la eSIM dal widget?
Posso limitare il widget ai paesi di cui scrivo?
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?
Posso mettere due widget nella stessa pagina?
HeyAtli.init() una volta per ogni contenitore.


