@vircle/sdk-web 0.4.0 → 0.4.1

package/README.md

@@ -23,7 +23,7 @@ VircleCore를 확장하여 웹 환경에 특화된 기능을 제공하는 웹
 
 ### 세션 관리
 - **세션 타임아웃**: 비활성 상태 감지 후 자동 세션 로테이션 (기본 30분)
-- **fetch+keepalive**: 페이지 종료 시 인증 헤더 포함 이벤트 전송
+- **fetch+keepalive**: 페이지 종료 시 `Authorization` 헤더 포함 이벤트 전송
 
 ### 보안 및 프라이버시
 - **페이로드 암호화**: Web Crypto API 기반 하이브리드 암호화 (AES-256-GCM + RSA-OAEP)
@@ -162,7 +162,7 @@ await vircle.identify('user-123', {
 │  • 자동 추적 (페이지뷰/클릭/폼/에러/SPA)       │
 │  • 웹 컨텍스트 수집 (WebContextCollector)      │
 │  • 세션 타임아웃 / 로테이션                      │
-│  • sendBeacon (페이지 이탈 보호)                │
+│  • fetch+keepalive (페이지 이탈 보호)            │
 │  • StorageFactory (IndexedDB/LocalStorage) │
 │  • 하이브리드 암호화 (WebExtendedCryptoAdapter)│
 │  • 에러 클래스 (VircleWebError 계열)           │
@@ -244,6 +244,22 @@ User-Agent 기반 디바이스/브라우저/OS 감지 및 화면 정보 수집
 | `version` | `string \| undefined` | `<meta name="version">` | 앱 버전 |
 | `environment` | `'development' \| 'production'` | `window.location.hostname` | localhost/staging → development, 그 외 → production |
 
+#### campaign (CampaignContext)
+
+URL의 UTM 파라미터 및 광고 클릭 ID를 수집합니다. `sessionStorage`에 저장하여 MPA 페이지 전환 간에도 유지됩니다.
+
+| 필드 | 타입 | 조건 | 설명 |
+|------|------|------|------|
+| `source` | `string` | `utm_source` 존재 시 | 트래픽 소스 (예: `google`) |
+| `medium` | `string` | `utm_medium` 존재 시 | 트래픽 매체 (예: `cpc`) |
+| `campaign` | `string` | `utm_campaign` 존재 시 | 캠페인 이름 |
+| `term` | `string` | `utm_term` 존재 시 | 검색 키워드 |
+| `content` | `string` | `utm_content` 존재 시 | 광고 콘텐츠 구분 |
+| `gclid` | `string` | `gclid` 존재 시 | Google Ads 클릭 ID |
+| `fbclid` | `string` | `fbclid` 존재 시 | Facebook 클릭 ID |
+| `msclkid` | `string` | `msclkid` 존재 시 | Microsoft Ads 클릭 ID |
+| `ttclid` | `string` | `ttclid` 존재 시 | TikTok 클릭 ID |
+
 #### custom (Record<string, unknown>)
 
 추가 브라우저 환경 정보 (가용한 경우에만 수집)
@@ -251,7 +267,6 @@ User-Agent 기반 디바이스/브라우저/OS 감지 및 화면 정보 수집
 | 필드 | 타입 | 조건 | 설명 |
 |------|------|------|------|
 | `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 지원 시 | 네트워크 연결 정보 |
@@ -284,13 +299,13 @@ User-Agent 기반 디바이스/브라우저/OS 감지 및 화면 정보 수집
     version: '2.1.0',
     environment: 'production'
   },
+  campaign: {
+    source: 'google',
+    medium: 'cpc',
+    campaign: 'summer_sale'
+  },
   custom: {
     referrer: 'https://google.com',
-    campaign: {
-      source: 'google',
-      medium: 'cpc',
-      campaign: 'summer_sale'
-    },
     cookieEnabled: true,
     doNotTrack: false,
     connection: {
@@ -398,14 +413,14 @@ const vircle = new VircleWeb({
 });
 ```
 
-### sendBeacon (페이지 이탈 보호)
+### fetch+keepalive (페이지 이탈 보호)
 
-페이지 종료 시 `navigator.sendBeacon`을 사용하여 대기 중인 이벤트를 안전하게 전송합니다:
+페이지 종료 시 `fetch()` + `keepalive: true` 옵션을 사용하여 대기 중인 이벤트를 안전하게 전송합니다:
 
-- **beforeunload**: 페이지 닫기/새로고침 시 큐의 이벤트를 beacon으로 전송
-- **visibilitychange → hidden**: 탭 전환/최소화 시 beacon으로 전송
-- **제약사항**: sendBeacon은 커스텀 헤더를 설정할 수 없으므로 API 키를 요청 body에 포함하며, 암호화는 스킵됩니다
-- **폴백**: `navigator.sendBeacon` 미지원 환경에서는 자동으로 무시됩니다
+- **beforeunload**: 페이지 닫기/새로고침 시 큐의 이벤트를 keepalive fetch로 전송
+- **visibilitychange → hidden**: 탭 전환/최소화 시 keepalive fetch로 전송
+- **장점**: `Authorization` 헤더를 포함할 수 있어 인증된 요청으로 전송 가능
+- **폴백**: `keepalive` 미지원 환경에서는 자동으로 무시됩니다
 
 ```typescript
 const vircle = new VircleWeb(
@@ -445,7 +460,7 @@ try {
 - **컨텍스트 캐싱**: ContextCache를 통한 브라우저 정보 캐싱 (기본 5분), 중복 수집 방지를 위한 Promise 재사용
 - **이벤트 배칭**: TransportService의 큐를 통한 네트워크 요청 최소화
 - **메모리 관리**: cleanup 시 모든 이벤트 리스너 제거 및 History API 원복으로 누수 방지
-- **페이지 이탈 대응**: `navigator.sendBeacon`을 사용한 페이지 종료 시 안정적 이벤트 전송
+- **페이지 이탈 대응**: `fetch()+keepalive`를 사용한 페이지 종료 시 안정적 이벤트 전송
 - **큐 크기 제한**: TaskScheduler의 `maxQueueSize`(기본 1000)로 메모리 오버플로우 방지
 
 ### 추적 제외
@@ -502,7 +517,7 @@ interface VircleWebConfig extends VircleConfig {
 
 ```typescript
 interface VircleWebOptions extends Partial<VircleCoreOptions> {
-    flushOnUnload?: boolean;   // 페이지 언로드 시 sendBeacon 전송 (기본: true)
+    flushOnUnload?: boolean;   // 페이지 언로드 시 fetch+keepalive 전송 (기본: true)
     contextCacheTime?: number; // 컨텍스트 캐시 시간(ms) (기본: 300000 = 5분)
 }
 ```
@@ -678,7 +693,7 @@ import type {
 
 4. **암호화**: `enableEncryption: true` 설정 시 서버 공개키로 이벤트 페이로드를 암호화합니다. 공개키는 CDN(`RemoteConfigService`)에서 자동 fetch됩니다.
 
-5. **sendBeacon 전송**: 페이지 종료 시 `sendBeacon`으로 전송되는 이벤트는 커스텀 헤더 설정이 불가하여 암호화/HMAC 서명 없이 전송됩니다. API 키는 요청 body에 포함됩니다. 정상 동작 중에는 `fetch()` 기반의 암호화된 전송이 사용됩니다.
+5. **페이지 이탈 전송**: 페이지 종료 시 `fetch()+keepalive`로 전송되며, `Authorization` 헤더를 포함한 인증된 요청으로 전송됩니다. 정상 동작과 동일한 `fetch()` 기반 전송을 사용합니다.
 
 ## 성능 영향
 
@@ -762,7 +777,7 @@ const vircle = new VircleWeb(
     },
     {
         contextCacheTime: 600000, // 10분 캐싱 (기본 5분)
-        flushOnUnload: true,      // sendBeacon으로 페이지 이탈 시 자동 전송 (기본값)
+        flushOnUnload: true,      // fetch+keepalive로 페이지 이탈 시 자동 전송 (기본값)
     },
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vircle/sdk-web",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Vircle SDK for Web applications",
   "type": "module",
   "main": "dist/index.js",