> For the complete documentation index, see [llms.txt](https://help-partner.mallpie.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help-partner.mallpie.kr/api/sdk/web-sdk.md).

# WEB SDK 연동 가이드

## 라이브 데모

* **Playground**: [Mallpie Web SDK Playground →](https://ad.mallpie.co.kr/cps/prd/sdk/index.html)
* **설명**: CDN에서 SDK를 로드한 뒤 `initialize` · `start` · `mount` 등을 브라우저에서 바로 실행·검증할 수 있습니다.

## 1. 개요

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

핵심 포인트:

* `window.MallpieSDK`가 직접 정의됩니다.
* [`https://ad.mallpie.co.kr/cps/prd/sdk/index.global.js`](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. 로딩 파일

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

## 3. script 방식 사용 예시

```html
<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. 자동 초기화 방식

```html
<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. 정상 동작 확인 포인트

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

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

## 6. `initialize(options)` 옵션

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

```html
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`

&#x20;   <sub><mark style="color:$danger;">**※ adid :**<mark style="color:$danger;"></sub> <sub><mark style="color:$danger;">**Android: Google Advertising ID (GAID) /**<mark style="color:$danger;"></sub> <sub><mark style="color:$danger;">**iOS: Identifier for Advertisers (IDFA)**<mark style="color:$danger;"></sub>

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