1. SDK 설치

SDK를 사용하기 위해 다음 스크립트를 HTML의 <head> 태그 내에 추가해주세요.

<head>
  <script src="https://sdk-checkout.delivered.co.kr/index.js"></script>
</head>

2. 메서드

글로벌 오더 통합형 SDK에서 제공하는 주요 메서드입니다.

orderInNewTab(products)

새로운 탭에서 글로벌 체크아웃을 호출하는 메서드입니다. products 파라미터에 주문 정보를 전달합니다.

orderInNewTab(products: CartProduct[]): Promise<void>
  • 파라미터
    • products (타입: CartProduct[]): 주문 정보 배열입니다.(상세 타입은 아래 ‘3. 주문 상품 정보 연동’ 참고)
  • 리턴 타입
    • Promise<void>: 주문 프로세스가 성공적으로 완료되면 resolve됩니다. 실패 시 에러가 reject됩니다.

Promise 사용

// products 데이터 구조는 '3. 주문 상품 정보 연동'의 예시를 참고하세요.
dkLibrary.orderInNewTab(products)
  .then(() => {
    console.log('주문 성공');
  })
  .catch((err) => {
    console.error('주문 실패:', err);
  })
  .finally(() => {
    console.log('주문 프로세스 완료');
  });

async/await 사용

// products 데이터 구조는 '3. 주문 상품 정보 연동'의 예시를 참고하세요.
try {
  await dkLibrary.orderInNewTab(products);
  console.log('주문 성공');
} catch (err) {
  console.error('주문 실패:', err);
}

orderInIframe(request)

iframe을 사용하여 글로벌 체크아웃을 호출하는 메서드입니다. request 파라미터는 주문 정보와 부모 URL을 포함합니다.

orderInIframe(request: IframeCartProductRequest): Promise<string>
  • 파라미터
    • request (타입: IframeCartProductRequest): 주문 정보와 부모 페이지 URL을 포함하는 객체입니다. (상세 타입은 아래 ‘3. 주문 상품 정보 연동’ 참고)
  • 리턴 타입
    • Promise<string>: iframe 로드에 사용할 URL을 반환합니다. 실패 시 에러가 reject됩니다.

Promise 사용

// productsRequest 데이터 구조는 '3. 주문 상품 정보 연동'의 예시를 참고하세요.
dkLibrary.orderInIframe({
  products: productsRequest,
  parentUrl: 'https://example.com/iframe-page?url=',
})
  .then((response) => {
    console.log('주문 성공');
    window.location.href = `https://example.com/iframe-page?url=${response}`;
  })
  .catch((err) => {
    console.error('주문 실패:', err);
  })
  .finally(() => {
    console.log('주문 프로세스 완료');
  });
parentUrl
string
required

iframe을 로드할 부모 페이지의 URL

async/await 사용

// productsRequest 데이터 구조는 '3. 주문 상품 정보 연동'의 예시를 참고하세요.
try {
  const response = await dkLibrary.orderInIframe({
    products: productsRequest,
    parentUrl: 'https://example.com/iframe-page?url=',
  });
  console.log('주문 성공');
  window.location.href = `https://example.com/iframe-page?url=${response}`;
} catch (err) {
  console.error('주문 실패:', err);
}
parentUrl
string
required

iframe을 로드할 부모 페이지의 URL

iframe을 노출할 페이지의 코드

const url = window.location.search.replace("?url=", "");
const eventListener = (e: MessageEvent<any>) => {
  if (e.origin !== "https://checkout.delivered.co.kr") return;

  const { type, payload } = e.data;

  if (type === "dk-global-order-go-to") {
    window.location.replace(payload);
  }
};

window.addEventListener("message", eventListener);
<iframe src={url} />

3. 주문 상품 정보 연동

Parameter 상세 설명

IframeCartProductRequest
object
required

orderInIframe 메서드 요청 시 사용되는 데이터 구조

CartProduct
object
required

개별 장바구니 상품 정보 (orderInNewTabproducts 배열 요소, IframeCartProductRequestproducts 배열 요소)

ProductRequest
object
required

상품 정보

