DOCS

Tilpasset integrasjon

Logg inn
Bestill en demo
Checkout•
HjemGlobal e-handel Integrasjon Integrere Checkout Tilpasset integrasjon

Tilpasset integrasjon

Bygg en ende-til-ende Checkout integrasjon inn i ditt tilpassede nettsted.

Denne guiden dekker de tekniske aspektene ved å fullføre en full integrasjon av Zonos Checkout inn i ditt tilpassede nettsted eller plattform. Den er ment for utviklere som er komfortable med å jobbe med JavaScript og har erfaring med frontend-utvikling. Alle trinn er nødvendige med mindre annet er notert.

Forutsetninger


Installer Zonos JS-skriptet 

Din tilpassede integrasjon må inkludere Zonos JavaScript-snippet. Dette skriptet er ansvarlig for å gjengi Checkout UI, Zonos Hello, håndtere betalingsbehandling og håndtere besøkendes geo-IP-detektering.

1

Installer Zonos JS-snippet

Zonos Elements-skriptet er tilgjengelig på følgende URL:

Zonos JS-snippet

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

Håndtering av nettleserbuffer

Vi anbefaler også vanligvis å legge til et tidsstempel eller en annen unik identifikator til URL-en for å sikre at skriptet ikke blir bufret av nettleseren. Dette vil sikre at den nyeste versjonen av skriptet alltid lastes inn. For eksempel:

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

Autentiser Zonos JS-snippetet

Når du har lastet inn Zonos JS-skriptet, må du autentisere det ved å sende en Zonos API-nøkkel og butikk-ID inn i Zonos.init funksjonen. API-nøklene som brukes til å autentisere Checkout er designet for å være publiserbare, noe som betyr at de trygt kan brukes i frontend-kode uten å eksponere sensitiv informasjon.

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

Angi tillatte domener

For å sikre at Zonos JS-skriptet kun lastes inn på tillatte nettsteder, filtrerer vi forespørslene basert på en liste over "tillatte domener". Denne listen konfigureres i Dashboard. Uten denne konfigurasjonen vil Zonos JS-skriptet returnere tillatelsesfeil i stedet for å lastes inn riktig.

For å oppdatere dine tillatte domener:

  1. Gå til Dashboard -> Innstillinger -> Checkout innstillinger.
  2. Under Tillatte domener-seksjonen, legg til domenet/domenene der du vil integrere Checkout.
  3. Klikk Lagre.

Sett opp Zonos Hello 

Når du har satt opp Zonos JS-skriptet, må du konfigurere Hello for å fungere med nettstedet ditt. Hello er ansvarlig for å oppdage besøkendes plassering, språk og valuta, og vise den passende informasjonen til dem. Hello er nødvendig når du bruker Checkout.

Du kan konfigurere alle Hello-innstillinger både i Dashboard og i Zonos JS-skriptet. Hvis du allerede har konfigurert Hello i Dashboard, vil skriptet laste inn disse innstillingene og bruke dem. Hvis du spesifiserer noen verdier i helloSettings-egenskapen til Zonos.init-funksjonen, vil skriptet bruke disse verdiene i stedet.

1

Konfigurer valutakonvertering

Hello bruker CSS-selektorer for å identifisere elementer på nettstedet ditt som viser valutainformasjon. Du må sende disse selektorene til helloSettings.currencyElementSelector-egenskapen til Zonos.init-funksjonen.

Du kan bruke hvilken som helst gyldig CSS-selektor her, for eksempel #price, .price for å velge flere forskjellige elementer.

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

Valgfritt — Åpne automatisk Hello ved sideinnlasting

Som standard vil Hello kun åpne når besøkende klikker på flaggknappen. Hvis du ønsker å åpne Hello automatisk når siden lastes, kan du kalle Zonos.openHelloDialog()-funksjonen når Zonos-skriptet har lastet inn.

Zonos JS-snutt

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

Sett opp Zonos Checkout 

Når Hello er konfigurert, må du sette opp Checkout for å fungere med nettstedet ditt. Checkout er ansvarlig for å la kunden angi sin fraktinformasjon, beregne landed cost, og fullføre bestillingen.

Checkout vil dele kontekstuell data med Hello, som for eksempel besøkendes plassering, språk og valuta. Dette sikrer at kundens opplevelse er konsistent gjennom hele handleprosessen.

Du kan konfigurere alle Checkout-innstillinger både i Dashboard og i Zonos JS-skriptet. Hvis du allerede har konfigurert Checkout i Dashboard, vil skriptet laste disse innstillingene og bruke dem. Hvis du spesifiserer noen verdier i checkoutSettings-egenskapen til Zonos.init-funksjonen, vil skriptet bruke disse verdiene i stedet.

1

Konfigurer 'plasser ordre'-knappen

Zonos JS-skriptet vil automatisk gjenkjenne internasjonale kunder og lede dem til Checkout-flyten. Du må imidlertid konfigurere 'plasser ordre'-knappen på plattformen din for å åpne Checkout når den klikkes. Dette kan gjøres ved å sende en CSS-velger til checkoutSettings.placeOrderButtonSelector-egenskapen til Zonos.init-funksjonen.

Hvis du har flere knapper som kan brukes til å plassere en ordre, må du sørge for å sende inn en velger som vil matche alle sammen. For eksempel, #placeOrder, .place-order vil matche både #placeOrder og .place-order.

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

Sikker oppretting av handlekurvdetaljer på serversiden

For å vise handlekurvdetaljene til kunden, må du opprette en serverside funksjon som vil kalle Zonos API-et for å opprette en handlekurv, og deretter sende den handlekurv-ID-en tilbake til frontend. Dette vil sikre at handlekurvdetaljene ikke blir eksponert for kunden på en måte som kan manipuleres.

API-anropet ditt på backend vil bruke en hemmelig GraphQL-legitimasjonstoken, som er forskjellig fra den offentlige tokenen som du bruker for å autentisere Zonos JS-skriptet. Denne tokenen kan hentes i Dashboard -> Innstillinger -> Integrasjoner. Den hemmelige tokenen må sendes som en header i API-anropet ditt.

cartCreate mutasjonen aksepterer en liste over varer, som bør formateres i henhold til handlekurvvare-skjemaet.

Eksempel på oppretting av handlekurv på serversiden

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
}

Vi foreslår å opprette et API-endepunkt på server-siden din og deretter kalle det endepunktet fra frontend JS-integrasjonen din, som er detaljert i neste trinn.

3

Send handlekurv-ID til Checkout via frontend

Når du har opprettet en handlekurv på server-siden din, må du sende handlekurv-ID-en til Zonos JS-skriptet. Dette kan gjøres ved å bruke createCartId callback som er en del av Zonos.init funksjonen. Checkout vil deretter sikkert hente handlekurvdetaljene fra Zonos når den åpnes, og forhindre enhver manipulering med handlekurven.

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

Var denne siden nyttig?

Bestill en demo

Spørsmål?

Få støtte
© 2025 Zonoszonos.com
På denne siden:
  • Tilpasset integrasjon
  • Installer Zonos JS-skriptet
  • Sett opp Zonos Hello
  • Sett opp Zonos Checkout