Niestandardowa integracja

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

<script src="https://js.zonos.com/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:

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

Po załadowaniu skryptu JS Zonos musisz go uwierzytelnić, przekazując Zonos klucz API oraz identyfikator sklepu 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.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
});

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.

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.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: '#price, .price', // Replace with your actual selector
  },
});

Hello ma możliwość sprawdzania ograniczonych przedmiotów, gdy klient przegląda i zapobiega ich dodawaniu do koszyka. Aby to działało, Hello musi znać dodatkowe informacje o przedmiotach, takie jak nazwa i opis, a także "przycisk dodaj do koszyka". Możesz przekazać selektory CSS do Hello, aby umożliwić mu zbieranie tych informacji z strony.

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

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.init({
  // ... other fields
});

Zonos.openHelloDialog();

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.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

Callback buildCartDetail jest odpowiedzialny za zwracanie szczegółów koszyka w formacie, który interfejs Checkout może zrozumieć i wyświetlić. Ta funkcja jest wywoływana, gdy tylko klient dotrze na stronę checkout, co zapewnia, że szczegóły koszyka są wyświetlane dokładnie na pierwszej stronie Checkout. Należy pamiętać, że nie jest to używane do obliczeń - tym zajmuje się następny krok.

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

Schemat pozycji w koszyku

Funkcja buildCartDetail powinna zwracać tablicę pozycji w koszyku. Poniżej znajduje się tabela szczegółowo opisująca strukturę każdego obiektu CartItem:

Funkcja buildLandedCost zajmuje się bezpiecznym obliczaniem landed cost. Jest wywoływana po tym, jak klient wprowadzi swoje dane wysyłkowe. Funkcja ta oblicza stawki wysyłkowe i inne niezbędne koszty, które są następnie wyświetlane na kolejnej stronie Checkout.

Ważne jest, abyś obsługiwał logikę obliczania landed cost po stronie serwera, ponieważ jest to jedyny sposób, aby zapewnić, że szczegóły koszyka nie są ujawniane przeglądarce klienta. Jeśli używasz architektury bezserwerowej, możesz użyć funkcji bezserwerowej do obsługi obliczeń landed cost. Funkcja buildLandedCost powinna po prostu wywołać funkcję bezserwerową/punkt końcowy API i zwrócić wynik.

Po stronie serwera możesz użyć API Zonos Checkout do obliczenia landed cost za pomocą następującego żądania POST. Będziesz musiał przekazać klucz API, którego używasz dla skryptu JS Zonos w nagłówku credentialToken.

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