DOCS

Custom integration

/
Checkout•
홈글로벌 전자상거래 통합 Checkout 통합 맞춤형 통합

맞춤형 통합

귀하의 맞춤형 사이트에 Checkout 통합을 구축하세요.

이 가이드는 귀하의 맞춤형 사이트 또는 플랫폼에 Zonos Checkout의 전체 통합을 완료하는 기술적 측면을 다룹니다. JavaScript 작업에 익숙하고 프론트엔드 개발 경험이 있는 개발자를 위한 것입니다. 별도로 언급되지 않는 한 모든 단계가 필요합니다.

필수 조건


이 가이드는 귀하의 맞춤형 사이트 또는 플랫폼에 Zonos Checkout의 전체 통합을 완료하는 기술적 측면을 다룹니다. JavaScript 작업에 익숙하고 프론트엔드 개발 경험이 있는 개발자를 위한 것입니다. 별도로 언급되지 않는 한 모든 단계가 필요합니다.

필수 조건


Zonos JS 스크립트 설치 

귀하의 맞춤형 통합에는 Zonos JavaScript 스니펫이 포함되어야 합니다. 이 스크립트는 Checkout UI, Zonos Hello를 렌더링하고, 결제 처리를 처리하며, 방문자의 geo-IP 감지를 처리하는 역할을 합니다.

1

Zonos JS 스니펫 설치

Zonos Elements 스크립트는 다음 URL에서 사용할 수 있습니다:

Zonos JS 스니펫

1
<script src="https://js.zonos.com/dist/scripts/loadZonos.js" />

브라우저 캐싱 처리

우리는 또한 스크립트가 브라우저에 의해 캐시되지 않도록 URL에 타임스탬프 또는 기타 고유 식별자를 추가하는 것을 일반적으로 권장합니다. 이렇게 하면 항상 최신 버전의 스크립트가 로드됩니다. 예를 들어:

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://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>
2

Zonos JS 스니펫 인증

Zonos JS 스크립트를 로드한 후, Zonos API 키와 저장소 ID를 Zonos.init 함수에 전달하여 인증해야 합니다. Checkout 인증에 사용되는 API 키는 게시 가능하도록 설계되어 있어, 민감한 정보를 노출하지 않고도 프론트엔드 코드에서 안전하게 사용할 수 있습니다.

Zonos JS 스니펫

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

허용된 도메인 설정

Zonos JS 스크립트가 허용된 사이트에서만 로드되도록 하기 위해, "허용된 도메인" 목록을 기반으로 요청을 필터링합니다. 이 목록은 대시보드에서 구성됩니다. 이 구성이 없으면 Zonos JS 스크립트는 제대로 로드되지 않고 권한 오류를 반환합니다.

허용된 도메인을 업데이트하려면:

  1. 대시보드 -> 설정 -> Checkout 설정으로 이동합니다.
  2. 허용된 도메인 섹션에서 Checkout을 통합할 도메인(s)을 추가합니다.
  3. 저장을 클릭합니다.

Zonos Hello 설정 

Zonos JS 스크립트를 설정한 후, Hello를 귀하의 사이트와 함께 작동하도록 구성해야 합니다. Hello는 방문자의 위치, 언어 및 통화를 감지하고 적절한 정보를 표시하는 역할을 합니다. Hello는 Checkout을 사용할 때 필요합니다.

Hello의 모든 설정은 대시보드와 Zonos JS 스크립트에서 구성할 수 있습니다. 이미 대시보드에서 Hello를 구성한 경우, 스크립트는 해당 설정을 로드하여 사용합니다. Zonos.init 함수의 helloSettings 속성에 값을 지정하면, 스크립트는 대신 해당 값을 사용합니다.

1

통화 변환 구성

Hello는 사이트에서 통화 정보를 표시하는 요소를 식별하기 위해 CSS 선택기를 사용합니다. 이러한 선택기를 Zonos.init 함수의 helloSettings.currencyElementSelector 속성에 전달해야 합니다.

여기에서 유효한 CSS 선택기를 사용할 수 있으며, 예를 들어 #price, .price를 사용하여 여러 다른 요소를 선택할 수 있습니다.

Zonos JS 스니펫

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

항목 제한 구성

Hello는 쇼핑객이 브라우징하는 동안 제한된 항목을 확인하고 장바구니에 추가되는 것을 방지할 수 있는 기능을 가지고 있습니다. 이를 위해 Hello는 이름 및 설명과 같은 추가 항목 정보와 "장바구니에 추가 버튼"에 대해 알아야 합니다. Hello에 CSS 선택기를 전달하여 페이지에서 이 정보를 스크랩할 수 있도록 할 수 있습니다.

Zonos JS 스니펫

1
2
3
4
5
6
7
8
9
10
Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    productAddToCartElementSelector: '.add-to-cart',
    productDescriptionElementSelector: '.description',
    productPriceElementSelector: '.price',
    productTitleElementSelector: '.title',
  },
});

선택 사항 — 페이지 로드 시 Hello 자동 열기

기본적으로 Hello는 방문자가 플래그 버튼을 클릭할 때만 열립니다. 페이지가 로드될 때 Hello를 자동으로 열고 싶다면, Zonos 스크립트가 로드된 후 Zonos.openHelloDialog() 함수를 호출하면 됩니다.

