DOCS

Niestandardowa integracja

Checkout•
DomGlobalny e-commerce Integracja Zintegruj Checkout Niestandardowa integracja

Niestandardowa integracja

Zbuduj kompleksową integrację Checkout w swojej niestandardowej witrynie.

Ten przewodnik obejmuje aspekty techniczne zakończenia pełnej integracji Zonos Checkout w Twojej niestandardowej witrynie lub platformie. Jest przeznaczony dla programistów, którzy czują się komfortowo w pracy z JavaScript i mają doświadczenie w rozwoju frontendowym. Wszystkie kroki są wymagane, chyba że zaznaczone jest inaczej.

Wymagania wstępne


Zainstaluj skrypt JS Zonos 

Twoja niestandardowa integracja będzie musiała zawierać fragment JavaScript Zonos. Ten skrypt odpowiada za renderowanie interfejsu użytkownika Checkout, Zonos Hello, obsługę przetwarzania płatności oraz wykrywanie geolokalizacji odwiedzających.

1

Zainstaluj fragment JS Zonos

Skrypt Zonos Elements jest dostępny pod następującym adresem URL:

Zonos JS snippet

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

Obsługa pamięci podręcznej przeglądarki

Zazwyczaj zalecamy również dodanie znacznika czasu lub innego unikalnego identyfikatora do adresu URL, aby upewnić się, że skrypt nie jest buforowany przez przeglądarkę. To zapewni, że zawsze ładowana jest najnowsza wersja skryptu. Na przykład:

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

Uwierzytelnij Zonos JS snippet

Po załadowaniu skryptu JS Zonos musisz go uwierzytelnić, przekazując klucz API Zonos oraz identyfikator magazynu do funkcji Zonos.init. Klucze API używane do uwierzytelniania Checkout są zaprojektowane jako publikowalne, co oznacza, że mogą być bezpiecznie używane w kodzie frontendowym bez ujawniania jakichkolwiek wrażliwych informacji.

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

Ustaw dozwolone domeny

Aby zapewnić, że skrypt JS Zonos jest ładowany tylko na dozwolonych stronach, filtrujemy żądania na podstawie listy "dozwolonych domen". Ta lista jest konfigurowana w Dashboard. Bez tej konfiguracji skrypt JS Zonos zwróci błędy uprawnień zamiast ładować się poprawnie.

Aby zaktualizować swoje dozwolone domeny:

  1. Przejdź do Dashboard -> Ustawienia -> ustawienia Checkout.
  2. W sekcji Dozwolone domeny dodaj domenę(y), na których będziesz integrować Checkout.
  3. Kliknij Zapisz.

Skonfiguruj Zonos Hello 

Gdy skonfigurujesz skrypt JS Zonos, musisz skonfigurować Hello, aby działał z Twoją stroną. Hello jest odpowiedzialny za wykrywanie lokalizacji, języka i waluty odwiedzającego oraz wyświetlanie odpowiednich informacji. Hello jest wymagany podczas korzystania z Checkout.

Możesz skonfigurować wszystkie ustawienia Hello zarówno w Dashboard, jak i w skrypcie JS Zonos. Jeśli już skonfigurowałeś Hello w Dashboard, skrypt załaduje te ustawienia i je wykorzysta. Jeśli określisz jakiekolwiek wartości w właściwości helloSettings funkcji Zonos.init, skrypt użyje tych wartości zamiast.

1

Skonfiguruj konwersję walut

Hello używa selektorów CSS do identyfikacji elementów na Twojej stronie, które wyświetlają informacje o walucie. Będziesz musiał przekazać te selektory do właściwości helloSettings.currencyElementSelector funkcji Zonos.init.

Możesz użyć dowolnego ważnego selektora CSS tutaj, na przykład #price, .price, aby wybrać wiele różnych elementów.

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

Opcjonalne — Automatycznie otwórz Hello po załadowaniu strony

