Intégration personnalisée

Le script Zonos Elements est disponible à l'URL suivante :

<script src="https://js.zonos.com/dist/scripts/loadZonos.js" />

Gestion de la mise en cache du navigateur

Nous recommandons également généralement d'ajouter un horodatage ou un autre identifiant unique à l'URL pour garantir que le script ne soit pas mis en cache par le navigateur. Cela garantira que la dernière version du script est toujours chargée. Par exemple:

<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>

Une fois que vous avez chargé le script JS de Zonos, vous devez l'authentifier en passant une Zonos clé API et l'ID du magasin dans la fonction Zonos.init. Les clés API utilisées pour authentifier Checkout sont conçues pour être publiables, ce qui signifie qu'elles peuvent être utilisées en toute sécurité dans le code frontend sans exposer d'informations sensibles.

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

Afin de s'assurer que le script JS de Zonos ne soit chargé que sur les sites autorisés, nous filtrons les demandes en fonction d'une liste de "domaines autorisés". Cette liste est configurée dans le Dashboard. Sans cette configuration, le script JS de Zonos renverra des erreurs de permission au lieu de se charger correctement.

Pour mettre à jour vos domaines autorisés :

1. Allez dans Dashboard -> Paramètres -> Paramètres de Checkout.
2. Dans la section Domaines autorisés, ajoutez le(s) domaine(s) où vous intégrerez Checkout.
3. Cliquez sur Enregistrer.

Hello utilise des sélecteurs CSS pour identifier les éléments de votre site qui affichent des informations sur les devises. Vous devrez passer ces sélecteurs à la propriété helloSettings.currencyElementSelector de la fonction Zonos.init.

Vous pouvez utiliser n'importe quel sélecteur CSS valide ici, par exemple #price, .price pour sélectionner plusieurs éléments différents.

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

Hello a la capacité de vérifier les articles restreints lorsque l'acheteur navigue et de les empêcher d'être ajoutés au panier. Pour que cela fonctionne, Hello a besoin de connaître des informations supplémentaires sur l'article telles que le nom et la description, ainsi que le "bouton ajouter au panier". Vous pouvez transmettre des sélecteurs CSS à Hello pour lui permettre de récupérer ces informations de la page.

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

Par défaut, Hello ne s'ouvrira que lorsque le visiteur cliquera sur le bouton du drapeau. Si vous souhaitez ouvrir automatiquement Hello lorsque la page se charge, vous pouvez appeler la fonction Zonos.openHelloDialog() une fois que le script Zonos a été chargé.

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

Zonos.openHelloDialog();

Le script Zonos JS reconnaîtra automatiquement les acheteurs internationaux et les dirigera vers le flux de Checkout. Cependant, vous devrez configurer le bouton 'passer la commande' sur votre plateforme pour ouvrir Checkout lorsqu'il est cliqué. Cela peut être fait en passant un sélecteur CSS à la propriété checkoutSettings.placeOrderButtonSelector de la fonction Zonos.init.

Si vous avez plusieurs boutons qui peuvent être utilisés pour passer une commande, assurez-vous de passer un sélecteur qui les correspondra tous. Par exemple, #placeOrder, .place-order correspondra à la fois à #placeOrder et .place-order.

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

La fonction buildCartDetail est responsable de renvoyer les détails du panier dans un format que l'interface Checkout peut comprendre et afficher. Cette fonction est appelée dès que le client arrive sur la page de checkout, garantissant que les détails du panier sont affichés correctement sur la première page de Checkout. Veuillez noter que cela n'est pas utilisé pour les calculs - cela est géré à l'étape suivante.

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

Schéma de l'article du panier

La fonction buildCartDetail doit retourner un tableau d'articles du panier. Ci-dessous se trouve un tableau détaillant la structure de chaque objet CartItem :

La fonction buildLandedCost gère le calcul sécurisé du landed cost. Elle est invoquée après que le client a saisi ses informations de livraison. Cette fonction calcule les frais d'expédition et autres coûts nécessaires, qui sont ensuite affichés sur la page suivante de Checkout.

Il est important de gérer la logique de calcul du landed cost côté serveur, car c'est le seul moyen de garantir que les détails du panier ne sont pas exposés au navigateur du client. Si vous utilisez une architecture sans serveur, vous pouvez utiliser une fonction sans serveur pour gérer le calcul du landed cost. La fonction buildLandedCost doit simplement appeler la fonction sans serveur/point de terminaison API et retourner le résultat.

Côté serveur, vous pouvez utiliser l'API Zonos Checkout pour calculer le landed cost en utilisant la requête POST suivante. Vous devrez passer la clé API que vous utilisez pour le script JS de Zonos dans l'en-tête 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
    },
  },
});