Benutzerdefinierte Integration

Das Zonos Elements-Skript ist unter folgender URL verfügbar:

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

Umgang mit Browser-Caching

Wir empfehlen in der Regel auch, einen Zeitstempel oder eine andere eindeutige Kennung an die URL anzuhängen, um sicherzustellen, dass das Skript nicht vom Browser zwischengespeichert wird. Dadurch wird sichergestellt, dass immer die neueste Version des Skripts geladen wird. Zum Beispiel:

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

Sobald Sie das Zonos JS-Skript geladen haben, müssen Sie es authentifizieren, indem Sie einen Zonos API-Schlüssel und die Store-ID in die Zonos.init-Funktion übergeben. Die API-Schlüssel, die zur Authentifizierung des Checkout verwendet werden, sind so konzipiert, dass sie veröffentlichbar sind, was bedeutet, dass sie sicher im Frontend-Code verwendet werden können, ohne sensible Informationen preiszugeben.

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

Um sicherzustellen, dass das Zonos JS-Skript nur auf erlaubten Websites geladen wird, filtern wir Anfragen basierend auf einer Liste von "erlaubten Domains". Diese Liste wird im Dashboard konfiguriert. Ohne diese Konfiguration wird das Zonos JS-Skript Berechtigungsfehler zurückgeben, anstatt ordnungsgemäß geladen zu werden.

Um Ihre erlaubten Domains zu aktualisieren:

1. Gehen Sie zu Dashboard -> Einstellungen -> Checkout Einstellungen.
2. Fügen Sie unter dem Abschnitt Erlaubte Domains die Domain(s) hinzu, auf der Sie Checkout integrieren werden.
3. Klicken Sie auf Speichern.

Hello verwendet CSS-Selektoren, um Elemente auf Ihrer Website zu identifizieren, die Währungsinformationen anzeigen. Sie müssen diese Selektoren an die helloSettings.currencyElementSelector Eigenschaft der Zonos.init Funktion übergeben.

Sie können hier jeden gültigen CSS-Selektor verwenden, z.B. #price, .price, um mehrere verschiedene Elemente auszuwählen.

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

Hello hat die Möglichkeit, nach eingeschränkten Artikeln zu suchen, während der Kunde durchsucht, und sie daran zu hindern, zum Warenkorb hinzugefügt zu werden. Damit dies funktioniert, muss Hello zusätzliche Artikelinformationen wie den Namen und die Beschreibung sowie die Schaltfläche "Zum Warenkorb hinzufügen" kennen. Sie können CSS-Selektoren an Hello übergeben, damit es diese Informationen von der Seite abrufen kann.

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

Standardmäßig wird Hello nur geöffnet, wenn der Besucher auf die Flagge klickt. Wenn Sie möchten, dass Hello automatisch geöffnet wird, wenn die Seite geladen wird, können Sie die Funktion Zonos.openHelloDialog() aufrufen, sobald das Zonos-Skript geladen wurde.

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

Zonos.openHelloDialog();

Das Zonos JS-Skript erkennt automatisch internationale Käufer und leitet sie zum Checkout-Ablauf weiter. Sie müssen jedoch die Schaltfläche "Bestellung aufgeben" auf Ihrer Plattform konfigurieren, um Checkout zu öffnen, wenn darauf geklickt wird. Dies kann erfolgen, indem Sie einen CSS-Selektor an die checkoutSettings.placeOrderButtonSelector-Eigenschaft der Zonos.init-Funktion übergeben.

Wenn Sie mehrere Schaltflächen haben, die zum Aufgeben einer Bestellung verwendet werden können, stellen Sie sicher, dass Sie einen Selektor übergeben, der allen entspricht. Zum Beispiel wird #placeOrder, .place-order sowohl zu #placeOrder als auch zu .place-order passen.

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

Der buildCartDetail-Rückruf ist dafür verantwortlich, Warenkorbdetails in einem Format zurückzugeben, das die Benutzeroberfläche von Checkout verstehen und anzeigen kann. Diese Funktion wird aufgerufen, sobald der Kunde die checkout-Seite erreicht, um sicherzustellen, dass die Warenkorbdetails auf der ersten Seite von Checkout korrekt angezeigt werden. Bitte beachten Sie, dass dies nicht für Berechnungen verwendet wird - diese werden im nächsten Schritt durchgeführt.

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

Schema des Warenkorbartikels

Die Funktion buildCartDetail sollte ein Array von Warenkorbartikeln zurückgeben. Unten ist eine Tabelle, die die Struktur jedes CartItem-Objekts beschreibt:

Die Funktion buildLandedCost kümmert sich um die sichere Berechnung der landed cost. Sie wird aufgerufen, nachdem der Kunde seine Versandinformationen eingegeben hat. Diese Funktion berechnet die Versandkosten und andere notwendige Kosten, die dann auf der nächsten Seite von Checkout angezeigt werden.

Es ist wichtig, dass Sie die Berechnungslogik der landed cost serverseitig handhaben, da dies der einzige Weg ist, um sicherzustellen, dass die Warenkorbdaten nicht im Browser des Kunden offengelegt werden. Wenn Sie eine serverlose Architektur verwenden, können Sie eine serverlose Funktion nutzen, um die Berechnung der landed cost durchzuführen. Die Funktion buildLandedCost sollte einfach die serverlose Funktion/API-Endpunkt aufrufen und das Ergebnis zurückgeben.

Auf der Serverseite können Sie die Zonos Checkout API verwenden, um die landed cost mit der folgenden POST-Anfrage zu berechnen. Sie müssen den API-Schlüssel, den Sie für das Zonos JS-Skript verwendet haben, im credentialToken-Header übergeben.

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