@vircle/plugin-ecommerce-core

커머스 플랫폼 플러그인을 위한 기반 클래스와 유틸리티를 제공하는 패키지입니다. 플랫폼별 플러그인(Cafe24, Shopify 등)은 이 패키지를 확장하여 구현합니다.

설치

pnpm add @vircle/plugin-ecommerce-core

구성 요소

BaseEcommercePlugin

모든 커머스 플러그인의 추상 기반 클래스입니다. VirclePlugin 인터페이스를 구현하며, 다음 기능을 제공합니다:

• 네트워크 요청 인터셉션 (fetch/XHR)
• History API 기반 페이지 네비게이션 추적
• 이벤트 중복 방지 (deduplication)
• 플랫폼 메타데이터 자동 첨부
• globalProperties — 모든 이벤트에 자동 병합되는 글로벌 프로퍼티 (크로스 도메인 어트리뷰션 등)
• UTM / 캠페인 파라미터 자동 수집 (utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid, msclkid, ttclid)

import { BaseEcommercePlugin, EcommerceEvent, type NetworkPattern, type PlatformAdapter } from '@vircle/plugin-ecommerce-core';

class MyPlatformPlugin extends BaseEcommercePlugin {
    readonly name = 'my-platform';
    readonly version = '1.0.0';
    readonly description = 'My platform tracking plugin';

    protected getNetworkPatterns(): NetworkPattern[] {
        return [
            { pattern: '/api/cart/add', method: 'POST', event: EcommerceEvent.PRODUCT_ADDED_TO_CART },
        ];
    }

    protected createAdapter(): PlatformAdapter {
        return new MyPlatformAdapter();
    }

    protected handleNetworkRequest(url: string, method: string, body?: any): void {
        // 인터셉트된 네트워크 요청 처리
    }
}

NetworkInterceptor

window.fetch와 XMLHttpRequest를 패치하여 특정 URL 패턴에 매칭되는 네트워크 요청/응답을 인터셉트합니다.

import { NetworkInterceptor, type NetworkPattern } from '@vircle/plugin-ecommerce-core';

const patterns: NetworkPattern[] = [
    { pattern: '/api/cart', method: 'POST', event: EcommerceEvent.PRODUCT_ADDED_TO_CART },
    { pattern: /\/api\/order\/\d+/, event: EcommerceEvent.ORDER_COMPLETED },
];

const interceptor = new NetworkInterceptor(patterns, {
    onRequest: (url, method, body) => { /* 요청 감지 */ },
    onResponse: (url, status, body) => { /* 응답 감지 */ },
});

interceptor.start();
// ...
interceptor.stop(); // 원본 함수 복원

PlatformAdapter

플랫폼별 데이터 추출 계약을 정의하는 인터페이스입니다:

interface PlatformAdapter {
    readonly name: string;
    initialize(config: EcommercePluginConfig, context: PluginContext): void;
    cleanup(): void;
    detectPageType(): PageType;
    extractProduct(): Product | null;
    extractCartItems(): CartItem[];
    extractOrder(): OrderData | null;
    getPlatformMeta(): Record<string, any>;
}

이벤트 타입

enum EcommerceEvent {
    PAGE_VIEWED              // 페이지 조회
    PRODUCT_VIEWED           // 상품 상세 조회
    PRODUCT_ADDED_TO_CART    // 장바구니 추가
    PRODUCT_REMOVED_FROM_CART // 장바구니 제거
    CART_VIEWED              // 장바구니 조회
    CART_UPDATED             // 장바구니 수량 변경
    PRODUCT_ADDED_TO_WISHLIST // 위시리스트 추가
    CHECKOUT_STARTED         // 주문서 진입
    EXTERNAL_PAYMENT_INITIATED // 외부 결제 시작
    ORDER_COMPLETED          // 주문 완료
}

데이터 타입

| 타입 | 설명 | |------|------| | Product | 상품 정보 (product_id, name, price, sku, ...) | | CartItem | 장바구니 아이템 (Product + quantity) | | OrderItem | 주문 아이템 (Product + quantity + item_total) | | OrderData | 주문 데이터 (order_id, total, items, ...) |

설정

interface EcommercePluginConfig {
    trackPageViews?: boolean;        // 페이지뷰 자동 추적 (기본: true)
    trackNetworkRequests?: boolean;  // 네트워크 인터셉션 (기본: true)
    trackDomInteractions?: boolean;  // DOM 인터랙션 추적 (기본: true)
    deduplicationWindow?: number;    // 중복 방지 윈도우 ms (기본: 2000)
    debug?: boolean;                 // 디버그 로그 (기본: false)
}

새 플랫폼 플러그인 만들기

1. BaseEcommercePlugin을 상속
2. PlatformAdapter를 구현하여 플랫폼별 데이터 추출 로직 작성
3. getNetworkPatterns()에서 인터셉트할 API URL 패턴 반환
4. handleNetworkRequest()에서 인터셉트된 요청을 이벤트로 변환

참조 구현: @vircle/plugin-cafe24