@vircle/plugin-cafe24

Cafe24 쇼핑몰에서 행동 데이터를 자동 수집하는 Vircle SDK 플러그인입니다. 스크립트 하나만 설치하면 상품 조회, 장바구니, 주문 완료 등 주요 커머스 이벤트를 자동으로 추적합니다.

설치

NPM

pnpm add @vircle/plugin-cafe24

import { VircleWeb } from '@vircle/sdk-web';
import { createCafe24Plugin } from '@vircle/plugin-cafe24';

const vircle = new VircleWeb({
    apiKey: 'your-api-key',
    plugins: [createCafe24Plugin()],
});

await vircle.initialize();

Cafe24Plugin은 브라우저 API(window, document, fetch, History API)를 사용하므로 @vircle/sdk-web의 VircleWeb과 함께 사용해야 합니다.

CDN (Script 태그)

Cafe24 관리자 > 쇼핑몰관리 > 기본설정 > 검색엔진최적화(SEO) > 고급 설정 > 코드 직접입력 > body 영역에 추가:

<script src="https://static.vircle.co.kr/sdk/v1/js/cafe24-loader.min.js?apiKey=your-api-key"></script>

로더 스크립트가 SDK와 플러그인을 자동으로 로드하고 초기화합니다.

<script src="https://static.vircle.co.kr/sdk/v1/js/vircle-web-sdk.min.js"></script>
<script src="https://static.vircle.co.kr/sdk/v1/js/vircle-cafe24-plugin.min.js"></script>
<script>
    var vircle = new VircleWebSDK({ apiKey: 'your-api-key' });
    var cafe24Plugin = VircleCafe24Plugin.createCafe24Plugin();
    vircle.registerPlugin(cafe24Plugin);
    vircle.initialize();
</script>

자동 수집 이벤트

| 이벤트 | 트리거 | 데이터 소스 | |--------|--------|------------| | page_viewed | 페이지 전환 (History API) | location.href, document.title | | product_viewed | 상품 상세 페이지 진입 | window.iProductNo, product_name, product_price | | product_added_to_cart | 장바구니 추가 (API 또는 form submit) | /exec/front/cart/Cart/AddProduct 인터셉트 | | product_removed_from_cart | 장바구니 삭제 (API 또는 form submit) | /exec/front/cart/Cart/DeleteProduct 인터셉트 | | cart_updated | 장바구니 수량 변경 (API 또는 form submit) | /exec/front/cart/Cart/UpdateProduct 인터셉트 | | cart_viewed | 장바구니 페이지 진입 | window.aBasketProductData | | product_added_to_wishlist | 위시리스트 추가 API 호출 | /exec/front/Wish/WishProduct/Add 인터셉트 | | checkout_started | 주문서 페이지 진입 | 장바구니 데이터 | | order_completed | 주문 완료 페이지 진입 | EC_FRONT_EXTERNAL_SCRIPT_VARIABLE_DATA | | external_payment_initiated | 네이버페이/카카오페이 버튼 클릭 | 버튼 클릭 이벤트 리스너 |

설정

createCafe24Plugin({
    // EcommercePluginConfig
    trackPageViews: true,          // 페이지뷰 자동 추적 (기본: true)
    trackNetworkRequests: true,    // 네트워크 인터셉션 (기본: true)
    deduplicationWindow: 2000,     // 중복 방지 윈도우 ms (기본: 2000)

    // Cafe24PluginConfig
    trackExternalPayments: true,   // 네이버페이/카카오페이 추적 (기본: true)
});

크로스 도메인 어트리뷰션

버클 사이트에서 Cafe24 쇼핑몰로 이동할 때 _vuid 쿼리 파라미터로 사용자를 연결합니다.

버클 사이트 → https://shop.cafe24.com/product/detail.html?_vuid={anonymousId}

• _vuid 파라미터가 있으면 sessionStorage에 저장하고 모든 이벤트의 properties._vuid에 자동 첨부
• MPA 페이지 전환 간 sessionStorage로 유지
• 버클 사이트에서 vircle.getAnonymousId()로 값을 가져와 링크에 첨부

