DOCS

Benutzerdefinierte Integration

Anmelden
Eine Demo buchen
Checkout•
StartseiteGlobaler E-Commerce Integration Integrieren Sie Checkout Benutzerdefinierte Integration

Benutzerdefinierte Integration

Bauen Sie eine End-to-End Checkout-Integration in Ihre benutzerdefinierte Website ein.

Dieser Leitfaden behandelt die technischen Aspekte der vollständigen Integration von Zonos Checkout in Ihre benutzerdefinierte Website oder Plattform. Er richtet sich an Entwickler, die mit JavaScript vertraut sind und Erfahrung in der Frontend-Entwicklung haben. Alle Schritte sind erforderlich, es sei denn, es wird anders angegeben.

Voraussetzungen


Installieren Sie das Zonos JS-Skript 

Ihre benutzerdefinierte Integration muss den Zonos JavaScript-Snippet enthalten. Dieses Skript ist verantwortlich für das Rendern der Checkout-UI, Zonos Hello, die Zahlungsabwicklung und die Geo-IP-Erkennung der Besucher.

1

Installieren Sie den Zonos JS-Snippet

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

Zonos JS-Snippet

1
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/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:

Zonos JS-Schnipsel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<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>
2

Authentifizieren Sie das Zonos JS-Snippet

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

1
2
3
4
5
6
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
});
3

Erlaubte Domains festlegen

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.

Einrichten von Zonos Hello 

Nachdem Sie das Zonos JS-Skript eingerichtet haben, müssen Sie Hello konfigurieren, um mit Ihrer Website zu funktionieren. Hello ist dafür verantwortlich, den Standort, die Sprache und die Währung des Besuchers zu erkennen und die entsprechenden Informationen anzuzeigen. Hello wird benötigt, wenn Sie Checkout verwenden.

Sie können alle Hello Einstellungen sowohl im Dashboard als auch im Zonos JS-Skript konfigurieren. Wenn Sie Hello bereits im Dashboard konfiguriert haben, lädt das Skript diese Einstellungen und verwendet sie. Wenn Sie Werte in der helloSettings Eigenschaft der Zonos.init Funktion angeben, verwendet das Skript stattdessen diese Werte.

1

Währungsumrechnung konfigurieren

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

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Optional — Automatisches Öffnen von Hello beim Laden der Seite

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

1
2
3
4
5
6
7
8
9
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Einrichten von Zonos Checkout 

Sobald Hello konfiguriert wurde, müssen Sie Checkout einrichten, um mit Ihrer Website zu funktionieren. Checkout ist dafür verantwortlich, es dem Kunden zu ermöglichen, seine Versandinformationen einzugeben, die landed cost zu berechnen und die Bestellung abzuschließen.

Checkout wird kontextbezogene Daten mit Hello teilen, wie z.B. den Standort, die Sprache und die Währung des Besuchers. Dies stellt sicher, dass die Erfahrung des Kunden während des gesamten Einkaufsprozesses konsistent ist.

Sie können alle Checkout-Einstellungen sowohl im Dashboard als auch im Zonos JS-Skript konfigurieren. Wenn Sie Checkout bereits im Dashboard konfiguriert haben, lädt das Skript diese Einstellungen und verwendet sie. Wenn Sie Werte im checkoutSettings-Eigenschaft des Zonos.init-Funktion angeben, verwendet das Skript stattdessen diese Werte.

1

Konfigurieren Sie die Schaltfläche "Bestellung aufgeben"

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

1
2
3
4
5
6
7
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});
2

Sicheres Erstellen von Warenkorbdaten auf der Serverseite

Um die Warenkorbdaten dem Kunden anzuzeigen, müssen Sie eine serverseitige Funktion erstellen, die die Zonos API aufruft, um einen Warenkorb zu erstellen, und dann diese Warenkorb-ID an Ihr Frontend zurückgibt. Dies stellt sicher, dass die Warenkorbdaten dem Kunden nicht in einer Weise angezeigt werden, die manipuliert werden kann.

Ihr Backend-API-Aufruf verwendet ein geheimes GraphQL-Anmeldeinformationstoken, das sich von dem öffentlichen Token unterscheidet, das Sie zur Authentifizierung des Zonos JS-Skripts verwenden. Dieses Token kann in Dashboard -> Einstellungen -> Integrationen abgerufen werden. Das geheime Token muss als Header in Ihrem API-Aufruf übergeben werden.

Die cartCreate Mutation akzeptiert eine Liste von Artikeln, die gemäß dem Warenkorb-Artikel-Schema formatiert sein sollten.

Beispiel für die Erstellung eines Warenkorbs auf der Serverseite

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
// 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
}

Wir empfehlen, einen API-Endpunkt auf Ihrer Server-Seite zu erstellen und diesen Endpunkt dann von Ihrer Frontend-JS-Integration aus aufzurufen, was im nächsten Schritt detailliert beschrieben wird.

3

Übergeben Sie die Warenkorb-ID an Checkout über das Frontend

Sobald Sie einen Warenkorb auf Ihrer Server-Seite erstellt haben, müssen Sie die Warenkorb-ID an das Zonos JS-Skript übergeben. Dies kann durch die Verwendung des createCartId-Callbacks erfolgen, das Teil der Zonos.init-Funktion ist. Checkout wird dann sicher die Warenkorbdaten von Zonos abrufen, wenn es geöffnet wird, um eine Manipulation des Warenkorbs zu verhindern.

Zonos JS-Snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
    },
  },
});

War diese Seite hilfreich?

Eine Demo buchen
© 2025 Zonoszonos.com
Auf dieser Seite:
  • Benutzerdefinierte Integration
  • Installieren Sie das Zonos JS-Skript
  • Einrichten von Zonos Hello
  • Einrichten von Zonos Checkout