1. SDK 설치

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

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

2. 메서드

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

orderInNewTab(products, isPriceDetailsSectionOpen)

새로운 탭에서 글로벌 체크아웃을 호출하는 메서드입니다. products 파라미터에 주문 정보를 전달하고, isPriceDetailsSectionOpen으로 가격 상세 섹션 펼침 여부를 설정할 수 있습니다.

orderInNewTab(products: CartProduct[], isPriceDetailsSectionOpen?: boolean): Promise<void>
  • 파라미터
    • products (타입: CartProduct[]): 주문 정보 배열입니다.(상세 타입은 아래 ‘3. 주문 상품 정보 연동’ 참고)
    • isPriceDetailsSectionOpen (타입: boolean, 선택): 가격 상세 섹션 펼침 여부. 기본값은 true입니다.
  • 리턴 타입
    • Promise<void>: 주문 프로세스가 성공적으로 완료되면 resolve됩니다. 실패 시 에러가 reject됩니다.

Promise 사용

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

async/await 사용

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

orderInIframe(request, isPriceDetailsSectionOpen)

iframe을 사용하여 글로벌 체크아웃을 호출하는 메서드입니다. request 파라미터는 주문 정보와 부모 URL을 포함하며, isPriceDetailsSectionOpen으로 가격 상세 섹션 펼침 여부를 설정할 수 있습니다.

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

Promise 사용

// productsRequest 데이터 구조는 '3. 주문 상품 정보 연동'의 예시를 참고하세요.
dkLibrary.orderInIframe({
  products: productsRequest,
  parentUrl: 'https://example.com/iframe-page?url=',
}, false)
  .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=',
  }, true); // 가격 상세 섹션 숨김
  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>) => {

  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

상품 정보

QuantityControl
object
required

수량 제어 설정

OptionGroup
object
required

옵션 그룹 정보

SelectTypeOption
object
required

선택형 옵션 정보

SelectedOptionGroup
object
required

선택된 옵션 그룹 정보

PricesByCurrency
object
required

통화별 가격 정보

Example 1: 옵션이 없는 단일 상품 (KRW)

상품 예시:

  • 단일 상품으로 별도의 옵션 없이 판매
  • 고객이 수량만 선택 가능
const products = [
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '기본 면 티셔츠',
      prices: { krw: 19900 },
      discountRate: 0,
      originUrl: 'https://example.com/products/basic-tshirt',
      images: ['https://example.com/images/basic-tshirt.jpg'],
      options: [], // 옵션 없음
      quantityControl: {
        allowQuantityChange: true,
        minQuantity: 1,
        maxQuantity: 10
      }
    },
    selectedOptions: [], // 옵션 없음
    quantity: 2
  }
];

Example 2: 선택형 옵션이 있는 상품 (KRW)

상품 예시:

  • 색상 옵션: 화이트(추가금 없음), 블랙(+1,000원)
  • 사이즈 옵션: S, M(추가금 없음), L(+500원)
  • 할인가 적용: 정가 29,900원 → 할인가 19,900원 (33% 할인)
  • 수량 변경 불가 (1개씩만 주문)
const 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: [
        {
          groupName: '색상',
          type: 'select',
          required: true,
          options: [
            { label: '화이트', extraPrice: { krw: 0 } },
            { label: '블랙', extraPrice: { krw: 1000 } }
          ]
        },
        {
          groupName: '사이즈',
          type: 'select',
          required: true,
          options: [
            { label: 'S', extraPrice: { krw: 0 } },
            { label: 'M', extraPrice: { krw: 0 } },
            { label: 'L', extraPrice: { krw: 500 } }
          ]
        }
      ],
      quantityControl: {
        allowQuantityChange: false
      }
    },
    selectedOptions: [
      { groupName: '색상', value: '화이트' },
      { groupName: '사이즈', value: 'M' }
    ],
    quantity: 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개까지 주문 가능
const products = [
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '커스텀 폰케이스',
      prices: { krw: 35000, usd: 29.99 },
      discountRate: 0,
      originUrl: 'https://example.com/products/custom-phone-case',
      images: ['https://example.com/images/phone-case-template.jpg'],
      options: [
        {
          groupName: '기기 모델',
          type: 'select',
          required: true,
          options: [
            { label: 'iPhone 14', extraPrice: { krw: 0, usd: 0 } },
            { label: 'iPhone 14 Pro', extraPrice: { krw: 2000, usd: 1.99 } },
            { label: 'Samsung Galaxy S23', extraPrice: { krw: 0, usd: 0 } },
            { label: 'Samsung Galaxy S23 Ultra', extraPrice: { krw: 3000, usd: 2.99 } }
          ]
        },
        {
          groupName: '케이스 소재',
          type: 'select',
          required: true,
          options: [
            { label: '실리콘 (소프트)', extraPrice: { krw: 0, usd: 0 } },
            { label: '하드 플라스틱', extraPrice: { krw: 1000, usd: 0.99 } },
            { label: '가죽 (프리미엄)', extraPrice: { krw: 8000, usd: 6.99 } }
          ]
        },
        {
          groupName: '커스텀 텍스트',
          type: 'text',
          required: false,
          extraPrice: { krw: 3000, usd: 2.49 }
        },
        {
          groupName: '이미지 업로드',
          type: 'image',
          required: false,
          extraPrice: { krw: 5000, usd: 3.99 }
        }
      ],
      quantityControl: {
        allowQuantityChange: true,
        minQuantity: 1,
        maxQuantity: 5
      }
    },
    selectedOptions: [
      { groupName: '기기 모델', value: 'iPhone 14 Pro' },
      { groupName: '케이스 소재', value: '가죽 (프리미엄)' },
      { groupName: '커스텀 텍스트', value: 'My Special Phone' },
      { 
        groupName: '이미지 업로드', 
        value: [
          'https://example.com/uploads/my-photo.jpg',
          'https://example.com/uploads/pattern-design.png'
        ] 
      }
    ],
    quantity: 2
  }
];

