글로벌 오더
SDK 연동하기
글로벌 오더 통합형 JavaScript SDK는 브라우저 환경에서 글로벌 오더를 새 탭 또는 iframe으로 열 수 있는 메서드를 제공합니다. SDK 사용을 위한 준비와 메서드 사용법을 알아봅니다.
1. SDK 설치
SDK를 사용하기 위해 다음 스크립트를 HTML의 <head>
태그 내에 추가해주세요.
2. 메서드
글로벌 오더 통합형 SDK에서 제공하는 주요 메서드입니다.
orderInNewTab(products, isPriceDetailsSectionOpen)
새로운 탭에서 글로벌 체크아웃을 호출하는 메서드입니다. products
파라미터에 주문 정보를 전달하고, isPriceDetailsSectionOpen
으로 가격 상세 섹션 펼침 여부를 설정할 수 있습니다.
- 파라미터
products
(타입:CartProduct[]
): 주문 정보 배열입니다.(상세 타입은 아래 ‘3. 주문 상품 정보 연동’ 참고)isPriceDetailsSectionOpen
(타입:boolean
, 선택): 가격 상세 섹션 펼침 여부. 기본값은true
입니다.
- 리턴 타입
Promise<void>
: 주문 프로세스가 성공적으로 완료되면 resolve됩니다. 실패 시 에러가 reject됩니다.
Promise 사용
async/await 사용
orderInIframe(request, isPriceDetailsSectionOpen)
iframe을 사용하여 글로벌 체크아웃을 호출하는 메서드입니다. request
파라미터는 주문 정보와 부모 URL을 포함하며, isPriceDetailsSectionOpen
으로 가격 상세 섹션 펼침 여부를 설정할 수 있습니다.
- 파라미터
request
(타입:IframeCartProductRequest
): 주문 정보와 부모 페이지 URL을 포함하는 객체입니다. (상세 타입은 아래 ‘3. 주문 상품 정보 연동’ 참고)isPriceDetailsSectionOpen
(타입:boolean
, 선택): 가격 상세 섹션 펼침 여부. 기본값은true
입니다.
- 리턴 타입
Promise<string>
: iframe 로드에 사용할 URL을 반환합니다. 실패 시 에러가 reject됩니다.
Promise 사용
iframe을 로드할 부모 페이지의 URL
async/await 사용
iframe을 로드할 부모 페이지의 URL
iframe을 노출할 페이지의 코드
3. 주문 상품 정보 연동
Parameter 상세 설명
orderInIframe
메서드 요청 시 사용되는 데이터 구조
개별 장바구니 상품 정보 (orderInNewTab
의 products
배열 요소, IframeCartProductRequest
의 products
배열 요소)
상품 정보
수량 제어 설정
옵션 그룹 정보
선택형 옵션 정보
선택된 옵션 그룹 정보
통화별 가격 정보
Example 1: 옵션이 없는 단일 상품 (KRW)
상품 예시:
- 단일 상품으로 별도의 옵션 없이 판매
- 고객이 수량만 선택 가능
Example 2: 선택형 옵션이 있는 상품 (KRW)
상품 예시:
- 색상 옵션: 화이트(추가금 없음), 블랙(+1,000원)
- 사이즈 옵션: S, M(추가금 없음), L(+500원)
- 할인가 적용: 정가 29,900원 → 할인가 19,900원 (33% 할인)
- 수량 변경 불가 (1개씩만 주문)
Example 3: 커스터마이징 옵션이 있는 상품 (USD)
상품 예시:
- 기기 모델 옵션: iPhone 14(추가금 없음), iPhone 14 Pro(+$1.99), Galaxy S23(추가금 없음), Galaxy S23 Ultra(+$2.99)
- 케이스 소재 옵션: 실리콘(추가금 없음), 하드 플라스틱(+$0.99), 가죽(+$6.99)
- 커스텀 텍스트 옵션: 고객이 직접 입력하는 텍스트 각인 서비스 (+$2.49)
- 이미지 업로드 옵션: 고객이 png/jpg/jpeg 파일을 업로드하여 인쇄 (+$3.99)
- 수량 제한: 1~5개까지 주문 가능
Example 4: 장바구니 다중 상품 연동 (KRW)
상품 예시:
- 상품 1: 기본 티셔츠 (옵션 없음, 2개)
- 상품 2: 커스텀 머그컵 (색상 선택 + 텍스트 각인, 1개)
4. 주의 사항
-
클라이언트키 사용
sellerClientKey
는 딜리버드 파트너스에서 제공한 판매자 고유값입니다.- 모든
ProductRequest
객체에는 반드시sellerClientKey
가 포함되어야 합니다.
-
옵션 그룹과 선택된 옵션의 관계
SelectedOptionGroup
의groupName
은 반드시ProductRequest
의options
중 동일한groupName
이 존재해야 합니다.OptionGroup
에서required: true
인 옵션은selectedOptions
에 반드시 포함되어야 합니다.ProductRequest.options
내부의groupName
은 같은 상품 내에서 unique해야 합니다.OptionGroup.options
내부에서label
은 같은 옵션 그룹 내에서 unique해야 합니다.
-
옵션 타입별 제약사항
type
이select
인 경우options
필드가 필수입니다.type
이select
인 경우extraPrice
는 무시되고, 각SelectTypeOption
의extraPrice
가 적용됩니다.type
이image
인 경우value
는string[]
타입이며, png, jpg, jpeg 형식의 완전한 URL만 허용됩니다.type
이text
또는select
인 경우value
는string
타입입니다.
-
수량 제어 설정
allowQuantityChange
가true
인 경우minQuantity
,maxQuantity
값이 필수입니다.
-
할인 가격 설정
discountRate
가 0보다 크다면, 할인 전 가격인originalPrices
필드는 필수적으로 포함되어야 합니다.originalPrices
는 쇼핑몰의 상품 소비자가격과 동일해야 합니다.discountRate
가 0이라면,originalPrices
는 선택 사항이며, 값을 전달해도 할인 계산에 사용되지 않습니다.
-
통화 사용 설정
prices
및originalPrices
,extraPrice
필드에는PricesByCurrency
타입 객체를 사용합니다.- 기본 통화는 KRW입니다. KRW 가격(
krw
)은 항상 필수입니다. - 표시 통화가 USD인 쇼핑몰의 경우에도 주문 확인을 위해
krw
값이 필수로 포함되어야 합니다. - 쇼핑몰의 기본 화폐 단위를 USD로 사용하고 싶으신 경우, 딜리버드 파트너스 문의하기를 통해 별도 문의가 필요합니다.
-
가격 상세 섹션 설정
isPriceDetailsSectionOpen
파라미터로 체크아웃 페이지의 가격 상세 섹션 펼침 여부를 제어할 수 있습니다.- 기본값은
true
(노출)이며,false
로 설정하면 가격 상세 섹션이 접혀진 상태로 시작됩니다.