Integrazione personalizzata

Lo script Elements di Zonos è disponibile al seguente URL:

<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />

Gestione della cache del browser

Consigliamo anche di aggiungere un timestamp o un altro identificatore unico all'URL per garantire che lo script non venga memorizzato nella cache dal browser. Questo garantirà che l'ultima versione dello script venga sempre caricata. Ad esempio:

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
      script.addEventListener(
        'load',
        () => {
          // Initialize the script here (instructions in next section)
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>

Una volta caricato lo script JS di Zonos, è necessario autenticare passando una chiave API di Zonos e l'ID del negozio nella funzione Zonos.init. Le chiavi API utilizzate per autenticare Checkout sono progettate per essere pubblicabili, il che significa che possono essere utilizzate in modo sicuro nel codice frontend senza esporre informazioni sensibili.

Zonos.init({
  // ... other fields
  zonosApiKey: 'API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Per garantire che lo script JS di Zonos venga caricato solo sui siti consentiti, filtriamo le richieste in base a un elenco di "domini consentiti". Questo elenco è configurato nel Dashboard. Senza questa configurazione, lo script JS di Zonos restituirà errori di autorizzazione invece di caricarsi correttamente.

Per aggiornare i tuoi domini consentiti:

1. Vai su Dashboard -> Impostazioni -> impostazioni di Checkout.
2. Nella sezione Domini consentiti, aggiungi il/i dominio/i dove integrerai Checkout.
3. Clicca su Salva.

Hello utilizza selettori CSS per identificare gli elementi sul tuo sito che visualizzano informazioni sulla valuta. Dovrai passare questi selettori alla proprietà helloSettings.currencyElementSelector della funzione Zonos.init.

Puoi utilizzare qualsiasi selettore CSS valido qui, ad esempio #price, .price per selezionare più elementi diversi.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Per impostazione predefinita, Hello si aprirà solo quando il visitatore clicca sul pulsante della bandiera. Se desideri aprire automaticamente Hello quando la pagina si carica, puoi chiamare la funzione Zonos.openHelloDialog() una volta che lo script Zonos è stato caricato.

Zonos.init({
  // ... other fields
});

Zonos.openHelloDialog();

Lo script JS di Zonos riconoscerà automaticamente gli acquirenti internazionali e li dirigerà al flusso di Checkout. Tuttavia, dovrai configurare il pulsante 'effettua ordine' sulla tua piattaforma per aprire Checkout quando viene cliccato. Questo può essere fatto passando un selettore CSS alla proprietà checkoutSettings.placeOrderButtonSelector della funzione Zonos.init.

Se hai più pulsanti che possono essere utilizzati per effettuare un ordine, assicurati di passare un selettore che corrisponda a tutti loro. Ad esempio, #placeOrder, .place-order corrisponderà sia a #placeOrder che a .place-order.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

Per visualizzare i dettagli del carrello al cliente, è necessario creare una funzione sul lato server che chiamerà l'API Zonos per creare un carrello e poi restituire quell'ID del carrello al frontend. Questo garantirà che i dettagli del carrello non siano esposti al cliente in un modo che possa essere manipolato.

La tua chiamata API backend utilizzerà un token di credenziale GraphQL segreto, che è diverso dal token pubblico che usi per autenticare lo script JS di Zonos. Questo token può essere recuperato dal Dashboard e deve essere passato come intestazione nella tua chiamata API.

La mutazione createCart accetta un elenco di articoli, che devono essere formattati secondo lo schema dell'elemento del carrello.

// Example cart creation with Node.js
async function createCart(someCartDetails) {
  const response = await fetch('https://api.zonos.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      credentialToken: 'credential_live_xxxxxxxxxx', // Replace with your actual credential token (found in Dashboard)
    },
    body: `
      mutation {
        createCart(input: {
          cart: {
            items: ${JSON.stringify(someCartDetails)}
          }
        }) {
          id
        }
      }
    `,
  });

  const data = await response.json();
  return data.createCart.id; // Return the cart ID to your frontend
}

Suggeriamo di creare un endpoint API sul lato server e poi chiamare quell'endpoint dalla tua integrazione JS frontend, che è dettagliata nel passaggio successivo.

Una volta creato un carrello sul lato server, è necessario passare l'ID del carrello allo script JS di Zonos. Questo può essere fatto utilizzando il callback createCartId che fa parte della funzione Zonos.init. Checkout recupererà quindi in modo sicuro i dettagli del carrello da Zonos quando verrà aperto, prevenendo qualsiasi manomissione del carrello.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch('https://api.merchant.com/api/get-cart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});