Zonos JS 스니펫

1
2
3
4
5
Zonos.init({
  // ... other fields
});

Zonos.openHelloDialog();

Zonos Checkout 설정하기 

Hello가 구성된 후, Checkout를 귀하의 사이트와 함께 작동하도록 설정해야 합니다. Checkout는 고객이 배송 정보를 입력하고, landed cost를 계산하며, 주문을 완료할 수 있도록 합니다.

Checkout는 방문자의 위치, 언어 및 통화와 같은 맥락 데이터를 Hello와 공유합니다. 이는 고객의 경험이 전체 쇼핑 과정에서 일관되도록 보장합니다.

모든 Checkout 설정은 대시보드와 Zonos JS 스크립트 모두에서 구성할 수 있습니다. 이미 대시보드에서 Checkout를 구성한 경우, 스크립트는 해당 설정을 로드하여 사용합니다. Zonos.init 함수의 checkoutSettings 속성에 값을 지정하면, 스크립트는 대신 해당 값을 사용합니다.

1

'주문하기' 버튼 구성하기

Zonos JS 스크립트는 국제 쇼핑객을 자동으로 인식하고 그들을 Checkout 흐름으로 안내합니다. 그러나 클릭 시 Checkout를 열도록 플랫폼에서 '주문하기' 버튼을 구성해야 합니다. 이는 Zonos.init 함수의 checkoutSettings.placeOrderButtonSelector 속성에 CSS 선택기를 전달하여 수행할 수 있습니다.

주문을 할 수 있는 여러 버튼이 있는 경우, 모든 버튼과 일치하는 선택기를 전달해야 합니다. 예를 들어, #placeOrder, .place-order는 #placeOrder와 .place-order 모두와 일치합니다.

Zonos JS 스니펫

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

장바구니 보기 전용 장바구니 세부정보를 Checkout에 전달하기

buildCartDetail 콜백은 Checkout 인터페이스가 이해하고 표시할 수 있는 형식으로 장바구니 세부정보를 반환하는 역할을 합니다. 이 함수는 고객이 checkout 페이지에 도착하자마자 호출되어, Checkout의 첫 페이지에 장바구니 세부정보가 정확하게 표시되도록 보장합니다. 이 기능은 계산에 사용되지 않으며, 그 부분은 다음 단계에서 처리됩니다.

Zonos JS 스니펫

1
2
3
4
5
6
7
8
9
10
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildCartDetail: async () => {
      // ... Your existing buildCartDetail implementation
      // This should return cart details for UI display
    },
  },
});

장바구니 항목 스키마

buildCartDetail 함수는 장바구니 항목의 배열을 반환해야 합니다. 아래는 각 CartItem 객체의 구조를 자세히 설명하는 표입니다:

필드 이름유형필수설명
amount숫자예항목의 가격 금액입니다.
countryOfOrigin문자열아니오항목의 원산지 국가입니다.
currencyCode문자열예금액의 통화 코드입니다.
description문자열아니오항목에 대한 설명입니다.
hsCode문자열아니오항목의 조화 시스템 코드입니다.
imageUrl문자열아니오항목 이미지의 URL입니다.
measurementsItemMeasurement[]아니오항목 측정값의 배열입니다.
metadata객체 (문자열/숫자 쌍)아니오항목에 대한 추가 메타데이터입니다.
name문자열예항목의 이름입니다.
productId문자열아니오제품 ID입니다.
quantity숫자예장바구니에 있는 항목의 수량입니다.
sku문자열아니오재고 관리 단위 식별자입니다.
3

landed cost를 Checkout에 안전하게 전달하기

buildLandedCost 함수는 landed cost를 안전하게 계산하는 역할을 합니다. 이 함수는 고객이 배송 정보를 입력한 후 호출됩니다. 이 함수는 배송 요금 및 기타 필요한 비용을 계산하며, 이는 이후 Checkout 페이지에 표시됩니다.

서버 측에서 landed cost 계산 로직을 처리하는 것이 중요합니다. 이는 장바구니 세부 정보가 고객의 브라우저에 노출되지 않도록 보장하는 유일한 방법입니다. 서버리스 아키텍처를 사용하는 경우, 서버리스 함수를 사용하여 landed cost 계산을 처리할 수 있습니다. buildLandedCost 함수는 단순히 서버리스 함수/API 엔드포인트를 호출하고 결과를 반환해야 합니다.

서버 측에서는 다음 POST 요청을 사용하여 Zonos Checkout API를 통해 landed cost를 계산할 수 있습니다. credentialToken 헤더에 Zonos JS 스크립트에 사용하고 있는 API 키를 전달해야 합니다.

요청 URL

1
https://v1.route.js.zonos.com/api/zonos-elements/calculate-landed-cost

요청 본문

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
{
  "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 JS 코드 조각

1
2
3
4
5
6
7
8
9
Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // This should return the landed cost calculation
    },
  },
});

이 페이지가 도움이 되었습니까?

질문 있으세요?

문의하세요.

Zonos을 보세요

정책 및 계약
© 2024 Zonoszonos.com
이 페이지에서:
  • Zonos JS 스크립트 설치
  • Zonos Hello 설정
  • Zonos Checkout 설정하기