Integrazione personalizzata

Lo script Elements di Zonos è disponibile al seguente URL:

<script src="https://js.zonos.com/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://js.zonos.com/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://js.zonos.com/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
  },
});

Hello ha la capacità di controllare gli articoli vietati mentre lo shopper naviga e di impedire che vengano aggiunti al carrello. Affinché questo funzioni, Hello deve conoscere informazioni aggiuntive sugli articoli, come il nome e la descrizione, oltre al "pulsante aggiungi al carrello". Puoi passare selettori CSS a Hello per consentirgli di estrarre queste informazioni dalla pagina.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    productAddToCartElementSelector: '.add-to-cart',
    productDescriptionElementSelector: '.description',
    productPriceElementSelector: '.price',
    productTitleElementSelector: '.title',
  },
});

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)
  },
});

Il callback buildCartDetail è responsabile del ritorno dei dettagli del carrello in un formato che l'interfaccia Checkout può comprendere e visualizzare. Questa funzione viene chiamata non appena il cliente arriva alla pagina checkout, assicurando che i dettagli del carrello vengano visualizzati accuratamente nella prima pagina di Checkout. Si prega di notare che questo non viene utilizzato per i calcoli - ciò è gestito nel passaggio successivo.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildCartDetail: async () => {
      // ... Your existing buildCartDetail implementation
      // This should return cart details for UI display
    },
  },
});

Schema dell'elemento del carrello

La funzione buildCartDetail dovrebbe restituire un array di elementi del carrello. Di seguito è riportata una tabella che dettaglia la struttura di ciascun oggetto CartItem:

La funzione buildLandedCost gestisce il calcolo sicuro del landed cost. Viene invocata dopo che il cliente inserisce le proprie informazioni di spedizione. Questa funzione calcola le tariffe di spedizione e altri costi necessari, che vengono poi visualizzati nella pagina successiva di Checkout.

È importante che tu gestisca la logica di calcolo del landed cost sul lato server, poiché questo è l'unico modo per garantire che i dettagli del carrello non siano esposti al browser del cliente. Se stai utilizzando un'architettura serverless, puoi utilizzare una funzione serverless per gestire il calcolo del landed cost. La funzione buildLandedCost dovrebbe semplicemente chiamare la funzione serverless/l'endpoint API e restituire il risultato.

Sul lato server, puoi utilizzare l'API di Zonos Checkout per calcolare il landed cost utilizzando la seguente richiesta POST. Dovrai passare la chiave API che hai utilizzato per lo script JS di Zonos nell'intestazione credentialToken.

https://v1.route.js.zonos.com/api/zonos-elements/calculate-landed-cost

{
  "billingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  },
  "billingContact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "checkoutSessionId": "xyz789",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44-20-7946-0958"
  },
  "items": [
    {
      "amount": 150,
      "currencyCode": "USD",
      "name": "Product Name",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "addressLine1": "789 King Street",
    "city": "London",
    "country": "GB",
    "postalCode": "SW1A 1AA",
    "state": "England"
  }
}

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // This should return the landed cost calculation
    },
  },
});