자동 수집 사용자 식별자

| 식별자 | 수집 위치 | 설명 | |--------|-----------|------| | _vuid | 모든 페이지 (URL 파라미터 유입 시) | 버클 사이트 anonymousId | | cafe24_member_id | 모든 페이지 (로그인 시) | common_member_id_crypt 암호화 회원 ID | | cafe24_member_id_plain | 주문 완료 페이지 | EC_FRONT_EXTERNAL_SCRIPT_VARIABLE_DATA.member_id 실제 회원 ID |

UTM / 캠페인 파라미터 자동 수집

BaseEcommercePlugin이 URL의 캠페인 파라미터를 자동으로 수집하여 모든 이벤트에 첨부합니다.

• UTM: utm_source, utm_medium, utm_campaign, utm_term, utm_content
• 광고 ID: gclid (Google), fbclid (Facebook), msclkid (Microsoft), ttclid (TikTok)
• sessionStorage에 저장하여 MPA 페이지 전환 간 유지
• 새 캠페인 유입 시 기존 값을 클리어하고 새로 저장

데이터 추출 방식

상품 정보 (ProductExtractor)

2단계 Fallback:

1. Cafe24 전역 변수: window.iProductNo, window.product_name, window.product_price
2. DOM 파싱: .xans-product-detail 내부 요소

장바구니 (CartExtractor)

• 페이지 데이터: window.aBasketProductData 전역 배열
• API 요청: 네트워크 인터셉트로 form-encoded body 파싱

주문 완료 (OrderExtractor)

• EC_FRONT_EXTERNAL_SCRIPT_VARIABLE_DATA 전역 변수에서 주문 ID, 총액, 상품 목록 추출

페이지 타입 감지

URL 패턴 매칭을 우선 사용하고, 실패 시 DOM 셀렉터 기반 감지로 Fallback합니다:

| 페이지 | URL 패턴 | DOM 셀렉터 | |--------|---------|-----------| | 상품 상세 | /product/*detail.html | .xans-product-detail | | 상품 목록 | /product/*list.html | .xans-product-listnormal | | 장바구니 | /order/basket.html | .xans-order-basketpackage | | 주문서 | /order/orderform.html | .xans-order-orderform | | 주문 완료 | /order/order_result.html | .xans-order-result | | 검색 결과 | /product/search.html | .xans-search-result |

빌드 출력

| 파일 | 포맷 | 용도 | |------|------|------| | dist/index.js | CJS | Node.js / SSR | | dist/index.esm.js | ESM | 번들러 (Webpack, Vite) | | dist/vircle-cafe24-plugin.min.js | UMD | CDN <script> 태그 (~5KB gzipped) | | dist/cafe24-loader.min.js | IIFE | 1줄 설치용 로더 스크립트 (~0.5KB gzipped) | | dist/index.d.ts | TypeScript 선언 | 타입 지원 |

UMD 빌드는 전역 변수 VircleCafe24Plugin으로 접근할 수 있습니다. @vircle/plugin-ecommerce-core 의존성은 번들에 포함되어 있지만, @vircle/sdk-web의 UMD 스크립트(vircle-web-sdk.min.js)를 먼저 로드해야 합니다.

아키텍처

Cafe24Plugin (BaseEcommercePlugin 상속)
├── Cafe24Adapter (PlatformAdapter 구현)
│   ├── ProductExtractor    — 상품 데이터 추출
│   ├── CartExtractor       — 장바구니 데이터 추출
│   └── OrderExtractor      — 주문 데이터 추출
├── NetworkInterceptor      — fetch/XHR API 인터셉트
├── Form Submit Interception — form submit 기반 장바구니 조작 감지
├── External Payment Track  — 네이버페이/카카오페이 버튼 감지
└── Cross-domain Attribution — _vuid 파라미터 + cafe24_member_id 수집