DOCS

Aangepaste integratie

Checkout•
HomeWereldwijde e-commerce Integratie Integreer Checkout Aangepaste integratie

Aangepaste integratie

Bouw een end-to-end Checkout integratie in uw aangepaste site.

Deze gids behandelt de technische aspecten van het voltooien van een volledige integratie van Zonos Checkout in uw aangepaste site of platform. Het is bedoeld voor ontwikkelaars die comfortabel zijn met het werken met JavaScript en ervaring hebben met frontend-ontwikkeling. Alle stappen zijn vereist, tenzij anders vermeld.

Vereisten


Installeer het Zonos JS-script 

Uw aangepaste integratie moet het Zonos JavaScript-fragment bevatten. Dit script is verantwoordelijk voor het weergeven van de Checkout UI, Zonos Hello, het verwerken van betalingen en het afhandelen van geo-IP-detectie van bezoekers.

1

Installeer het Zonos JS-fragment

Het Zonos Elements-script is beschikbaar op de volgende URL:

Zonos JS-fragment

1
<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />

Omgaan met browsercaching

We raden ook meestal aan om een tijdstempel of een andere unieke identifier aan de URL toe te voegen om ervoor te zorgen dat het script niet door de browser wordt gecached. Dit zorgt ervoor dat de nieuwste versie van het script altijd wordt geladen. Bijvoorbeeld:

Zonos JS snippet

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

Authenticeer de Zonos JS snippet

Zodra je de Zonos JS-script hebt geladen, moet je deze authentiseren door een Zonos API-sleutel en store ID door te geven aan de Zonos.init functie. De API-sleutels die worden gebruikt om Checkout te authentiseren, zijn ontworpen om publiceerbaar te zijn, wat betekent dat ze veilig kunnen worden gebruikt in frontendcode zonder gevoelige informatie bloot te stellen.

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

Stel toegestane domeinen in

Om ervoor te zorgen dat het Zonos JS-script alleen op toegestane sites wordt geladen, filteren we verzoeken op basis van een lijst van "toegestane domeinen". Deze lijst wordt geconfigureerd in het Dashboard. Zonder deze configuratie zal het Zonos JS-script toestemmingsfouten retourneren in plaats van correct te laden.

Om uw toegestane domeinen bij te werken:

  1. Ga naar Dashboard -> Instellingen -> Checkout instellingen.
  2. Voeg onder de sectie Toegestane domeinen het domein of de domeinen toe waar u Checkout zult integreren.
  3. Klik op Opslaan.

Stel Zonos Hello in 

Zodra u het Zonos JS-script hebt ingesteld, moet u Hello configureren om met uw site te werken. Hello is verantwoordelijk voor het detecteren van de locatie, taal en valuta van de bezoeker en het weergeven van de juiste informatie aan hen. Hello is vereist bij het gebruik van Checkout.

U kunt alle instellingen van Hello zowel in het Dashboard als in het Zonos JS-script configureren. Als u Hello al in het Dashboard hebt geconfigureerd, zal het script die instellingen laden en gebruiken. Als u waarden opgeeft in de helloSettings-eigenschap van de Zonos.init functie, zal het script die waarden in plaats daarvan gebruiken.

1

Configureer valutaconversie

Hello gebruikt CSS-selectors om elementen op uw site te identificeren die valutainformatie weergeven. U moet deze selectors doorgeven aan de helloSettings.currencyElementSelector-eigenschap van de Zonos.init functie.

U kunt hier elke geldige CSS-selector gebruiken, bijvoorbeeld #price, .price om meerdere verschillende elementen te selecteren.

Zonos JS snippet

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

Optioneel — Open Hello automatisch bij het laden van de pagina

Standaard zal Hello alleen openen wanneer de bezoeker op de vlagknop klikt. Als u Hello automatisch wilt openen wanneer de pagina laadt, kunt u de Zonos.openHelloDialog() functie aanroepen zodra het Zonos script is geladen.

Zonos JS snippet

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

Stel Zonos Checkout in 

Zodra Hello is geconfigureerd, moet je Checkout instellen om met je site te werken. Checkout is verantwoordelijk voor het toestaan dat de klant zijn verzendinformatie invoert, landed cost berekent en de bestelling voltooit.

Checkout zal contextuele gegevens delen met Hello, zoals de locatie van de bezoeker, taal en valuta. Dit zorgt ervoor dat de ervaring van de klant consistent is gedurende het hele winkelproces.

Je kunt alle instellingen van Checkout configureren in zowel het Dashboard als het Zonos JS-script. Als je Checkout al in het Dashboard hebt geconfigureerd, zal het script die instellingen laden en gebruiken. Als je waarden opgeeft in de checkoutSettings eigenschap van de Zonos.init functie, zal het script die waarden in plaats daarvan gebruiken.

1

Configureer de 'plaats bestelling' knop

Het Zonos JS-script zal automatisch internationale shoppers herkennen en hen naar de Checkout flow leiden. Je moet echter de 'plaats bestelling' knop op je platform configureren om Checkout te openen wanneer erop wordt geklikt. Dit kan worden gedaan door een CSS-selector door te geven aan de checkoutSettings.placeOrderButtonSelector eigenschap van de Zonos.init functie.

Als je meerdere knoppen hebt die kunnen worden gebruikt om een bestelling te plaatsen, zorg er dan voor dat je een selector doorgeeft die op allemaal overeenkomt. Bijvoorbeeld, #placeOrder, .place-order zal zowel #placeOrder als .place-order overeenkomen.

Zonos JS snippet

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

Maak veilig winkelwagentijdetails aan op de serverzijde

Om de winkelwagentijdetails aan de klant weer te geven, moet je een serverzijde functie maken die de Zonos API aanroept om een winkelwagentje te creëren, en vervolgens die winkelwagentje-ID terug naar je frontend doorgeven. Dit zorgt ervoor dat de winkelwagentijdetails niet op een manier aan de klant worden blootgesteld die kan worden gemanipuleerd.

Je backend API-aanroep zal een geheim GraphQL-credentialtoken gebruiken, dat verschilt van de publieke token die je gebruikt om het Zonos JS-script te authenticeren. Dit token kan worden opgehaald in Dashboard -> Instellingen -> Integraties. Het geheime token moet als een header in je API-aanroep worden doorgegeven.

De cartCreate mutatie accepteert een lijst van items, die moet worden opgemaakt volgens het winkelwagentijde schema.

Voorbeeld van het aanmaken van een winkelwagentje op de serverzijde

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
}

We raden aan om een API-eindpunt op uw serverzijde te creëren en dat eindpunt vervolgens aan te roepen vanuit uw frontend JS-integratie, wat in de volgende stap wordt toegelicht.

3

Geef cart ID door aan Checkout via frontend

Zodra u een winkelwagentje op uw serverzijde heeft aangemaakt, moet u de cart ID doorgeven aan het Zonos JS-script. Dit kan worden gedaan door de createCartId callback te gebruiken, die deel uitmaakt van de Zonos.init functie. Checkout zal vervolgens veilig de cart-gegevens ophalen van Zonos wanneer deze wordt geopend, waardoor elke manipulatie van de cart wordt voorkomen.

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

Was deze pagina nuttig?

Boek een demo
© 2025 Zonoszonos.com
Op deze pagina:
  • Aangepaste integratie
  • Installeer het Zonos JS-script
  • Stel Zonos Hello in
  • Stel Zonos Checkout in