WEB SDK 연동 가이드

라이브 데모

Playground: Mallpie Web SDK Playground →
설명: CDN에서 SDK를 로드한 뒤 initialize · start · mount 등을 브라우저에서 바로 실행·검증할 수 있습니다.

1. 개요

이 프로젝트는 script/CDN 방식으로 사용할 수 있는 Mallpie Web SDK입니다.

핵심 포인트:

window.MallpieSDK가 직접 정의됩니다.
https://ad.mallpie.co.kr/cps/prd/sdk/index.global.js를 <script>로 로드하면 바로 사용할 수 있습니다.
initialize() / getMallpieUrl() / start() / mount() / close() / flushTrackingData()를 지원합니다.
추가로 destroy() / registerCallback() / version도 제공됩니다.
현재 버전: 1.0.1

2. 로딩 파일

<script src="https://ad.mallpie.co.kr/cps/prd/sdk/index.global.js"></script>

3. script 방식 사용 예시

<script src="https://ad.mallpie.co.kr/cps/prd/sdk/index.global.js"></script>
<script>
  window.MallpieSDK.initialize({
    userKey: 'YOUR_USER_KEY',
    apiKey: 'YOUR_API_KEY',
    adid:'YOUR_USER_ADID',
    isDev: true,
    onReady: function(url) { console.log('[onReady]', url); }
  }).then(function () {
    window.MallpieSDK.start();
  });
</script>

4. 자동 초기화 방식

<script>
  window.MallpieConfig = {
    userKey: 'YOUR_USER_KEY',
    apiKey: 'YOUR_API_KEY',
    adid:'YOUR_USER_ADID',
    isDev: true,
  };
</script>
<script src="https://ad.mallpie.co.kr/cps/prd/sdk/index.global.js"></script>

5. 정상 동작 확인 포인트

문서 상단 라이브 데모 링크에서 동일한 흐름을 바로 재현할 수 있습니다. 아래 순서로 동작 여부를 확인합니다.

window.MallpieSDK가 로드되었는지 확인 (예: typeof window.MallpieSDK.initialize === 'function')
initialize(options) 호출 후 Promise가 resolve 되는지 확인
options.onReady(url) 콜백이 호출되는지 확인
getMallpieUrl()이 문자열을 반환하는지 확인
start() 호출 시 새 탭/팝업 창이 열리는지 확인 (브라우저 팝업 차단 해제 필요)
mount(container, options) 호출 시 iframe이 컨테이너에 삽입되고 HTMLIFrameElement가 반환되는지 확인
flushTrackingData() 호출 시 추적 데이터 전송이 시도되는지 확인
close() 호출 시 iframe/팝업이 정리되고 onClose 콜백이 호출되는지 확인

6. `initialize(options)` 옵션

initialize()는 Promise<void>를 반환하며, 완료되면 내부적으로 Shop ID를 조회하고 Mallpie URL을 구성한 뒤 onReady(url)를 호출합니다.

window.MallpieSDK.initialize({
  userKey: 'YOUR_USER_KEY',
  apiKey: 'YOUR_API_KEY',
  adid:'YOUR_USER_ADID',
  isDev: true,
  allowedOrigins: ['https://example.com'],
  onReady: function (url) { console.log('[onReady]', url); },
  onError: function (err) { console.log('[onError]', err.code, err.message); },
  onOpen: function () { console.log('[onOpen]'); },
  onClose: function () { console.log('[onClose]'); },
});

주요 옵션:

userKey(필수), apiKey(필수): 초기화에 필요한 키
adid(선택): 개인화 상품 추천을 위한 필수 값으로 adid 값 미 제공시 개인화 상품 추천 불가
isDev(선택): 개발/운영 환경 구분 (기본값: false)
baseWebUrl, bootstrapUrl, trackingUrl(선택): 서버/URL 오버라이드
allowedOrigins(선택): postMessage 수신 허용 origin 목록
콜백: onError, onClose, onOpen, onReady

_{※ adid :} _{Android: Google Advertising ID (GAID) /} _{iOS: Identifier for Advertisers (IDFA)}

7. 콜백/이벤트 제어

