@vircle/sdk-web 0.4.0 → 0.6.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분)
 }
 ```
@@ -618,6 +633,10 @@ import type { VircleWebConfig, VircleWebOptions } from '@vircle/sdk-web';
 // 컨텍스트 수집기
 import { WebContextCollector } from '@vircle/sdk-web';
 
+// F-4b Link Decoration — outbound link에 ?_vuid= 자동 부착 (프로그래밍 API)
+import { LinkDecorator } from '@vircle/sdk-web';
+import type { LinkDecoratorOptions } from '@vircle/sdk-web';
+
 // 스토리지
 import { LocalStorageAdapter, IndexedDBAdapter, StorageFactory } from '@vircle/sdk-web';
 import type { StorageType } from '@vircle/sdk-web'; // 'auto' | 'localStorage' | 'indexedDB'
@@ -678,7 +697,7 @@ import type {
 
 4. **암호화**: `enableEncryption: true` 설정 시 서버 공개키로 이벤트 페이로드를 암호화합니다. 공개키는 CDN(`RemoteConfigService`)에서 자동 fetch됩니다.
 
-5. **sendBeacon 전송**: 페이지 종료 시 `sendBeacon`으로 전송되는 이벤트는 커스텀 헤더 설정이 불가하여 암호화/HMAC 서명 없이 전송됩니다. API 키는 요청 body에 포함됩니다. 정상 동작 중에는 `fetch()` 기반의 암호화된 전송이 사용됩니다.
+5. **페이지 이탈 전송**: 페이지 종료 시 `fetch()+keepalive`로 전송되며, `Authorization` 헤더를 포함한 인증된 요청으로 전송됩니다. 정상 동작과 동일한 `fetch()` 기반 전송을 사용합니다.
 
 ## 성능 영향
 
@@ -762,7 +781,7 @@ const vircle = new VircleWeb(
     },
     {
         contextCacheTime: 600000, // 10분 캐싱 (기본 5분)
-        flushOnUnload: true,      // sendBeacon으로 페이지 이탈 시 자동 전송 (기본값)
+        flushOnUnload: true,      // fetch+keepalive로 페이지 이탈 시 자동 전송 (기본값)
     },
 );
 
@@ -938,6 +957,37 @@ await vircle.identify<CustomUserTraits>('user-123', {
 });
 ```
 
+## Identity Graph 강화
+
+Meta CAPI EMQ 7+ 도달을 위한 호스트 통합(PII 해시, consent, 크로스 도메인 link decoration, Meta Pixel 활성화 등):
+
+- [호스트 통합 가이드](./docs/host-integration-guide.md) — `vircle.identify()` PII 전달, `setConsent()`, `linkDecoration` 설정
+- [Cafe24 PII 수집 가이드](../plugin-cafe24/docs/cafe24-pii-collection.md) — Cafe24 자사몰 환경 한정
+
+핵심 설정 예시:
+
+```typescript
+new VircleWeb({
+    apiKey: 'vk_prod_...',
+    storageType: 'localStorage',
+    accountSwitchDetectionEnabled: true,
+    defaultConsent: { analytics: true, marketing: false, functional: true },
+    linkDecoration: {
+        enabled: true,
+        allowedDomains: ['.vircle.co.kr', 'shop.example.com'],
+    },
+});
+
+// 호스트 동의관리 응답 후
+vircle.setConsent({ analytics: true, marketing: true, functional: true });
+
+// PII는 SDK가 정규화 + SHA-256 해시 → em/ph array로 전송 (평문 키는 strip)
+await vircle.identify(userId, {
+    email: 'user@example.com',
+    phone: '+82 10-1234-5678',
+});
+```
+
 ## 라이선스
 
 MIT

package/dist/index.d.ts

