@vircle/sdk-web 0.2.0 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
 # @vircle/sdk-web
 
-VircleCore를 확장하여 웹 환경에 특화된 기능을 제공하는 웹 애플리케이션용 Vircle Analytics SDK입니다. 자동 추적, 브라우저 컨텍스트 수집, 웹 스토리지 지원 등 웹 환경에 최적화된 기능을 제공합니다.
+VircleCore를 확장하여 웹 환경에 특화된 기능을 제공하는 웹 애플리케이션용 Vircle Analytics SDK입니다. 자동 추적, 브라우저 컨텍스트 수집, 웹 스토리지 지원, 하이브리드 암호화 등 웹 환경에 최적화된 기능을 제공합니다.
 
-## 🚀 주요 기능
+## 주요 기능
 
 ### 핵심 기능
 - **VircleCore 상속**: 코어 SDK의 모든 기능 + 웹 특화 기능
@@ -13,13 +13,19 @@ VircleCore를 확장하여 웹 환경에 특화된 기능을 제공하는 웹
 ### 성능 최적화
 - **requestIdleCallback**: UI 블로킹 없는 백그라운드 처리
 - **컨텍스트 캐싱**: 반복적인 DOM 접근 방지
-- **LocalStorage**: 영속적 데이터 저장 및 LRU 캐시 정리
+- **스마트 스토리지**: IndexedDB/LocalStorage 자동 선택으로 대용량 데이터 지원
 - **이벤트 배칭**: 네트워크 요청 최소화
+- **큐 크기 제한**: TaskScheduler 큐 오버플로우 방지 (기본 1000)
+
+### 세션 관리
+- **세션 타임아웃**: 비활성 상태 감지 후 자동 세션 로테이션 (기본 30분)
+- **sendBeacon**: 페이지 종료 시 이벤트 손실 방지
 
 ### 보안 및 프라이버시
-- **페이로드 암호화**: 하이브리드 암호화 (AES-256-GCM + RSA-OAEP)
+- **페이로드 암호화**: Web Crypto API 기반 하이브리드 암호화 (AES-256-GCM + RSA-OAEP)
 - **추적 제외**: data-vircle-ignore 속성으로 민감 정보 보호
 - **안전한 에러 처리**: SDK 안정성을 위한 모든 외부 API 호출 보호
+- **전용 에러 클래스**: 상세한 에러 코드 및 디버깅 정보 제공
 
 ## 설치
 
@@ -33,21 +39,25 @@ pnpm add @vircle/sdk-web
 
 ## 예제 실행
 
+예제는 `packages/demo-web` 디렉토리에서 확인할 수 있습니다:
+
 ```bash
 # 저장소 클론 후
-cd packages/sdk-web
+cd packages/demo-web
 
-# 의존성 설치 및 빌드
-pnpm install
-pnpm build
+# ESM 예제
+open esm/index.html
 
-# 예제 서버 실행
-pnpm example
+# React 예제
+cd react && pnpm install && pnpm start
 
-# 브라우저에서 http://localhost:3000 접속
+# Next.js 예제
+cd nextjs && pnpm install && pnpm dev
 ```
 
-## 📖 빠른 시작
+자세한 내용은 [demo-web README](../demo-web/README.md)를 참조하세요.
+
+## 빠른 시작
 
 ### 기본 사용법
 
@@ -57,27 +67,32 @@ import { VircleWeb } from '@vircle/sdk-web';
 // SDK 초기화 (VircleCore 설정 + 웹 전용 설정)
 const vircle = new VircleWeb({
     apiKey: 'your-api-key',
-    environment: 'production', // 'development' | 'production'
-    
+    environment: 'production',
+
     // 배치 처리 설정 (VircleCore 기능)
     batch: {
-        size: 20,              // 배치당 이벤트 수
-        timeout: 5000,         // 대기 시간 (ms)
-        flushInterval: 10000,  // 자동 플러시 간격
+        size: 50,           // 기본값: 50
+        timeout: 5000,      // 기본값: 5000ms
+        flushInterval: 10000, // 기본값: 10000ms
     },
-    
+
     // 웹 전용 자동 추적 설정
-    autoTrack: {
-        pageView: true,
-        clicks: true,
-        forms: true,
-        errors: true,
-    },
+    trackPageViews: true,
+    trackClicks: true,
+    trackForms: true,
+    trackErrors: true,
+    singlePageApp: true,
+
+    // 암호화 활성화
+    enableEncryption: true,
+
+    // 스토리지 설정
+    storageType: 'auto',
+    storagePrefix: 'vircle_',
 }, {
     // 웹 전용 옵션
-    enableEncryption: true,     // 페이로드 암호화
-    flushOnUnload: true,        // 페이지 이탈 시 전송
-    contextCacheTime: 300000,   // 컨텍스트 캐싱 시간
+    flushOnUnload: true,
+    contextCacheTime: 300000,
 });
 
 // SDK 초기화 필수!
