Installez le script JS de Zonos
Votre intégration personnalisée devra inclure le snippet JavaScript de Zonos. Ce script est responsable du rendu de l'interface utilisateur Checkout, de Zonos Hello, du traitement des paiements et de la détection géo-IP des visiteurs.
Installez le snippet JS de Zonos
Le script Zonos Elements est disponible à l'URL suivante :
Zonos JS snippet
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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:
Zonos Extrait JS
<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>
Authentifier le snippet JS de Zonos
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 snippet JS
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
});
Définir les domaines autorisés
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 :
- Allez dans Dashboard -> Paramètres -> Paramètres de Checkout.
- Dans la section Domaines autorisés, ajoutez le(s) domaine(s) où vous intégrerez Checkout.
- Cliquez sur Enregistrer.
Configurer Zonos Hello
Une fois que vous avez configuré le script JS de Zonos, vous devez configurer Hello pour qu'il fonctionne avec votre site. Hello est responsable de détecter la localisation, la langue et la devise du visiteur, et d'afficher les informations appropriées. Hello est requis lors de l'utilisation de Checkout.
Vous pouvez configurer tous les paramètres de Hello à la fois dans le Dashboard et dans le script JS de Zonos. Si vous avez déjà configuré Hello dans le Dashboard, le script chargera ces paramètres et les utilisera. Si vous spécifiez des valeurs dans la propriété helloSettings de la fonction Zonos.init, le script utilisera ces valeurs à la place.
Configurer la conversion de devise
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 JS snippet
Zonos.init({
// ... other fields
helloSettings: {
// ... other fields
currencyElementSelector: '#price, .price', // Replace with your actual selector
},
});
Optionnel — Ouvrir automatiquement Hello lors du chargement de la page
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 Extrait JS
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
Configurer Zonos Checkout
Une fois que Hello a été configuré, vous devez configurer Checkout pour qu'il fonctionne avec votre site. Checkout est responsable de permettre au client de saisir ses informations de livraison, de calculer le landed cost, et de finaliser la commande.
Checkout partagera des données contextuelles avec Hello, telles que la localisation du visiteur, la langue et la devise. Cela garantit que l'expérience du client est cohérente tout au long du processus d'achat.
Vous pouvez configurer tous les paramètres de Checkout à la fois dans le Dashboard et dans le script Zonos JS. Si vous avez déjà configuré Checkout dans le Dashboard, le script chargera ces paramètres et les utilisera. Si vous spécifiez des valeurs dans la propriété checkoutSettings de la fonction Zonos.init, le script utilisera ces valeurs à la place.
Configurer le bouton 'passer la commande'
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 JS snippet
Zonos.init({
// ... other fields
checkoutSettings: {
// ... other fields
placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
},
});
Créer en toute sécurité les détails du panier côté serveur
Pour afficher les détails du panier au client, vous devez créer une fonction côté serveur qui appellera l'API Zonos pour créer un panier, puis renvoyer cet ID de panier à votre frontend. Cela garantira que les détails du panier ne sont pas exposés au client d'une manière qui peut être manipulée.
Votre appel API backend utilisera un jeton d'identification GraphQL secret, qui est différent du jeton public que vous utilisez pour authentifier le script JS Zonos. Ce jeton peut être récupéré dans Dashboard -> Settings -> Integrations. Le jeton secret doit être passé en tant qu'en-tête dans votre appel API.
La mutation cartCreate accepte une liste d'articles, qui doit être formatée selon le schéma d'élément de panier.
Exemple de création de panier côté serveur
// Create new cart from serverside
async function createCart() {
/**
* Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
* */
const graphql = JSON.stringify({
query: `
mutation cartCreate($input: CartCreateInput!){
cartCreate(input: $input) {
id
adjustments {
amount
currencyCode
description
productId
sku
type
}
items {
id
name
amount
currencyCode
quantity
sku
description
metadata {
key
value
}
}
metadata {
key
value
}
}
}`,
variables: {
/**
* input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
*/
input: {
/**
* Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
*/
adjustments: [
{
amount: -10,
currencyCode: 'USD',
/**
* Enum value: https://zonos.com/developer/types/CartAdjustmentType
*/
type: 'CART_TOTAL',
},
],
/**
* Cart item input: https://zonos.com/developer/types/ItemInput
*/
items: [
{
name: 'Item 1',
amount: 150.99,
currencyCode: 'USD',
description: 'Item 1 description',
quantity: 2,
},
],
/**
* Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
*/
metadata: [
{
key: 'key1',
value: 'value1',
},
],
},
},
});
const response = await fetch('https://api.zonos.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
credentialToken: 'credential_live_xxxxxxxxx', // Replace with your actual SECRET credential token (found in Dashboard)
},
body: graphql,
});
const { data } = await response.json();
return data.cartCreate.id; // Return the cart ID to your frontend
}
Nous vous suggérons de créer un point de terminaison API sur votre serveur et ensuite d'appeler ce point de terminaison depuis votre intégration JS côté frontend, ce qui est détaillé dans l'étape suivante.
Passer l'ID du panier à Checkout via le frontend
Une fois que vous avez créé un panier sur votre serveur, vous devez passer l'ID du panier au script JS de Zonos. Cela peut être fait en utilisant le rappel createCartId qui fait partie de la fonction Zonos.init. Checkout récupérera alors en toute sécurité les détails du panier depuis Zonos lorsqu'il sera ouvert, empêchant toute falsification du panier.
Zonos JS snippet
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
},
},
});
Intégration personnalisée
Construisez une intégration Checkout de bout en bout dans votre site personnalisé.
Ce guide couvre les aspects techniques de l'intégration complète de Zonos Checkout dans votre site ou plateforme personnalisée. Il est destiné aux développeurs qui sont à l'aise avec JavaScript et ont de l'expérience en développement frontend. Toutes les étapes sont requises, sauf indication contraire.
Prérequis