registerCallback(name, fn): 브리지 요청에서 callbackName으로 전달된 값을 기준으로 1회성 콜백을 등록합니다.
- MALLPIE_GET_ITEM: fn(getStorageItem(key))
- MALLPIE_GET_EVENTS: fn(getEventTrackingData())
flushTrackingData(useBeacon?: boolean): 누적 추적 이벤트를 500건 단위 배치로 전송합니다.
- useBeacon=true이면 가능할 때 navigator.sendBeacon()을 사용합니다.
- beforeunload 이벤트 및 visibilitychange 이벤트(hidden 전환 시) 에서도 자동 호출됩니다.
start(): window.open()으로 새 팝업 창을 열어 Mallpie 페이지를 표시합니다. mount() 모드가 활성 중이면 iframe을 먼저 제거합니다.
mount(container, options?): 지정된 컨테이너 요소에 iframe을 삽입하고 HTMLIFrameElement를 반환합니다. start() 팝업이 활성 중이면 먼저 닫습니다. options로 width, height, className 지정 가능.
close(): 현재 열린 iframe 또는 팝업을 닫고, 추적 데이터를 flush한 뒤 onClose 콜백을 호출합니다.
destroy(): close() 후 메시지/라이프사이클 이벤트 리스너를 모두 해제하고 내부 상태를 초기화합니다.
version: SDK 버전 문자열 (현재 '1.0.1')
onError(err): err.code, err.message, err.errorType 정보를 포함한 에러 객체를 전달받습니다.
- E001: Shop ID가 초기화되지 않았습니다.
- E002: API Key(Media Key)가 누락되거나 유효하지 않습니다.
- E003: User Key가 누락되었습니다.
- E004: SDK가 이미 초기화 중입니다.
- E200: Mallpie 서버 내부 통신 에러가 발생했습니다.
- E300: 알 수 없는 오류 또는 팝업이 브라우저에 의해 차단되었습니다.
- W001: 광고 식별자(ADID) 수집에 실패했습니다.(WARNING)

8. 브리지 방식

웹에서는 postMessage 기반 브리지를 사용합니다.

지원 메시지:

MALLPIE_CLOSE
MALLPIE_SET_ITEM
MALLPIE_GET_ITEM
MALLPIE_REMOVE_ITEM
MALLPIE_SAVE_EVENT
MALLPIE_GET_EVENTS

메시지 payload 형태(예시):

MALLPIE_CLOSE: { type: 'MALLPIE_CLOSE' }
MALLPIE_SET_ITEM: { type: 'MALLPIE_SET_ITEM', key: '...', value: '...', expireSec?: number }
MALLPIE_GET_ITEM: { type: 'MALLPIE_GET_ITEM', key: '...', callbackName: '...' }
MALLPIE_REMOVE_ITEM: { type: 'MALLPIE_REMOVE_ITEM', key: '...' }
MALLPIE_SAVE_EVENT: { type: 'MALLPIE_SAVE_EVENT', data: Record<string, unknown> | string }
MALLPIE_GET_EVENTS: { type: 'MALLPIE_GET_EVENTS', callbackName: '...' }

SDK는 allowedOrigins(및 Shop 기반 기본 origin)을 기준으로 event.origin을 확인한 뒤, iframe/popup의 올바른 event.source에서 온 메시지만 처리합니다.

9. 내부 스토리지

SDK는 localStorage를 사용하여 데이터를 저장합니다. 모든 키는 MallpieSDK_Storage_ 접두사를 사용합니다.

tracking_uuid: 세션 추적용 UUID (영구 보관)
shop_id: 조회한 Shop ID (24시간 캐시)
tracking_event: 누적 추적 이벤트 배열

10. 주의사항

해당 웹 SDK를 통해서는 ADID를 직접 수집할 수 없으므로, 개인화 상품 추천이 필요하신 경우 제휴사에서 해당 정보를 별도로 제공해주셔야 합니다.
start() 사용 시 브라우저 팝업 차단이 활성화되어 있으면 창이 열리지 않고 E300 에러가 발생합니다.
iframe 내부 Mallpie 페이지도 window.parent.postMessage()를 지원해야 브릿지 기능이 완전히 동작합니다.
file://로 열지 말고 반드시 HTTP 서버로 테스트해야 합니다.

Last updated 6 months ago