@@ -105,11 +120,9 @@ await vircle.identify('user-123', {
 
     const vircle = new VircleWeb({
         apiKey: 'your-api-key',
-        environment: 'production', // 'development' | 'production'
-        autoTrack: {
-            pageView: true,
-            clicks: true,
-        },
+        environment: 'production',
+        trackPageViews: true,
+        trackClicks: true,
     });
 
     await vircle.initialize();
@@ -124,7 +137,8 @@ await vircle.identify('user-123', {
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@vircle/sdk-web/dist/vircle-web-sdk.min.js"></script>
 <script>
-    const vircle = new VircleWebSDK.VircleWeb({
+    // UMD 빌드는 VircleWebSDK 전역 변수로 VircleWeb 클래스를 직접 노출합니다
+    const vircle = new VircleWebSDK({
         apiKey: 'your-api-key',
     });
 
@@ -134,26 +148,29 @@ await vircle.identify('user-123', {
 </script>
 ```
 
-## 🏗️ 아키텍처
+## 아키텍처
 
 ```
 ┌────────────────────────────────────────────┐
 │                  VircleWeb                 │
 │         (VircleCore 상속 + 웹 전용 기능)       │
 ├────────────────────────────────────────────┤
-│  • 자동 추적 시스템 (setupAutoTracking)        │
+│  • 자동 추적 (페이지뷰/클릭/폼/에러/SPA)       │
 │  • 웹 컨텍스트 수집 (WebContextCollector)      │
-│  • LocalStorage 어댑터                       │
-│  • 브라우저 이벤트 핸들러                        │
+│  • 세션 타임아웃 / 로테이션                      │
+│  • sendBeacon (페이지 이탈 보호)                │
+│  • StorageFactory (IndexedDB/LocalStorage) │
+│  • 하이브리드 암호화 (WebExtendedCryptoAdapter)│
+│  • 에러 클래스 (VircleWebError 계열)           │
 └────────────────────┬───────────────────────┘
                      │ extends
 ┌────────────────────┴───────────────────────┐
 │                 VircleCore                 │
-│    (이벤트 처리, 전송, 플러그인, 암호화 등)        │
+│  (이벤트/전송/플러그인/암호화/원격 설정/스토리지) │
 └────────────────────────────────────────────┘
 ```
 
-## 🔍 웹 전용 기능 상세
+## 웹 전용 기능 상세
 
 ### 자동 추적 시스템
 
@@ -168,73 +185,264 @@ SDK는 `setupAutoTracking` 메서드를 통해 다양한 브라우저 이벤트
 #### 클릭 추적
 - **전역 이벤트 위임**: `document`에 단일 리스너로 모든 클릭 감지
 - **요소 정보 수집**: 태그명, 텍스트, 클래스, ID
+- **추적 대상**: `A`, `BUTTON`, `INPUT`, `SELECT`, `TEXTAREA` 요소만 추적
 - **추적 제외**: `data-vircle-ignore` 속성으로 민감 요소 제외
+- **data-* 속성 수집**: idle 시간에 비동기로 추가 data 속성 수집
 
 #### 폼 제출 추적
 - **자동 감지**: 모든 `form` 태그의 `submit` 이벤트
-- **수집 정보**: 폼 ID, action, method
+- **수집 정보**: 폼 ID, name, action, method
 - **보안**: 폼 데이터는 수집하지 않음
 
 #### 에러 추적
-- **JavaScript 에러**: `window.onerror` 이벤트
-- **Promise 거부**: `unhandledrejection` 이벤트
-- **에러 정보**: 메시지, 스택, 파일명, 라인 번호
+- **JavaScript 에러**: `ErrorEvent` 리스너 (메시지, 파일명, 라인, 컬럼, 스택)
+- **Promise 거부**: `PromiseRejectionEvent` 리스너 (reason)
 
 ### 웹 컨텍스트 수집 (WebContextCollector)
 
-자동으로 수집되는 브라우저 환경 정보:
+`collect()` 호출 시 `device`, `page`, `app`, `custom` 4가지 컨텍스트를 **병렬로** 수집합니다.
+
+#### device (DeviceContext)
+
+User-Agent 기반 디바이스/브라우저/OS 감지 및 화면 정보 수집
+
+| 필드 | 타입 | 소스 | 설명 |
+|------|------|------|------|
+| `type` | `'mobile' \| 'tablet' \| 'desktop'` | `navigator.userAgent` | UA 패턴 매칭으로 판별 |
+| `os` | `string` | `navigator.userAgent` | Windows, macOS, Linux, Android, iOS, Chrome OS |
+| `osVersion` | `string \| undefined` | `navigator.userAgent` | OS 버전 (예: `14.0`) |
+| `browser` | `string` | `navigator.userAgent` | Edge, Chrome, Firefox, Safari, Opera, IE |
+| `browserVersion` | `string \| undefined` | `navigator.userAgent` | 브라우저 버전 (예: `120.0`) |
+| `screenResolution` | `string` | `screen.width/height` | `"1920x1080"` 형태 |
+| `viewport` | `{ width, height }` | `window.innerWidth/Height` | 현재 뷰포트 크기 |
+| `language` | `string` | `navigator.language` | 브라우저 언어 (예: `ko-KR`) |
+| `timezone` | `string` | `Intl.DateTimeFormat` | IANA 타임존 (예: `Asia/Seoul`) |
+
+#### page (PageContext)
+
+현재 페이지 URL 파싱 결과
+
+| 필드 | 타입 | 소스 | 설명 |
+|------|------|------|------|
+| `url` | `string` | `window.location.href` | 전체 URL |
+| `title` | `string` | `document.title` | 페이지 제목 |
+| `path` | `string` | `URL.pathname` | 경로 (예: `/products`) |
+| `search` | `string` | `URL.search` | 쿼리스트링 (예: `?category=electronics`) |
+| `hash` | `string` | `URL.hash` | 해시 프래그먼트 |
+
+#### app (AppContext)
+
+애플리케이션 메타 정보 (HTML meta 태그 기반)
+
+| 필드 | 타입 | 소스 | 설명 |
+|------|------|------|------|
+| `name` | `string` | `<meta name="application-name">` 또는 `<meta property="og:site_name">` 또는 `document.title` | 앱 이름 |
+| `version` | `string \| undefined` | `<meta name="version">` | 앱 버전 |
+| `environment` | `'development' \| 'production'` | `window.location.hostname` | localhost/staging → development, 그 외 → production |
+
+#### custom (Record<string, unknown>)
+
+추가 브라우저 환경 정보 (가용한 경우에만 수집)
+
+| 필드 | 타입 | 조건 | 설명 |
+|------|------|------|------|
+| `referrer` | `string` | `document.referrer` 존재 시 | 이전 페이지 URL |
+| `campaign` | `{ source, medium, campaign, term, content }` | URL에 `utm_*` 파라미터 존재 시 | UTM 캠페인 파라미터 (`utm_` 접두사 제거) |
+| `cookieEnabled` | `boolean` | 항상 | 쿠키 활성화 여부 |
+| `doNotTrack` | `boolean` | `navigator.doNotTrack` 존재 시 | DNT 설정 여부 |
+| `connection` | `{ effectiveType, downlink, rtt, saveData }` | Network Information API 지원 시 | 네트워크 연결 정보 |
+| `memory` | `{ usedJSHeapSize, totalJSHeapSize, jsHeapSizeLimit }` | `performance.memory` 지원 시 (Chrome 전용) | JS 힙 메모리 사용량 |
+
+#### 수집 결과 예시
 
 ```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'        // 타임존
+    type: 'desktop',
+    os: 'macOS',
+    osVersion: '14.0',
+    browser: 'Chrome',
+    browserVersion: '120.0',
+    screenResolution: '1920x1080',
+    viewport: { width: 1200, height: 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'
+    hash: ''
+  },
+  app: {
+    name: 'My Store',
+    version: '2.1.0',
+    environment: 'production'
   },
   custom: {
-    utm_source: 'google',
-    utm_medium: 'cpc',
-    utm_campaign: 'summer_sale',
-    cookiesEnabled: true,
-    network: {
+    referrer: 'https://google.com',
+    campaign: {
+      source: 'google',
+      medium: 'cpc',
+      campaign: 'summer_sale'
+    },
+    cookieEnabled: true,
+    doNotTrack: false,
+    connection: {
       effectiveType: '4g',
-      downlink: 10.0
+      downlink: 10.0,
+      rtt: 50,
+      saveData: false
+    },
+    memory: {
+      usedJSHeapSize: 12345678,
+      totalJSHeapSize: 33554432,
+      jsHeapSizeLimit: 2147483648
     }
   }
 }
 ```
 
-### LocalStorage 어댑터
+### 스토리지 어댑터
 
-웹 브라우저의 LocalStorage를 활용한 데이터 영속성:
+SDK는 `StorageFactory`를 통해 환경에 최적화된 스토리지를 자동 선택합니다:
 
+#### IndexedDB 어댑터 (권장)
+- **대용량 지원**: LocalStorage 5MB 제한 없이 대량 이벤트 저장
+- **비동기 처리**: UI 블로킹 없는 백그라운드 저장
+- **트랜잭션 지원**: 데이터 무결성 보장
+- **LRU 정리**: 타임스탬프 인덱스 기반 오래된 데이터 자동 정리
+
+#### LocalStorage 어댑터
 - **자동 용량 관리**: QuotaExceededError 시 LRU 캐시 정리
 - **접두사 격리**: `vircle_` 접두사로 다른 데이터와 분리
 - **타임스탬프 추적**: 데이터 저장 시간 기록
 - **안전한 폴백**: LocalStorage 불가 시 경고 후 계속 작동
 
+#### 스토리지 타입 선택
+
+```typescript
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    storageType: 'auto', // 'auto' | 'localStorage' | 'indexedDB'
+});
+```
+
+| 타입 | 설명 |
+|------|------|
+| `auto` (기본값) | IndexedDB 우선, 미지원 시 LocalStorage 폴백 |
+| `localStorage` | 항상 LocalStorage 사용 |
+| `indexedDB` | 항상 IndexedDB 사용 |
+
+`StorageFactory`는 동기(`create`) 및 비동기(`createAsync`) 생성을 모두 지원합니다. 비동기 방식은 Safari Private 모드 등에서 IndexedDB 실제 사용 가능 여부를 테스트한 후 안전하게 폴백합니다.
+
+### 암호화 (WebExtendedCryptoAdapter)
+
+Web Crypto API 기반의 하이브리드 암호화를 제공합니다:
+
+```
+데이터 (JSON) → AES-256-GCM 암호화 → 암호문 + Auth Tag
+AES 키 → RSA-OAEP (서버 공개키) → 암호화된 키
+결과: { data, key, iv, authTag, metadata }
+```
+
+#### 암호화 활성화
+
+```typescript
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    enableEncryption: true, // Web Crypto API 기반 암호화 활성화
+});
+```
+
+#### 제공 기능
+- **하이브리드 암호화**: AES-256-GCM (데이터) + RSA-OAEP (키 래핑)
+- **UUID v4 생성**: `crypto.randomUUID` 또는 `getRandomValues` 폴백
+- **HMAC-SHA256 서명**: 페이로드 무결성 검증
+- **자동 가용성 감지**: Web Crypto API 미지원 시 암호화 자동 비활성화
+
+#### 암호화된 페이로드 구조
+
+```typescript
+interface EncryptedPayload {
+    data: string;     // Base64 인코딩된 AES-GCM 암호문
+    key: string;      // Base64 인코딩된 RSA-OAEP 암호화 AES 키
+    iv: string;       // Base64 인코딩된 초기화 벡터 (96-bit)
+    authTag: string;  // Base64 인코딩된 GCM 인증 태그 (128-bit)
+    metadata: {
+        algorithm: 'AES-256-GCM';
+        keyAlgorithm: 'RSA-OAEP';
+        timestamp: string;
+    };
+}
+```
+
+### 세션 타임아웃
+
+SDK는 사용자 비활성 상태를 감지하여 자동으로 새 세션을 시작합니다:
+
+- **기본 타임아웃**: 30분 (설정 가능)
+- **동작 방식**: `visibilitychange → visible` 이벤트 시 마지막 활동 시간과 비교
+- **세션 로테이션**: 타임아웃 경과 시 새 세션 ID 생성 + `session_start` 이벤트 자동 추적
+- **활동 갱신**: `track()` 호출 시마다 마지막 활동 시간 갱신
+
+```typescript
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    sessionTimeout: 15 * 60 * 1000, // 15분
+});
+```
+
+### sendBeacon (페이지 이탈 보호)
+
+페이지 종료 시 `navigator.sendBeacon`을 사용하여 대기 중인 이벤트를 안전하게 전송합니다:
+
+- **beforeunload**: 페이지 닫기/새로고침 시 큐의 이벤트를 beacon으로 전송
+- **visibilitychange → hidden**: 탭 전환/최소화 시 beacon으로 전송
+- **제약사항**: sendBeacon은 커스텀 헤더를 설정할 수 없으므로 API 키를 요청 body에 포함하며, 암호화는 스킵됩니다
+- **폴백**: `navigator.sendBeacon` 미지원 환경에서는 자동으로 무시됩니다
+
+```typescript
+const vircle = new VircleWeb(
+    { apiKey: 'your-api-key' },
+    { flushOnUnload: true }, // 기본값: true
+);
+```
+
+### 에러 클래스
+
+SDK는 디버깅을 위한 구조화된 에러 클래스를 제공합니다:
+
+| 에러 클래스 | 코드 | 설명 |
+|------------|------|------|
+| `VircleWebError` | - | 기본 에러 클래스 (코드, 상세정보 포함) |
+| `VircleConfigError` | `CONFIG_ERROR` | 잘못된 설정 (API 키 누락 등) |
+| `VircleInitializationError` | `INITIALIZATION_ERROR` | 초기화 실패 |
+| `VircleStorageError` | `STORAGE_ERROR` | 스토리지 작업 실패 |
+| `VircleBrowserCompatibilityError` | `BROWSER_COMPATIBILITY_ERROR` | 브라우저 미지원 기능 |
+
+```typescript
+import { VircleWebError, VircleConfigError } from '@vircle/sdk-web';
+
+try {
+    const vircle = new VircleWeb({ apiKey: '' });
+    await vircle.initialize();
+} catch (error) {
+    if (error instanceof VircleConfigError) {
+        console.error('설정 오류:', error.code, error.details);
+    }
+}
+```
+
 ### 성능 최적화 기술
 
-- **requestIdleCallback 활용**: UI 블로킹 없는 백그라운드 이벤트 처리
-- **컨텍스트 캐싱**: 브라우저 정보 캐싱으로 반복적 DOM 접근 방지
+- **requestIdleCallback 활용**: TaskScheduler를 통한 UI 블로킹 없는 백그라운드 이벤트 처리
+- **컨텍스트 캐싱**: ContextCache를 통한 브라우저 정보 캐싱 (기본 5분), 중복 수집 방지를 위한 Promise 재사용
 - **이벤트 배칭**: TransportService의 큐를 통한 네트워크 요청 최소화
-- **메모리 관리**: cleanup 시 모든 이벤트 리스너 제거로 누수 방지
+- **메모리 관리**: cleanup 시 모든 이벤트 리스너 제거 및 History API 원복으로 누수 방지
+- **페이지 이탈 대응**: `navigator.sendBeacon`을 사용한 페이지 종료 시 안정적 이벤트 전송
+- **큐 크기 제한**: TaskScheduler의 `maxQueueSize`(기본 1000)로 메모리 오버플로우 방지
 
 ### 추적 제외
 
@@ -255,26 +463,43 @@ SDK는 `setupAutoTracking` 메서드를 통해 다양한 브라우저 이벤트
 
 ### VircleWebConfig
 
+`VircleConfig` (코어)를 상속하며 웹 전용 옵션을 추가합니다.
+
 ```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_')
+interface VircleWebConfig extends VircleConfig {
+    trackPageViews?: boolean;    // 자동 페이지뷰 추적 (기본: false)
+    trackClicks?: boolean;       // 자동 클릭 추적 (기본: false)
+    trackForms?: boolean;        // 자동 폼 제출 추적 (기본: false)
+    trackErrors?: boolean;       // 자동 에러 추적 (기본: false)
+    singlePageApp?: boolean;     // SPA 모드 (기본: false)
+    storagePrefix?: string;      // 스토리지 키 접두사 (기본: 'vircle_')
+    storageType?: StorageType;   // 스토리지 타입: 'auto' | 'localStorage' | 'indexedDB' (기본: 'auto')
+    enableEncryption?: boolean;  // Web Crypto API 암호화 활성화 (기본: false)
+    sessionTimeout?: number;     // 세션 타임아웃(ms) (기본: 1800000 = 30분)
 }
 ```
 
+#### VircleConfig (코어) 주요 옵션
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `apiKey` | `string` | (필수) | API 인증 키 |
+| `environment` | `'development' \| 'production'` | `'production'` | 환경 설정 |
+| `debug` | `boolean` | `false` | 디버그 모드 |
+| `batch.size` | `number` | `50` | 배치당 최대 이벤트 수 |
+| `batch.timeout` | `number` | `5000` | 배치 대기 시간(ms) |
+| `batch.flushInterval` | `number` | `10000` | 자동 플러시 간격(ms) |
+| `retry.maxAttempts` | `number` | `3` | 최대 재시도 횟수 |
+| `retry.initialDelay` | `number` | `500` | 초기 백오프 지연(ms) |
+| `privacy.respectDoNotTrack` | `boolean` | `true` | DNT 헤더 존중 |
+| `headers` | `Record<string, string>` | - | 커스텀 HTTP 헤더 |
+
 ### VircleWebOptions
 
 ```typescript
-interface VircleWebOptions {
-    flushOnUnload?: boolean; // 페이지 언로드 시 이벤트 전송 (기본: true)
-    contextCacheTime?: number; // 컨텍스트 캐시 시간(ms) (기본: 300000)
-    enablePerformance?: boolean; // 성능 측정 활성화 (기본: true)
+interface VircleWebOptions extends Partial<VircleCoreOptions> {
+    flushOnUnload?: boolean;   // 페이지 언로드 시 sendBeacon 전송 (기본: true)
+    contextCacheTime?: number; // 컨텍스트 캐시 시간(ms) (기본: 300000 = 5분)
 }
 ```
 
@@ -291,14 +516,14 @@ SDK를 초기화하고 자동 추적을 시작합니다.
 ### 이벤트 추적
 
 ```typescript
-await vircle.track(
-  eventName: string,
-  properties?: Record<string, unknown>,
+await vircle.track<TProperties>(
+  name: string,
+  properties?: TProperties,
   context?: EventContext
 ): Promise<void>
 ```
 
-커스텀 이벤트를 추적합니다.
+커스텀 이벤트를 추적합니다. `requestIdleCallback`을 활용하여 UI를 블로킹하지 않으며, 호출 시마다 세션의 마지막 활동 시간이 갱신됩니다.
 
 ### 페이지뷰 추적
 
@@ -309,18 +534,18 @@ await vircle.trackPageView(
 ): Promise<void>
 ```
 
-페이지뷰를 수동으로 추적합니다.
+페이지뷰를 수동으로 추적합니다. URL, 제목, 리퍼러 등의 페이지 컨텍스트를 자동 수집합니다.
 
 ### 사용자 식별
 
 ```typescript
-await vircle.identify(
+await vircle.identify<TTraits>(
   userId: string,
-  traits?: UserProperties
+  traits?: TTraits
 ): Promise<void>
 ```
 
-사용자를 식별하고 속성을 설정합니다.
+사용자를 식별하고 속성을 설정합니다. VircleWeb에서는 호출 시 컨텍스트 캐시를 자동으로 무효화합니다.
 
 ### 사용자 리셋
 
@@ -328,7 +553,38 @@ await vircle.identify(
 await vircle.reset(): Promise<void>
 ```
 
-사용자 정보를 초기화합니다.
+사용자 정보와 세션을 초기화합니다.
+
+### 유틸리티
+
+```typescript
+// 현재 페이지 URL
+vircle.getCurrentUrl(): string
+
+// 네트워크 연결 상태
+vircle.isOnline(): boolean
+
+// SDK 상태 확인
+vircle.getStatus(): {
+    isInitialized: boolean;
+    sessionId?: string;
+    userId?: string;
+    pluginCount: number;
+    queueSize: number;
+}
+
+// 런타임 메트릭 조회
+vircle.getMetrics(): {
+    queueSize: number;
+    isProcessing: boolean;
+}
+
+// 이벤트 수동 플러시
+await vircle.flush(): Promise<void>
+
+// 이벤트 수동 플러시 (타임아웃 지정)
+await vircle.flush(timeoutMs?: number): Promise<void>
+```
 
 ### 정리
 
@@ -336,18 +592,64 @@ await vircle.reset(): Promise<void>
 await vircle.cleanup(): Promise<void>
 ```
 
-모든 이벤트 리스너를 제거하고 리소스를 정리합니다.
+SDK가 사용하는 모든 리소스를 정리합니다:
+1. 이벤트 리스너 제거 (`beforeunload`, `error`, `click`, `submit`, `popstate`, `visibilitychange`)
+2. History API 원복 (`pushState`, `replaceState`)
+3. 대기 중인 이벤트 전송 (`flush()`)
+4. 코어 서비스 정리 (`super.cleanup()`)
+
+## Exports
+
+```typescript
+// 메인 SDK 클래스
+import { VircleWeb } from '@vircle/sdk-web';
+import VircleWeb from '@vircle/sdk-web'; // default export
+
+// 설정 타입
+import type { VircleWebConfig, VircleWebOptions } from '@vircle/sdk-web';
+
+// 컨텍스트 수집기
+import { WebContextCollector } from '@vircle/sdk-web';
+
+// 스토리지
+import { LocalStorageAdapter, IndexedDBAdapter, StorageFactory } from '@vircle/sdk-web';
+import type { StorageType } from '@vircle/sdk-web'; // 'auto' | 'localStorage' | 'indexedDB'
+
+// 암호화 어댑터
+import { WebExtendedCryptoAdapter } from '@vircle/sdk-web';
+
+// 에러 클래스
+import {
+    VircleWebError,
+    VircleConfigError,
+    VircleInitializationError,
+    VircleStorageError,
+    VircleBrowserCompatibilityError,
+} from '@vircle/sdk-web';
+
+// Core 타입 재수출
+import type {
+    VircleConfig,
+    EventContext,
+    DeviceContext,
+    PageContext,
+    AppContext,
+    UserTraits,
+    StorageAdapter,
+} from '@vircle/sdk-web';
+```
 
 ## 빌드 파일 설명
 
-| 파일 | 용도 | 의존성 | 사용 방법 |
-|------|------|--------|-----------|
-| `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>` |
+| 파일 | 포맷 | 용도 | `@vircle/sdk-core-ts` | 사용 방법 |
+|------|------|------|----------------------|-----------|
+| `dist/index.js` | CJS | 번들러 (Webpack 등) | 외부 의존성 | `require('@vircle/sdk-web')` |
+| `dist/index.esm.js` | ESM | 번들러 (Vite, Rollup 등) | 외부 의존성 | `import { VircleWeb } from '@vircle/sdk-web'` |
+| `dist/vircle-web-sdk.standalone.esm.js` | ESM | 브라우저 직접 사용 | 번들에 포함 | `<script type="module">` |
+| `dist/vircle-web-sdk.min.js` | UMD | 레거시 브라우저 | 번들에 포함 | `<script src="...">` |
+| `dist/index.d.ts` | DTS | TypeScript 타입 정의 | - | 자동 적용 |
 
-⚠️ **중요**: 브라우저에서 직접 사용할 때는 반드시 `standalone` 또는 `min` 빌드를 사용하세요.
+**중요**: 브라우저에서 직접 사용할 때는 반드시 `standalone` 또는 `min` 빌드를 사용하세요. npm 패키지로 사용 시 번들러가 `@vircle/sdk-core-ts`를 함께 번들링합니다.
 
 ## 브라우저 지원
 
@@ -357,51 +659,49 @@ await vircle.cleanup(): Promise<void>
 - iOS Safari: iOS 12+
 - Chrome for Android: Android 6+
 
+> 암호화 기능(`enableEncryption`)은 Web Crypto API를 지원하는 브라우저에서만 동작합니다. 미지원 시 자동으로 비활성화됩니다.
+
 ## 보안 고려사항
 
 1. **클라이언트 측 API 키**: 브라우저에서 사용되는 API 키는 공개됩니다. 데이터 수집(Write) 권한만 가진 키를 사용하세요.
 
 2. **민감한 데이터**: 민감한 데이터가 수집되지 않도록 `data-vircle-ignore` 속성을 적절히 사용하세요.
 
-3. **LocalStorage**: SDK는 LocalStorage를 사용하여 데이터를 임시 저장합니다. 민감한 정보는 저장하지 않습니다.
+3. **스토리지**: SDK는 LocalStorage/IndexedDB를 사용하여 데이터를 임시 저장합니다. 민감한 정보는 저장하지 않습니다.
+
+4. **암호화**: `enableEncryption: true` 설정 시 서버 공개키로 이벤트 페이로드를 암호화합니다. 공개키는 CDN(`RemoteConfigService`)에서 자동 fetch됩니다.
+
+5. **sendBeacon 전송**: 페이지 종료 시 `sendBeacon`으로 전송되는 이벤트는 커스텀 헤더 설정이 불가하여 암호화/HMAC 서명 없이 전송됩니다. API 키는 요청 body에 포함됩니다. 정상 동작 중에는 `fetch()` 기반의 암호화된 전송이 사용됩니다.
 
 ## 성능 영향
 
-- **번들 크기**: ~13.5KB (minified), ~4.5KB (gzipped)
-- **초기화 시간**: < 10ms
-- **이벤트 추적**: < 1ms (requestIdleCallback 사용)
+- **번들 크기 (standalone)**: ~106KB (minified, core 포함), npm 패키지는 ~70KB (core 외부 의존성)
+- **이벤트 추적**: requestIdleCallback 기반으로 UI 블로킹 없음
+- **컨텍스트 수집**: 캐싱으로 반복적인 DOM 접근 방지 (기본 5분)
 
 ## 고급 사용 예제
 
 ### SPA (Single Page Application) 설정
 
 ```typescript
+// singlePageApp: true 설정 시 History API (pushState, replaceState)를 래핑하여
+// 라우트 변경을 자동으로 감지하고 페이지뷰를 추적합니다.
+// React Router, Vue Router, Next.js 등 대부분의 SPA 프레임워크와 호환됩니다.
 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])
+    apiKey: 'your-api-key',
+    singlePageApp: true,     // History API 래핑
+    trackPageViews: true,    // 자동 페이지뷰 추적
+});
 
-  return <Routes>...</Routes>
-}
+await vircle.initialize();
+// 이후 별도의 설정 없이 라우트 변경 시 자동으로 page_view 이벤트가 추적됩니다.
 ```
 
 ### 에러 처리와 함께 사용
 
 ```typescript
+import { VircleWeb, VircleInitializationError } from '@vircle/sdk-web';
+
 try {
     const vircle = new VircleWeb({
         apiKey: 'your-api-key',
@@ -422,10 +722,27 @@ try {
         throw error;
     }
 } catch (error) {
-    console.error('SDK 초기화 실패:', error);
+    if (error instanceof VircleInitializationError) {
+        console.error('SDK 초기화 실패:', error.code, error.details);
+    }
 }
 ```
 
+### 암호화 활성화
+
+```typescript
+const vircle = new VircleWeb({
+    apiKey: 'your-api-key',
+    enableEncryption: true, // Web Crypto API 가용 시 자동 활성화
+    trackPageViews: true,
+});
+
+await vircle.initialize();
+
+// 이후 모든 이벤트가 하이브리드 암호화되어 전송됩니다
+await vircle.track('purchase', { amount: 99.99 });
+```
+
 ### 성능 최적화 설정
 
 ```typescript
@@ -434,18 +751,16 @@ const vircle = new VircleWeb(
         apiKey: 'your-api-key',
         trackPageViews: true,
         trackClicks: true,
+        sessionTimeout: 15 * 60 * 1000, // 15분 세션 타임아웃
     },
     {
-        contextCacheTime: 600000, // 10분 캐싱
-        flushOnUnload: false, // 수동으로 flush 관리
-        enablePerformance: false, // 성능 추적 비활성화
+        contextCacheTime: 600000, // 10분 캐싱 (기본 5분)
+        flushOnUnload: true,      // sendBeacon으로 페이지 이탈 시 자동 전송 (기본값)
     },
 );
 
-// 중요한 시점에 수동으로 flush
-window.addEventListener('beforeunload', async () => {
-    await vircle.flush();
-});
+// 중요한 시점에 수동으로 flush (예: 결제 완료 후)
+await vircle.flush();
 ```
 
 ### 민감한 정보가 있는 페이지
@@ -531,30 +846,51 @@ await vircle.flush();
 ### 메모리 누수 방지
 
 ```typescript
-// 컴포넌트 언마운트 시 반드시 cleanup 호출
-// React 예제
+// React 예제 - 컴포넌트 언마운트 시 반드시 cleanup 호출
+// 일반적으로 SDK는 앱 레벨에서 한 번만 초기화합니다
 useEffect(() => {
-    const vircle = new VircleWeb({ apiKey: 'your-api-key' });
+    const vircle = new VircleWeb({
+        apiKey: 'your-api-key',
+        trackPageViews: true,
+    });
     vircle.initialize();
 
     return () => {
+        // cleanup()은 이벤트 리스너 제거, History API 원복, 큐 플러시를 수행합니다
         vircle.cleanup();
     };
 }, []);
 ```
 
+### 암호화 관련
+
+```typescript
+// 암호화 미지원 환경에서 enableEncryption: true로 설정한 경우
+// 콘솔에 경고 메시지가 출력되고 암호화 없이 동작합니다
+// "[Vircle] Web Crypto API를 사용할 수 없습니다. 암호화를 비활성화합니다."
+```
+
 ## TypeScript 지원
 
 SDK는 완전한 TypeScript 타입 정의를 제공합니다:
 
 ```typescript
-import { VircleWeb, VircleWebConfig, VircleWebOptions, EventContext, UserProperties } from '@vircle/sdk-web';
+import {
+    VircleWeb,
+    VircleWebConfig,
+    VircleWebOptions,
+    WebExtendedCryptoAdapter,
+    VircleWebError,
+} from '@vircle/sdk-web';
+import type { EventContext, UserTraits, StorageType } from '@vircle/sdk-web';
 
 // 타입 안전한 설정
 const config: VircleWebConfig = {
     apiKey: process.env.VIRCLE_API_KEY!,
     trackPageViews: true,
     trackErrors: true,
+    enableEncryption: true,
+    storageType: 'auto',
 };
 
 const options: VircleWebOptions = {
@@ -565,14 +901,15 @@ const options: VircleWebOptions = {
 const vircle = new VircleWeb(config, options);
 
 // 타입 안전한 이벤트 추적
-interface PurchaseEvent {
+// track()의 제네릭 파라미터는 Record<string, unknown>을 확장해야 합니다
+interface PurchaseProperties {
     product_id: string;
     price: number;
     currency: string;
     quantity: number;
 }
 
-await vircle.track<PurchaseEvent>('purchase', {
+await vircle.track<PurchaseProperties>('purchase', {
     product_id: 'sku_123',
     price: 49.99,
     currency: 'USD',
@@ -580,13 +917,14 @@ await vircle.track<PurchaseEvent>('purchase', {
 });
 
 // 타입 안전한 사용자 속성
-interface UserTraits extends UserProperties {
+// identify()의 제네릭 파라미터는 Record<string, unknown>을 확장해야 합니다
+interface CustomUserTraits {
     email: string;
     plan: 'free' | 'pro' | 'enterprise';
     created_at: string;
 }
 
-await vircle.identify<UserTraits>('user-123', {
+await vircle.identify<CustomUserTraits>('user-123', {
     email: 'user@example.com',
     plan: 'pro',
     created_at: new Date().toISOString(),
@@ -595,4 +933,4 @@ await vircle.identify<UserTraits>('user-123', {
 
 ## 라이선스
 
-MIT
+MIT