SelectedOptionRequest
object
required

선택된 옵션 정보

PricesByCurrency
object
required

통화별 가격 정보

Example 1: 옵션이 있고, 할인율이 적용된 상품 (KRW 사용)

const products = [ // 또는 productsRequest (IframeCartProductRequest의 products)
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '프리미엄 티셔츠',
      prices: { krw: 19900 },
      originalPrices: { krw: 29900 },
      discountRate: 33,
      originUrl: 'https://example.com/products/premium-tshirt',
      images: ['https://example.com/images/tshirt-front.jpg'],
      options: [
        { title: '색상: 흰색', prices: { krw: 0 } },
        { title: '색상: 검정', prices: { krw: 1000 } },
      ],
    },
    selectedOptions: [{ title: '색상: 흰색', quantity: 1 }],
  },
];

Example 2: 옵션이 없고, 할인율이 적용되지 않은 상품 (KRW 사용)

const products = [ // 또는 productsRequest
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '기본 티셔츠',
      prices: { krw: 19900 },
      // originalPrices는 discountRate가 0이므로 불필요
      discountRate: 0,
      originUrl: 'https://example.com/products/basic-tshirt',
      images: ['https://example.com/images/basic-tshirt.jpg'],
      // 옵션 없는 상품도 아래와 같이 기본 옵션 필요
      options: [{ title: '', prices: { krw: 0 } }],
    },
    selectedOptions: [{ title: '', quantity: 2 }], // 옵션 없는 상품의 선택 정보
  },
];

Example 3: 조합형 옵션 상품 (USD 사용)

const products = [ // 또는 productsRequest
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '클래식 청바지',
      prices: { krw: 59000, usd: 49.99 },
      // originalPrices는 discountRate가 0이므로 불필요
      discountRate: 0,
      originUrl: 'https://example.com/products/classic-jeans',
      images: ['https://example.com/images/jeans.jpg'],
      options: [
        { title: '색상: 파랑, 사이즈: 30', prices: { krw: 0, usd: 0 } },
        { title: '색상: 파랑, 사이즈: 32', prices: { krw: 0, usd: 0 } },
        { title: '색상: 검정, 사이즈: 30', prices: { krw: 1000, usd: 1.00 } },
        { title: '색상: 검정, 사이즈: 32', prices: { krw: 1000, usd: 1.00 } },
      ],
    },
    selectedOptions: [{ title: '색상: 검정, 사이즈: 32', quantity: 1 }],
  },
];

4. 주의 사항

  1. sellerClientKey의 사용

    • sellerClientKey는 딜리버드 파트너스에서 제공한 판매자 고유값입니다.
    • 모든 ProductRequest 객체에는 반드시 sellerClientKey가 포함되어야 합니다.
  2. optionsselectedOptions의 사용

    • selectedOptionstitle은 반드시 productRequestoptions 중 동일한 title이 존재해야 합니다.
    • 상품에 옵션이 없는 경우에도 productRequestoptions 배열은 길이가 1 이상이어야 합니다. 빈 옵션을 추가하고, selectedOptions에도 titlequantity를 포함하여 전달해야 합니다.
  3. 할인 가격 설정 (discountRate, originalPrices)

    • discountRate가 0보다 크다면, 할인 전 가격인 originalPrices 필드는 필수적으로 포함되어야 합니다.
    • discountRate가 0이라면, originalPrices는 선택 사항이며, 값을 전달해도 할인 계산에 사용되지 않습니다.
  4. 통화 사용 설정 (PricesByCurrency)

    • pricesoriginalPrices (해당하는 경우), OptionRequestprices 필드에는 PricesByCurrency 타입 객체를 사용합니다.
    • 기본 통화는 KRW입니다. KRW 가격(krw)은 항상 필수입니다.
    • 화폐 단위를 USD를 사용하는 판매자의 경우, usd 값을 포함해야 합니다. (krw 값도 필수)
    • 쇼핑몰의 기본 화폐 단위를 KRW가 아닌 USD로 사용하고 싶으신 경우, 딜리버드 파트너스 문의하기를 통해 별도 문의가 필요합니다.