@@ -448,6 +448,29 @@ interface VircleWebConfig extends VircleConfig {
      * 지정된 시간 동안 비활성 상태이면 새 세션을 시작합니다.
      */
     sessionTimeout?: number;
+    /**
+     * F-4b 크로스 도메인 Link Decoration — outbound link에 `?_vuid=`를 click 시점에 자동 부착.
+     * 같은 partner의 여러 도메인 간(예: 라운지 ↔ Cafe24 자사몰) vuid 전파 자동화.
+     *
+     * 동작:
+     * - 페이지 로드 시 LinkDecorator가 capture-phase event delegation 등록 (mousedown/click/auxclick)
+     * - 사용자가 a[href] 클릭 시 link href가 `allowedDomains` 매치되면 `?_vuid=<anonymousId>` 부착
+     * - 정적 URL을 미리 변경하지 않음 — PR 미리보기·OG 태그 등에 vuid 노출 회피
+     * - 컨텍스트 메뉴("Copy link", "Open in new tab")도 mousedown 시점 갱신으로 커버
+     * - `allowedDomains` 매치되지 않은 외부 사이트에는 부착 안 함 (vuid 누출 방지)
+     */
+    linkDecoration?: {
+        /** 기본 false. true로 명시해야 활성화 */
+        enabled?: boolean;
+        /**
+         * vuid를 부착할 도메인 화이트리스트. hostname suffix 매칭.
+         * 예: ['shop.vircle.co.kr', 'lounge.vircle.co.kr'] → 정확 매치
+         *     ['.vircle.co.kr'] → 서브도메인 포함 매치
+         */
+        allowedDomains?: string[];
+        /** URL 파라미터 이름. 기본 `_vuid` */
+        paramName?: string;
+    };
 }
 interface VircleWebOptions extends Partial<VircleCoreOptions> {
     /**
@@ -489,6 +512,7 @@ declare class VircleWeb extends VircleCore {
     private originalReplaceState?;
     private lastActivityTime;
     private sessionTimeout;
+    private linkDecorator?;
     constructor(config: VircleWebConfig, options?: VircleWebOptions);
     /**
      * SDK 초기화 및 자동 추적 설정
@@ -577,6 +601,11 @@ declare class VircleWeb extends VircleCore {
      * @private
      */
     private setupAutoTracking;
+    /**
+     * F-4b Link Decoration 활성화 — outbound link click 시 ?_vuid= 자동 부착.
+     * @private
+     */
+    private setupLinkDecoration;
     /**
      * 에러 추적 설정
      *
@@ -727,7 +756,17 @@ declare class WebContextCollector {
      */
     private static readonly CAMPAIGN_PARAMS_MAP;
     private static readonly STORAGE_PREFIX;
+    /** localStorage 영구 백업 키 (PG 리다이렉트 등으로 sessionStorage 유실 시 복원용) */
+    private static readonly CAMPAIGN_PERSIST_KEY;
+    /** localStorage 캠페인 데이터 만료 기간: 7일 (광고 어트리뷰션 윈도우) */
+    private static readonly CAMPAIGN_PERSIST_TTL_MS;
     collect(): Promise<EventContext>;
+    /**
+     * Meta `_fbp`/`_fbc` 쿠키 read-only 수집. 호스트가 Meta Pixel을 설치했거나
+     * plugin-cafe24의 MetaPixelLoader가 쿠키를 발급해 둔 경우 read한다.
+     * 둘 다 부재 시 undefined 반환 (EventContext.meta omit).
+     */
+    private collectMetaContext;
     /**
      * 디바이스 정보 수집
      */
@@ -765,10 +804,19 @@ declare class WebContextCollector {
      */
     private getBrowserVersion;
     /**
-     * 캠페인 파라미터 수집 (UTM 5 + 광고 클릭 ID 4)
+     * 캠페인 파라미터 수집 (UTM 5 + 광고 클릭 ID 5 + 네이버 검색광고 8)
      * sessionStorage를 사용하여 MPA 페이지 전환 간에도 유지
      */
     private collectCampaignContext;
+    /**
+     * 캠페인 파라미터를 localStorage에 타임스탬프와 함께 백업.
+     * PG 리다이렉트로 새 탭이 열리거나 sessionStorage가 초기화되는 경우 복원용.
+     */
+    private persistCampaignToLocalStorage;
+    /**
+     * localStorage에서 캠페인 파라미터를 복원. 7일 초과 시 만료 처리.
+     */
+    private restoreCampaignFromLocalStorage;
     /**
      * 앱 이름 가져오기 (meta 태그에서)
      */
@@ -783,6 +831,68 @@ declare class WebContextCollector {
     private getEnvironment;
 }
 
+/**
+ * @module LinkDecorator
+ *
+ * F-4b 크로스 도메인 Link Decoration — outbound link에 `?_vuid=` click 시점 자동 부착.
+ *
+ * 같은 partner의 여러 도메인 간(예: 라운지 ↔ Cafe24 자사몰) vuid 전파 자동화.
+ * GA4 `linker` plugin과 동일 패턴.
+ *
+ * 설계 결정:
+ * - **정적 URL 미변경**: 페이지 로드 시 `<a href>` 속성을 직접 수정하지 않는다. PR 미리보기·OG 태그 등
+ *   에서 vuid 노출 회피.
+ * - **click 시점 동적 부착**: capturing-phase click 리스너가 `a[href]` 매치 시 즉시 href 갱신
+ *   (delegate 방식 — 동적으로 추가된 link도 자동 커버).
+ * - **MutationObserver 불필요**: capture-phase delegate가 동적 콘텐츠도 처리하므로 별도 observer 불요
+ *   (성능·복잡도 절감).
+ * - **allowedDomains 화이트리스트**: 매치 안 된 외부 사이트에는 부착 안 함 (vuid 누출 방지).
+ *
+ * Limitations:
+ * - JavaScript 비활성 환경에선 동작 안 함 (정적 URL 미변경 트레이드오프)
+ * - middle-click/wheel-click도 처리하기 위해 'auxclick' 이벤트도 리슨
+ * - `target="_blank"` 새 창 link도 동일 처리
+ */
+interface LinkDecoratorOptions {
+    /** vuid를 부착할 도메인 화이트리스트. hostname suffix 매칭 */
+    allowedDomains: string[];
+    /** URL 파라미터 이름 (기본 `_vuid`) */
+    paramName?: string;
+    /** 현재 anonymousId를 반환하는 콜백 — click 시점에 호출 */
+    getAnonymousId: () => string | undefined;
+}
+declare class LinkDecorator {
+    private allowedDomains;
+    private paramName;
+    private getAnonymousId;
+    private clickHandler?;
+    constructor(options: LinkDecoratorOptions);
+    /**
+     * mousedown/click/auxclick 이벤트 capture-phase delegate 등록. 동적 추가 link도 자동 커버.
+     * SSR/non-DOM 환경(typeof document === 'undefined')에서는 no-op.
+     *
+     * 이벤트별 역할:
+     * - `mousedown`: 우클릭 후 "Copy link address" / "Open in new tab" 컨텍스트 메뉴 케이스 커버
+     *   (이 흐름에서는 click이 발생하지 않으므로 mousedown 시점에 href 갱신)
+     * - `click`: 키보드 네비게이션(focus + Enter) 등 mousedown 미발생 케이스 백업
+     * - `auxclick`: middle-click (휠 클릭으로 새 탭 열기)
+     */
+    start(): void;
+    stop(): void;
+    /**
+     * 외부 호출용 — 임의 URL에 vuid 파라미터 부착. 화이트리스트 매치되지 않으면 원본 URL 반환.
+     * 호스트가 동적으로 만든 URL 등에 사용 가능.
+     */
+    decorate(href: string): string;
+    private handleClick;
+    /**
+     * hostname 화이트리스트 매칭.
+     * - `.example.com` → suffix match (서브도메인 포함)
+     * - `example.com` → exact match
+     */
+    private isAllowedDomain;
+}
+
 /**
  * Web Crypto API 기반 암호화 어댑터
  *
@@ -819,6 +929,11 @@ declare class WebExtendedCryptoAdapter implements ExtendedCryptoAdapter {
      * 2. RSA-OAEP로 AES 키 암호화
      */
     encryptPayload(data: Record<string, any>, publicKeyBase64: string): Promise<EncryptedPayload>;
+    /**
+     * SHA-256 해시 — Meta CAPI em/ph 등 PII 매칭 키 생성용.
+     * Web Crypto API의 crypto.subtle.digest 사용.
+     */
+    sha256(input: string): Promise<string>;
     /**
      * Web Crypto API 사용 가능 여부
      */
@@ -941,5 +1056,5 @@ declare class VircleBrowserCompatibilityError extends VircleWebError {
     constructor(message: string, details?: Record<string, any>);
 }
 
-export { IndexedDBAdapter, LocalStorageAdapter, StorageFactory, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebExtendedCryptoAdapter, VircleWeb as default };
-export type { StorageType, VircleWebConfig, VircleWebOptions };
+export { IndexedDBAdapter, LinkDecorator, LocalStorageAdapter, StorageFactory, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebExtendedCryptoAdapter, VircleWeb as default };
+export type { LinkDecoratorOptions, StorageType, VircleWebConfig, VircleWebOptions };