@vircle/sdk-web 0.2.0

package/README.md

@@ -0,0 +1,598 @@
+# @vircle/sdk-web
+
+VircleCore를 확장하여 웹 환경에 특화된 기능을 제공하는 웹 애플리케이션용 Vircle Analytics SDK입니다. 자동 추적, 브라우저 컨텍스트 수집, 웹 스토리지 지원 등 웹 환경에 최적화된 기능을 제공합니다.
+
+## 🚀 주요 기능
+
+### 핵심 기능
+- **VircleCore 상속**: 코어 SDK의 모든 기능 + 웹 특화 기능
+- **자동 추적**: 페이지뷰, 클릭, 폼 제출, JavaScript 에러 자동 감지
+- **SPA 지원**: History API 래핑으로 라우트 변경 감지
+- **웹 컨텍스트 수집**: 브라우저, OS, 디바이스, UTM 파라미터 등
+
+### 성능 최적화
+- **requestIdleCallback**: UI 블로킹 없는 백그라운드 처리
+- **컨텍스트 캐싱**: 반복적인 DOM 접근 방지
+- **LocalStorage**: 영속적 데이터 저장 및 LRU 캐시 정리
+- **이벤트 배칭**: 네트워크 요청 최소화
+
+### 보안 및 프라이버시
+- **페이로드 암호화**: 하이브리드 암호화 (AES-256-GCM + RSA-OAEP)
+- **추적 제외**: data-vircle-ignore 속성으로 민감 정보 보호
+- **안전한 에러 처리**: SDK 안정성을 위한 모든 외부 API 호출 보호
+
+## 설치
+
+```bash
+npm install @vircle/sdk-web
+# 또는
+yarn add @vircle/sdk-web
+# 또는
+pnpm add @vircle/sdk-web
+```
+
+## 예제 실행
+
+```bash
+# 저장소 클론 후
+cd packages/sdk-web
+
+# 의존성 설치 및 빌드
+pnpm install
+pnpm build
+
+# 예제 서버 실행
+pnpm example
+
+# 브라우저에서 http://localhost:3000 접속
+```
+
+## 📖 빠른 시작
+
+### 기본 사용법
+
+```typescript
+import { VircleWeb } from '@vircle/sdk-web';
+
+// SDK 초기화 (VircleCore 설정 + 웹 전용 설정)
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    environment: 'production', // 'development' | 'production'
+    
+    // 배치 처리 설정 (VircleCore 기능)
+    batch: {
+        size: 20,              // 배치당 이벤트 수
+        timeout: 5000,         // 대기 시간 (ms)
+        flushInterval: 10000,  // 자동 플러시 간격
+    },
+    
+    // 웹 전용 자동 추적 설정
+    autoTrack: {
+        pageView: true,
+        clicks: true,
+        forms: true,
+        errors: true,
+    },
+}, {
+    // 웹 전용 옵션
+    enableEncryption: true,     // 페이로드 암호화
+    flushOnUnload: true,        // 페이지 이탈 시 전송
+    contextCacheTime: 300000,   // 컨텍스트 캐싱 시간
+});
+
+// SDK 초기화 필수!
+await vircle.initialize();
+
+// 커스텀 이벤트 추적
+await vircle.track('button_clicked', {
+    button_id: 'purchase',
+    value: 99.99,
+});
+
+// 사용자 식별 (identify 이벤트로 서버 전송)
+await vircle.identify('user-123', {
+    email: 'user@example.com',
+    name: '홍길동',
+});
+```
+
+### ES Modules (브라우저)
+
+```html
+<!-- 방법1: CDN 사용 (standalone 빌드 - 모든 의존성 포함) -->
+<script type="module">
+    import { VircleWeb } from 'https://cdn.jsdelivr.net/npm/@vircle/sdk-web/dist/vircle-web-sdk.standalone.esm.js';
+
+    const vircle = new VircleWeb({
+        apiKey: 'your-api-key',
+        environment: 'production', // 'development' | 'production'
+        autoTrack: {
+            pageView: true,
+            clicks: true,
+        },
+    });
+
+    await vircle.initialize();
+</script>
+
+<!-- 방법2: 로컬 파일 사용 -->
+<script type="module" src="/dist/vircle-web-sdk.standalone.esm.js"></script>
+```
+
+### UMD (레거시 지원)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@vircle/sdk-web/dist/vircle-web-sdk.min.js"></script>
+<script>
+    const vircle = new VircleWebSDK.VircleWeb({
+        apiKey: 'your-api-key',
+    });
+
+    vircle.initialize().then(() => {
+        console.log('SDK 초기화 완료');
+    });
+</script>
+```
+
+## 🏗️ 아키텍처
+
+```
+┌────────────────────────────────────────────┐
+│                  VircleWeb                 │
+│         (VircleCore 상속 + 웹 전용 기능)       │
+├────────────────────────────────────────────┤
+│  • 자동 추적 시스템 (setupAutoTracking)        │
+│  • 웹 컨텍스트 수집 (WebContextCollector)      │
+│  • LocalStorage 어댑터                       │
+│  • 브라우저 이벤트 핸들러                        │
+└────────────────────┬───────────────────────┘
+                     │ extends
+┌────────────────────┴───────────────────────┐
+│                 VircleCore                 │
+│    (이벤트 처리, 전송, 플러그인, 암호화 등)        │
+└────────────────────────────────────────────┘
+```
+
+## 🔍 웹 전용 기능 상세
+
+### 자동 추적 시스템
+
+SDK는 `setupAutoTracking` 메서드를 통해 다양한 브라우저 이벤트를 자동으로 추적합니다:
+
+#### 페이지뷰 추적
+- **초기 로드**: 페이지 첫 로드 시 자동 추적
+- **SPA 라우트 변경**: History API (`pushState`, `replaceState`) 래핑
+- **브라우저 네비게이션**: `popstate` 이벤트 감지
+- **추적 데이터**: URL, 제목, 리퍼러, UTM 파라미터
+
+#### 클릭 추적
+- **전역 이벤트 위임**: `document`에 단일 리스너로 모든 클릭 감지
+- **요소 정보 수집**: 태그명, 텍스트, 클래스, ID
+- **추적 제외**: `data-vircle-ignore` 속성으로 민감 요소 제외
+
+#### 폼 제출 추적
+- **자동 감지**: 모든 `form` 태그의 `submit` 이벤트
+- **수집 정보**: 폼 ID, action, method
+- **보안**: 폼 데이터는 수집하지 않음
+
+#### 에러 추적
+- **JavaScript 에러**: `window.onerror` 이벤트
+- **Promise 거부**: `unhandledrejection` 이벤트
+- **에러 정보**: 메시지, 스택, 파일명, 라인 번호
+
+### 웹 컨텍스트 수집 (WebContextCollector)
+
+자동으로 수집되는 브라우저 환경 정보:
+
+```typescript
+{
+  device: {
+    type: 'desktop',              // mobile | tablet | desktop
+    browser: 'Chrome',            // 브라우저 이름
+    browserVersion: '120.0.0',    // 브라우저 버전
+    os: 'macOS',                  // 운영체제
+    osVersion: '14.0',            // OS 버전
+    screenWidth: 1920,            // 화면 너비
+    screenHeight: 1080,           // 화면 높이
+    viewportWidth: 1200,          // 뷰포트 너비
+    viewportHeight: 800,          // 뷰포트 높이
+    language: 'ko-KR',            // 언어
+    timezone: 'Asia/Seoul'        // 타임존
+  },
+  page: {
+    url: 'https://example.com/products?category=electronics',
+    title: '제품 목록',
+    path: '/products',
+    search: '?category=electronics',
+    hash: '',
+    referrer: 'https://google.com'
+  },
+  custom: {
+    utm_source: 'google',
+    utm_medium: 'cpc',
+    utm_campaign: 'summer_sale',
+    cookiesEnabled: true,
+    network: {
+      effectiveType: '4g',
+      downlink: 10.0
+    }
+  }
+}
+```
+
+### LocalStorage 어댑터
+
+웹 브라우저의 LocalStorage를 활용한 데이터 영속성:
+
+- **자동 용량 관리**: QuotaExceededError 시 LRU 캐시 정리
+- **접두사 격리**: `vircle_` 접두사로 다른 데이터와 분리
+- **타임스탬프 추적**: 데이터 저장 시간 기록
+- **안전한 폴백**: LocalStorage 불가 시 경고 후 계속 작동
+
+### 성능 최적화 기술
+
+- **requestIdleCallback 활용**: UI 블로킹 없는 백그라운드 이벤트 처리
+- **컨텍스트 캐싱**: 브라우저 정보 캐싱으로 반복적 DOM 접근 방지
+- **이벤트 배칭**: TransportService의 큐를 통한 네트워크 요청 최소화
+- **메모리 관리**: cleanup 시 모든 이벤트 리스너 제거로 누수 방지
+
+### 추적 제외
+
+특정 요소나 영역을 추적에서 제외하려면 `data-vircle-ignore` 속성을 사용하세요:
+
+```html
+<!-- 이 버튼은 클릭 추적에서 제외됩니다 -->
+<button data-vircle-ignore>추적 제외 버튼</button>
+
+<!-- 이 영역 내의 모든 요소가 추적에서 제외됩니다 -->
+<div data-vircle-ignore>
+    <button>추적 안됨</button>
+    <a href="#">이 링크도 추적 안됨</a>
+</div>
+```
+
+## 설정 옵션
+
+### VircleWebConfig
+
+```typescript
+interface VircleWebConfig {
+    apiKey: string; // 필수: API 키
+    endpoint?: string; // API 엔드포인트 (선택)
+    trackPageViews?: boolean; // 페이지뷰 자동 추적 (기본: false)
+    trackClicks?: boolean; // 클릭 자동 추적 (기본: false)
+    trackForms?: boolean; // 폼 제출 자동 추적 (기본: false)
+    trackErrors?: boolean; // 에러 자동 추적 (기본: false)
+    singlePageApp?: boolean; // SPA 모드 (기본: false)
+    storagePrefix?: string; // 스토리지 키 접두사 (기본: 'vircle_')
+}
+```
+
+### VircleWebOptions
+
+```typescript
+interface VircleWebOptions {
+    flushOnUnload?: boolean; // 페이지 언로드 시 이벤트 전송 (기본: true)
+    contextCacheTime?: number; // 컨텍스트 캐시 시간(ms) (기본: 300000)
+    enablePerformance?: boolean; // 성능 측정 활성화 (기본: true)
+}
+```
+
+## API 레퍼런스
+
+### 초기화
+
+```typescript
+await vircle.initialize(): Promise<void>
+```
+
+SDK를 초기화하고 자동 추적을 시작합니다.
+
+### 이벤트 추적
+
+```typescript
+await vircle.track(
+  eventName: string,
+  properties?: Record<string, unknown>,
+  context?: EventContext
+): Promise<void>
+```
+
+커스텀 이벤트를 추적합니다.
+
+### 페이지뷰 추적
+
+```typescript
+await vircle.trackPageView(
+  properties?: Record<string, unknown>,
+  context?: EventContext
+): Promise<void>
+```
+
+페이지뷰를 수동으로 추적합니다.
+
+### 사용자 식별
+
+```typescript
+await vircle.identify(
+  userId: string,
+  traits?: UserProperties
+): Promise<void>
+```
+
+사용자를 식별하고 속성을 설정합니다.
+
+### 사용자 리셋
+
+```typescript
+await vircle.reset(): Promise<void>
+```
+
+사용자 정보를 초기화합니다.
+
+### 정리
+
+```typescript
+await vircle.cleanup(): Promise<void>
+```
+
+모든 이벤트 리스너를 제거하고 리소스를 정리합니다.
+
+## 빌드 파일 설명
+
+| 파일 | 용도 | 의존성 | 사용 방법 |
+|------|------|--------|-----------|
+| `dist/index.js` | CommonJS (Node.js/번들러) | 별도 설치 필요 | `require('@vircle/sdk-web')` |
+| `dist/index.esm.js` | ES Modules (번들러) | 별도 설치 필요 | `import { VircleWeb } from '@vircle/sdk-web'` |
+| `dist/vircle-web-sdk.standalone.esm.js` | ES Modules (브라우저) | 모두 포함 ✅ | `<script type="module">` |
+| `dist/vircle-web-sdk.min.js` | UMD (레거시 브라우저) | 모두 포함 ✅ | `<script>` |
+
+⚠️ **중요**: 브라우저에서 직접 사용할 때는 반드시 `standalone` 또는 `min` 빌드를 사용하세요.
+
+## 브라우저 지원
+
+- Chrome/Edge: 최신 2개 버전
+- Firefox: 최신 2개 버전
+- Safari: 최신 2개 버전
+- iOS Safari: iOS 12+
+- Chrome for Android: Android 6+
+
+## 보안 고려사항
+
+1. **클라이언트 측 API 키**: 브라우저에서 사용되는 API 키는 공개됩니다. 데이터 수집(Write) 권한만 가진 키를 사용하세요.
+
+2. **민감한 데이터**: 민감한 데이터가 수집되지 않도록 `data-vircle-ignore` 속성을 적절히 사용하세요.
+
+3. **LocalStorage**: SDK는 LocalStorage를 사용하여 데이터를 임시 저장합니다. 민감한 정보는 저장하지 않습니다.
+
+## 성능 영향
+
+- **번들 크기**: ~13.5KB (minified), ~4.5KB (gzipped)
+- **초기화 시간**: < 10ms
+- **이벤트 추적**: < 1ms (requestIdleCallback 사용)
+
+## 고급 사용 예제
+
+### SPA (Single Page Application) 설정
+
+```typescript
+const vircle = new VircleWeb({
+  apiKey: 'your-api-key',
+  singlePageApp: true,  // SPA 모드 활성화
+  trackPageViews: true
+})
+
+await vircle.initialize()
+
+// React Router 예제
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+
+function App() {
+  const location = useLocation()
+
+  useEffect(() => {
+    // 라우트 변경 시 자동으로 페이지뷰가 추적됩니다
+  }, [location])
+
+  return <Routes>...</Routes>
+}
+```
+
+### 에러 처리와 함께 사용
+
+```typescript
+try {
+    const vircle = new VircleWeb({
+        apiKey: 'your-api-key',
+        trackErrors: false, // 자동 에러 추적 비활성화
+    });
+
+    await vircle.initialize();
+
+    // 수동으로 에러 추적
+    try {
+        await riskyOperation();
+    } catch (error) {
+        await vircle.track('error', {
+            message: error.message,
+            stack: error.stack,
+            component: 'PaymentForm',
+        });
+        throw error;
+    }
+} catch (error) {
+    console.error('SDK 초기화 실패:', error);
+}
+```
+
+### 성능 최적화 설정
+
+```typescript
+const vircle = new VircleWeb(
+    {
+        apiKey: 'your-api-key',
+        trackPageViews: true,
+        trackClicks: true,
+    },
+    {
+        contextCacheTime: 600000, // 10분 캐싱
+        flushOnUnload: false, // 수동으로 flush 관리
+        enablePerformance: false, // 성능 추적 비활성화
+    },
+);
+
+// 중요한 시점에 수동으로 flush
+window.addEventListener('beforeunload', async () => {
+    await vircle.flush();
+});
+```
+
+### 민감한 정보가 있는 페이지
+
+```html
+<!-- 개인정보가 포함된 대시보드 -->
+<div class="user-dashboard">
+    <!-- 사용자 정보는 추적에서 제외 -->
+    <h1 data-vircle-ignore>안녕하세요, 김철수님!</h1>
+
+    <!-- 계좌 정보는 추적에서 완전 제외 -->
+    <div data-vircle-ignore>
+        <p>계좌번호: 123-456-789</p>
+        <p>잔액: ₩1,234,567</p>
+        <button>송금하기</button>
+    </div>
+
+    <!-- 일반 액션은 추적 -->
+    <button>프로필 수정</button>
+</div>
+```
+
+### 동적 컨텍스트 추가
+
+```typescript
+// 글로벌 컨텍스트 설정
+vircle.setContext({
+    app: {
+        version: '2.1.0',
+        environment: 'production',
+    },
+    custom: {
+        experiment_id: 'exp_123',
+        feature_flags: {
+            new_ui: true,
+            beta_features: false,
+        },
+    },
+});
+
+// 특정 이벤트에만 컨텍스트 추가
+await vircle.track(
+    'purchase_completed',
+    {
+        product_id: 'sku_123',
+        price: 49.99,
+    },
+    {
+        custom: {
+            payment_method: 'card',
+            coupon_used: true,
+        },
+    },
+);
+```
+
+## 문제 해결
+
+### SDK가 초기화되지 않음
+
+```typescript
+// 상태 확인
+const status = vircle.getStatus();
+console.log('SDK 초기화 상태:', status.isInitialized);
+
+// 네트워크 상태 확인
+console.log('온라인 상태:', vircle.isOnline());
+```
+
+### 이벤트가 전송되지 않음
+
+```typescript
+// 디버그 모드로 재초기화
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    debug: true, // 콘솔에 디버그 로그 출력
+});
+
+// 수동으로 이벤트 플러시
+await vircle.flush();
+```
+
+### 메모리 누수 방지
+
+```typescript
+// 컴포넌트 언마운트 시 반드시 cleanup 호출
+// React 예제
+useEffect(() => {
+    const vircle = new VircleWeb({ apiKey: 'your-api-key' });
+    vircle.initialize();
+
+    return () => {
+        vircle.cleanup();
+    };
+}, []);
+```
+
+## TypeScript 지원
+
+SDK는 완전한 TypeScript 타입 정의를 제공합니다:
+
+```typescript
+import { VircleWeb, VircleWebConfig, VircleWebOptions, EventContext, UserProperties } from '@vircle/sdk-web';
+
+// 타입 안전한 설정
+const config: VircleWebConfig = {
+    apiKey: process.env.VIRCLE_API_KEY!,
+    trackPageViews: true,
+    trackErrors: true,
+};
+
+const options: VircleWebOptions = {
+    contextCacheTime: 300000,
+    flushOnUnload: true,
+};
+
+const vircle = new VircleWeb(config, options);
+
+// 타입 안전한 이벤트 추적
+interface PurchaseEvent {
+    product_id: string;
+    price: number;
+    currency: string;
+    quantity: number;
+}
+
+await vircle.track<PurchaseEvent>('purchase', {
+    product_id: 'sku_123',
+    price: 49.99,
+    currency: 'USD',
+    quantity: 1,
+});
+
+// 타입 안전한 사용자 속성
+interface UserTraits extends UserProperties {
+    email: string;
+    plan: 'free' | 'pro' | 'enterprise';
+    created_at: string;
+}
+
+await vircle.identify<UserTraits>('user-123', {
+    email: 'user@example.com',
+    plan: 'pro',
+    created_at: new Date().toISOString(),
+});
+```
+
+## 라이선스
+
+MIT