Domyślnie Hello otworzy się tylko wtedy, gdy odwiedzający kliknie przycisk flagi. Jeśli chcesz automatycznie otworzyć Hello po załadowaniu strony, możesz wywołać funkcję Zonos.openHelloDialog(), gdy skrypt Zonos zostanie załadowany.

Zonos JS snippet

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

Skonfiguruj Zonos Checkout 

Gdy Hello zostanie skonfigurowany, musisz skonfigurować Checkout, aby działał z Twoją stroną. Checkout odpowiada za umożliwienie klientowi wprowadzenia informacji o wysyłce, obliczenie landed cost oraz zakończenie zamówienia.

Checkout będzie dzielić się danymi kontekstowymi z Hello, takimi jak lokalizacja odwiedzającego, język i waluta. Zapewnia to, że doświadczenie klienta jest spójne w całym procesie zakupowym.

Możesz skonfigurować wszystkie ustawienia Checkout zarówno w Dashboard, jak i w skrypcie JS Zonos. Jeśli już skonfigurowałeś Checkout w Dashboard, skrypt załaduje te ustawienia i je wykorzysta. Jeśli określisz jakiekolwiek wartości w właściwości checkoutSettings funkcji Zonos.init, skrypt użyje tych wartości zamiast.

1

Skonfiguruj przycisk 'złóż zamówienie'

Skrypt JS Zonos automatycznie rozpozna międzynarodowych kupujących i skieruje ich do procesu Checkout. Jednak będziesz musiał skonfigurować przycisk 'złóż zamówienie' na swojej platformie, aby otwierał Checkout po kliknięciu. Można to zrobić, przekazując selektor CSS do właściwości checkoutSettings.placeOrderButtonSelector funkcji Zonos.init.

Jeśli masz wiele przycisków, które mogą być używane do składania zamówienia, upewnij się, że przekazujesz selektor, który będzie pasował do wszystkich z nich. Na przykład, #placeOrder, .place-order będzie pasować zarówno do #placeOrder, jak i .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

Bezpieczne tworzenie szczegółów koszyka po stronie serwera

Aby wyświetlić szczegóły koszyka klientowi, musisz stworzyć funkcję po stronie serwera, która wywoła API Zonos w celu utworzenia koszyka, a następnie przekaże ten identyfikator koszyka z powrotem do twojego frontend. Zapewni to, że szczegóły koszyka nie będą ujawnione klientowi w sposób, który można by manipulować.

Twoje wywołanie API backendu będzie używać tajnego tokena uwierzytelniającego GraphQL, który różni się od publicznego tokena, którego używasz do uwierzytelnienia skryptu JS Zonos. Ten token można uzyskać w Dashboard -> Settings -> Integracje. Tajny token musi być przekazany jako nagłówek w twoim wywołaniu API.

Mutacja cartCreate akceptuje listę przedmiotów, które powinny być sformatowane zgodnie z schematem przedmiotu koszyka.

Przykład tworzenia koszyka po stronie serwera

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
}

Sugerujemy utworzenie punktu końcowego API na serwerze, a następnie wywołanie tego punktu końcowego z integracji JS na froncie, co jest szczegółowo opisane w następnym kroku.

3

Przekaż identyfikator koszyka do Checkout za pomocą frontendu

Gdy utworzysz koszyk na swoim serwerze, musisz przekazać identyfikator koszyka do skryptu JS Zonos. Można to zrobić, używając funkcji zwrotnej createCartId, która jest częścią funkcji Zonos.init. Checkout następnie bezpiecznie pobierze szczegóły koszyka z Zonos po otwarciu, zapobiegając jakiejkolwiek manipulacji koszykiem.

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

Czy ta strona była pomocna?

Zarezerwuj demonstrację

Zobacz Zonos

polityki i umowy
© 2025 Zonoszonos.com
Na tej stronie:
  • Niestandardowa integracja
  • Zainstaluj skrypt JS Zonos
  • Skonfiguruj Zonos Hello
  • Skonfiguruj Zonos Checkout