Example 4: 장바구니 다중 상품 연동 (KRW)

상품 예시:

  • 상품 1: 기본 티셔츠 (옵션 없음, 2개)
  • 상품 2: 커스텀 머그컵 (색상 선택 + 텍스트 각인, 1개)
const products = [
  // 첫 번째 상품: 기본 티셔츠
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '기본 면 티셔츠',
      prices: { krw: 19900 },
      discountRate: 0,
      originUrl: 'https://example.com/products/basic-tshirt',
      images: ['https://example.com/images/basic-tshirt.jpg'],
      options: [], // 옵션 없음
      quantityControl: {
        allowQuantityChange: true,
        minQuantity: 1,
        maxQuantity: 10
      }
    },
    selectedOptions: [], // 옵션 없음
    quantity: 2
  },
  // 두 번째 상품: 커스텀 머그컵
  {
    productRequest: {
      sellerClientKey: 'your_seller_client_key',
      title: '커스텀 세라믹 머그컵',
      prices: { krw: 15000 },
      originalPrices: { krw: 18000 },
      discountRate: 17,
      originUrl: 'https://example.com/products/custom-mug',
      images: ['https://example.com/images/ceramic-mug.jpg'],
      options: [
        {
          groupName: '컵 색상',
          type: 'select',
          required: true,
          options: [
            { label: '화이트', extraPrice: { krw: 0 } },
            { label: '블랙', extraPrice: { krw: 1000 } },
            { label: '네이비', extraPrice: { krw: 1000 } }
          ]
        },
        {
          groupName: '개인화 텍스트',
          type: 'text',
          required: false,
          extraPrice: { krw: 3000 }
        }
      ],
      quantityControl: {
        allowQuantityChange: true,
        minQuantity: 1,
        maxQuantity: 5
      }
    },
    selectedOptions: [
      { groupName: '컵 색상', value: '블랙' },
      { groupName: '개인화 텍스트', value: 'My Coffee Cup' }
    ],
    quantity: 1
  }
];

4. 주의 사항

  1. 클라이언트키 사용

    • sellerClientKey는 딜리버드 파트너스에서 제공한 판매자 고유값입니다.
    • 모든 ProductRequest 객체에는 반드시 sellerClientKey가 포함되어야 합니다.
  2. 옵션 그룹과 선택된 옵션의 관계

    • SelectedOptionGroupgroupName은 반드시 ProductRequestoptions 중 동일한 groupName이 존재해야 합니다.
    • OptionGroup에서 required: true인 옵션은 selectedOptions에 반드시 포함되어야 합니다.
    • ProductRequest.options 내부의 groupName은 같은 상품 내에서 unique해야 합니다.
    • OptionGroup.options 내부에서 label은 같은 옵션 그룹 내에서 unique해야 합니다.
  3. 옵션 타입별 제약사항

    • typeselect인 경우 options 필드가 필수입니다.
    • typeselect인 경우 extraPrice는 무시되고, 각 SelectTypeOptionextraPrice가 적용됩니다.
    • typeimage인 경우 valuestring[] 타입이며, png, jpg, jpeg 형식의 완전한 URL만 허용됩니다.
    • typetext 또는 select인 경우 valuestring 타입입니다.
  4. 수량 제어 설정

    • allowQuantityChangetrue인 경우 minQuantity, maxQuantity 값이 필수입니다.
  5. 할인 가격 설정

    • discountRate가 0보다 크다면, 할인 전 가격인 originalPrices 필드는 필수적으로 포함되어야 합니다.
    • originalPrices는 쇼핑몰의 상품 소비자가격과 동일해야 합니다.
    • discountRate가 0이라면, originalPrices는 선택 사항이며, 값을 전달해도 할인 계산에 사용되지 않습니다.
  6. 통화 사용 설정

    • pricesoriginalPrices, extraPrice 필드에는 PricesByCurrency 타입 객체를 사용합니다.
    • 기본 통화는 KRW입니다. KRW 가격(krw)은 항상 필수입니다.
    • 표시 통화가 USD인 쇼핑몰의 경우에도 주문 확인을 위해 krw 값이 필수로 포함되어야 합니다.
    • 쇼핑몰의 기본 화폐 단위를 USD로 사용하고 싶으신 경우, 딜리버드 파트너스 문의하기를 통해 별도 문의가 필요합니다.
  7. 가격 상세 섹션 설정

    • isPriceDetailsSectionOpen 파라미터로 체크아웃 페이지의 가격 상세 섹션 펼침 여부를 제어할 수 있습니다.
    • 기본값은 true(노출)이며, false로 설정하면 가격 상세 섹션이 접혀진 상태로 시작됩니다.