@vircle/sdk-web 0.4.1 → 0.6.1

package/README.md

@@ -633,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'
@@ -953,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 };

package/dist/index.esm.js

@@ -1,5 +1,65 @@
 import { VircleCore, WebIdleScheduler } from '@vircle/sdk-core-ts';
 
+/**
+ * @module MetaCookieCollector
+ *
+ * Meta(Facebook) `_fbp`/`_fbc` 쿠키 **read-only** 수집기.
+ *
+ * 책임 범위:
+ * - document.cookie에서 `_fbp`, `_fbc` 값 읽어 EventContext.meta에 첨부.
+ * - **자체 생성 안 함**. fbclid → `_fbc` 변환, `_fbp` 생성 등 쓰기 작업은 plugin-cafe24의
+ *   MetaPixelLoader가 opt-in 3-조건 AND(enable_pixel + vircle_pixel_id + consent.marketing)
+ *   충족 시에만 수행한다 — 책임 분리.
+ *
+ * 모든 web 환경(Cafe24 외 SmartStore 등 향후 partner 포함)에서 공통으로 cookie를 read한다.
+ */
+const FBP_KEY = '_fbp';
+const FBC_KEY = '_fbc';
+/**
+ * document.cookie를 파싱하여 `_fbp`, `_fbc` 값을 반환.
+ * 호스트 사이트가 Meta Pixel을 설치한 환경에서는 Pixel이 이미 cookie를 발급해 둔다.
+ *
+ * @returns 발견된 값만 포함하는 객체. 둘 다 부재 시 빈 객체.
+ */
+function readMetaCookies() {
+    if (typeof document === 'undefined' || !document.cookie) {
+        return {};
+    }
+    const cookies = parseCookieString(document.cookie);
+    const result = {};
+    if (cookies[FBP_KEY])
+        result.fbp = cookies[FBP_KEY];
+    if (cookies[FBC_KEY])
+        result.fbc = cookies[FBC_KEY];
+    return result;
+}
+/**
+ * cookie 문자열을 key-value 객체로 파싱.
+ * "a=1; b=2; c=3" → { a: '1', b: '2', c: '3' }
+ */
+function parseCookieString(cookieStr) {
+    const result = {};
+    const pairs = cookieStr.split(';');
+    for (const pair of pairs) {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx <= 0)
+            continue;
+        const name = pair.slice(0, eqIdx).trim();
+        const value = pair.slice(eqIdx + 1).trim();
+        if (!name || !value)
+            continue;
+        // 잘못된 URI 인코딩(예: '%' 단독)에 decodeURIComponent가 URIError를 던질 수 있으므로
+        // 원본 raw 값 fallback. 다른 cookie 파싱이 중단되지 않게 한다.
+        try {
+            result[name] = decodeURIComponent(value);
+        }
+        catch {
+            result[name] = value;
+        }
+    }
+    return result;
+}
+
 /**
  * 웹 브라우저 환경 정보 수집기
  */
@@ -20,8 +80,25 @@ class WebContextCollector {
         if (campaign) {
             result.campaign = campaign;
         }
+        // Meta(Facebook) Pixel cookie read-only. fbclid → _fbc 변환 및 _fbp 자체 생성은
+        // plugin-cafe24의 MetaPixelLoader가 opt-in 3-조건 AND 충족 시에만 수행한다.
+        const meta = this.collectMetaContext();
+        if (meta) {
+            result.meta = meta;
+        }
         return result;
     }
+    /**
+     * Meta `_fbp`/`_fbc` 쿠키 read-only 수집. 호스트가 Meta Pixel을 설치했거나
+     * plugin-cafe24의 MetaPixelLoader가 쿠키를 발급해 둔 경우 read한다.
+     * 둘 다 부재 시 undefined 반환 (EventContext.meta omit).
+     */
+    collectMetaContext() {
+        const cookies = readMetaCookies();
+        if (!cookies.fbp && !cookies.fbc)
+            return undefined;
+        return cookies;
+    }
     /**
      * 디바이스 정보 수집
      */
@@ -120,10 +197,10 @@ class WebContextCollector {
             return 'Windows';
         if (/macintosh|mac os x/i.test(ua))
             return 'macOS';
-        if (/linux/i.test(ua))
-            return 'Linux';
         if (/android/i.test(ua))
             return 'Android';
+        if (/linux/i.test(ua))
+            return 'Linux';
         if (/iphone|ipad|ipod/i.test(ua))
             return 'iOS';
         if (/cros/i.test(ua))
@@ -190,7 +267,7 @@ class WebContextCollector {
         return version ? version[1] : undefined;
     }
     /**
-     * 캠페인 파라미터 수집 (UTM 5 + 광고 클릭 ID 4)
+     * 캠페인 파라미터 수집 (UTM 5 + 광고 클릭 ID 5 + 네이버 검색광고 8)
      * sessionStorage를 사용하여 MPA 페이지 전환 간에도 유지
      */
     collectCampaignContext() {
@@ -206,8 +283,9 @@ class WebContextCollector {
                 break;
             }
         }
-        // 새 캠페인이면 기존 sessionStorage 클리어 후 새로 저장
+        // 새 캠페인이면 기존 sessionStorage 클리어 후 새로 저장 + localStorage 백업
         if (hasUrlCampaign) {
+            const persistParams = {};
             for (const key of allKeys) {
                 try {
                     sessionStorage.removeItem(WebContextCollector.STORAGE_PREFIX + key);
@@ -221,8 +299,11 @@ class WebContextCollector {
                         sessionStorage.setItem(WebContextCollector.STORAGE_PREFIX + key, value);
                     }
                     catch { }
+                    persistParams[key] = value;
                 }
             }
+            // localStorage에 백업 (PG 리다이렉트 등 sessionStorage 유실 대비)
+            this.persistCampaignToLocalStorage(persistParams);
         }
         // sessionStorage에서 복원하여 CampaignContext 구성
         const campaign = {};
@@ -237,8 +318,58 @@ class WebContextCollector {
             }
             catch { }
         }
+        // sessionStorage에 캠페인이 없으면 localStorage 폴백 (도메인 복귀, 탭 전환 등)
+        if (!hasParams) {
+            const restored = this.restoreCampaignFromLocalStorage();
+            if (restored) {
+                for (const [paramKey, contextKey] of Object.entries(WebContextCollector.CAMPAIGN_PARAMS_MAP)) {
+                    const value = restored[paramKey];
+                    if (value) {
+                        campaign[contextKey] = value;
+                        hasParams = true;
+                        // sessionStorage에도 복원하여 후속 페이지에서 사용
+                        try {
+                            sessionStorage.setItem(WebContextCollector.STORAGE_PREFIX + paramKey, value);
+                        }
+                        catch { }
+                    }
+                }
+            }
+        }
         return hasParams ? campaign : undefined;
     }
+    /**
+     * 캠페인 파라미터를 localStorage에 타임스탬프와 함께 백업.
+     * PG 리다이렉트로 새 탭이 열리거나 sessionStorage가 초기화되는 경우 복원용.
+     */
+    persistCampaignToLocalStorage(params) {
+        try {
+            localStorage.setItem(WebContextCollector.CAMPAIGN_PERSIST_KEY, JSON.stringify({ params, timestamp: Date.now() }));
+        }
+        catch {
+            // localStorage 접근 불가 시 무시 (private browsing 등)
+        }
+    }
+    /**
+     * localStorage에서 캠페인 파라미터를 복원. 7일 초과 시 만료 처리.
+     */
+    restoreCampaignFromLocalStorage() {
+        try {
+            const raw = localStorage.getItem(WebContextCollector.CAMPAIGN_PERSIST_KEY);
+            if (!raw)
+                return null;
+            const data = JSON.parse(raw);
+            if (Date.now() - data.timestamp > WebContextCollector.CAMPAIGN_PERSIST_TTL_MS) {
+                // 만료된 데이터 삭제
+                localStorage.removeItem(WebContextCollector.CAMPAIGN_PERSIST_KEY);
+                return null;
+            }
+            return data.params;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * 앱 이름 가져오기 (meta 태그에서)
      */
@@ -287,8 +418,22 @@ WebContextCollector.CAMPAIGN_PARAMS_MAP = {
     'fbclid': 'fbclid',
     'msclkid': 'msclkid',
     'ttclid': 'ttclid',
+    'kclid': 'kclid',
+    // 네이버 검색광고 자동추적 파라미터
+    'n_media': 'n_media',
+    'n_query': 'n_query',
+    'n_ad': 'n_ad',
+    'n_ad_group': 'n_ad_group',
+    'n_keyword': 'n_keyword',
+    'n_keyword_id': 'n_keyword_id',
+    'n_rank': 'n_rank',
+    'n_campaign_type': 'n_campaign_type',
 };
 WebContextCollector.STORAGE_PREFIX = '__vircle_campaign_';
+/** localStorage 영구 백업 키 (PG 리다이렉트 등으로 sessionStorage 유실 시 복원용) */
+WebContextCollector.CAMPAIGN_PERSIST_KEY = '__vircle_campaign_persist';
+/** localStorage 캠페인 데이터 만료 기간: 7일 (광고 어트리뷰션 윈도우) */
+WebContextCollector.CAMPAIGN_PERSIST_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
  * Vircle Web SDK 전용 에러 클래스
@@ -1501,6 +1646,18 @@ class WebExtendedCryptoAdapter {
             throw new Error(`[WebExtendedCryptoAdapter] Encryption failed at step '${step}': ${errorMessage}`);
         }
     }
+    /**
+     * SHA-256 해시 — Meta CAPI em/ph 등 PII 매칭 키 생성용.
+     * Web Crypto API의 crypto.subtle.digest 사용.
+     */
+    async sha256(input) {
+        if (!this.subtle) {
+            throw new Error('Web Crypto API is required for SHA-256 hashing');
+        }
+        const encoder = new TextEncoder();
+        const digest = await this.subtle.digest('SHA-256', encoder.encode(input));
+        return this.arrayBufferToHex(digest);
+    }
     /**
      * Web Crypto API 사용 가능 여부
      */
@@ -1564,6 +1721,135 @@ class WebExtendedCryptoAdapter {
     }
 }
 
+/**
+ * @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도 동일 처리
+ */
+const DEFAULT_PARAM_NAME = '_vuid';
+class LinkDecorator {
+    constructor(options) {
+        this.allowedDomains = (options.allowedDomains ?? []).map((d) => d.toLowerCase());
+        this.paramName = options.paramName ?? DEFAULT_PARAM_NAME;
+        this.getAnonymousId = options.getAnonymousId;
+    }
+    /**
+     * 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() {
+        if (typeof document === 'undefined')
+            return;
+        if (this.allowedDomains.length === 0)
+            return;
+        if (this.clickHandler)
+            return; // 이미 시작됨
+        this.clickHandler = this.handleClick.bind(this);
+        // capture phase로 등록하여 다른 핸들러가 preventDefault 호출하기 전에 href 갱신.
+        // handleClick은 멱등이라 mousedown + click 둘 다 발화돼도 안전.
+        document.addEventListener('mousedown', this.clickHandler, { capture: true });
+        document.addEventListener('click', this.clickHandler, { capture: true });
+        document.addEventListener('auxclick', this.clickHandler, { capture: true });
+    }
+    stop() {
+        if (typeof document === 'undefined' || !this.clickHandler)
+            return;
+        document.removeEventListener('mousedown', this.clickHandler, { capture: true });
+        document.removeEventListener('click', this.clickHandler, { capture: true });
+        document.removeEventListener('auxclick', this.clickHandler, { capture: true });
+        this.clickHandler = undefined;
+    }
+    /**
+     * 외부 호출용 — 임의 URL에 vuid 파라미터 부착. 화이트리스트 매치되지 않으면 원본 URL 반환.
+     * 호스트가 동적으로 만든 URL 등에 사용 가능.
+     */
+    decorate(href) {
+        const vuid = this.getAnonymousId();
+        if (!vuid)
+            return href;
+        let url;
+        try {
+            url = new URL(href, typeof location !== 'undefined' ? location.href : 'http://localhost');
+        }
+        catch {
+            return href; // mailto:, javascript:, tel: 등 invalid URL
+        }
+        // http/https 외 스킴(javascript:, data:, blob: 등)은 navigation link가 아니므로 skip
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return href;
+        if (!this.isAllowedDomain(url.hostname))
+            return href;
+        // same-origin link는 동일 SDK 인스턴스에서 동일 vuid 사용하므로 부착 불필요 — URL noise 회피
+        if (typeof location !== 'undefined' && url.origin === location.origin)
+            return href;
+        if (url.searchParams.get(this.paramName))
+            return href; // 이미 부착됨 — 멱등
+        url.searchParams.set(this.paramName, vuid);
+        return url.toString();
+    }
+    handleClick(event) {
+        const target = event.target;
+        if (!target || typeof target.closest !== 'function')
+            return;
+        const anchor = target.closest('a[href]');
+        if (!anchor)
+            return;
+        const href = anchor.getAttribute('href');
+        if (!href)
+            return;
+        // mailto:, javascript:, tel:, # 등 non-http 스킴은 무시
+        if (/^(mailto:|javascript:|tel:|sms:|#)/i.test(href))
+            return;
+        const decorated = this.decorate(href);
+        if (decorated !== href) {
+            anchor.setAttribute('href', decorated);
+        }
+    }
+    /**
+     * hostname 화이트리스트 매칭.
+     * - `.example.com` → suffix match (서브도메인 포함)
+     * - `example.com` → exact match
+     */
+    isAllowedDomain(hostname) {
+        const lower = hostname.toLowerCase();
+        for (const domain of this.allowedDomains) {
+            if (domain.startsWith('.')) {
+                // suffix match: '.vircle.co.kr'은 shop.vircle.co.kr / lounge.vircle.co.kr 모두 허용
+                if (lower === domain.slice(1) || lower.endsWith(domain)) {
+                    return true;
+                }
+            }
+            else if (lower === domain) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+
 /**
  * Web 플랫폼용 Vircle SDK
  *
@@ -1794,6 +2080,31 @@ class VircleWeb extends VircleCore {
         if (this.webConfig.singlePageApp) {
             this.setupSPATracking();
         }
+        // F-4b 크로스 도메인 Link Decoration — outbound link에 ?_vuid= 자동 부착
+        if (this.webConfig.linkDecoration?.enabled) {
+            this.setupLinkDecoration();
+        }
+    }
+    /**
+     * F-4b Link Decoration 활성화 — outbound link click 시 ?_vuid= 자동 부착.
+     * @private
+     */
+    setupLinkDecoration() {
+        const cfg = this.webConfig.linkDecoration;
+        if (!cfg?.enabled)
+            return;
+        const allowedDomains = cfg.allowedDomains ?? [];
+        if (allowedDomains.length === 0) {
+            console.warn('[Vircle] linkDecoration.enabled=true이지만 allowedDomains가 비어 있어 활성화되지 않습니다. ' +
+                'vuid 누출 방지를 위해 도메인 화이트리스트를 명시하세요.');
+            return;
+        }
+        this.linkDecorator = new LinkDecorator({
+            allowedDomains,
+            paramName: cfg.paramName,
+            getAnonymousId: () => this.getAnonymousId(),
+        });
+        this.linkDecorator.start();
     }
     /**
      * 에러 추적 설정
@@ -2080,6 +2391,11 @@ class VircleWeb extends VircleCore {
                 history.replaceState = this.originalReplaceState;
                 this.originalReplaceState = undefined;
             }
+            // F-4b LinkDecorator click 핸들러 해제
+            if (this.linkDecorator) {
+                this.linkDecorator.stop();
+                this.linkDecorator = undefined;
+            }
             // Idle 작업 정리
             // Flush pending tasks
             await this.flush();
@@ -2130,5 +2446,5 @@ class VircleWeb extends VircleCore {
     }
 }
 
-export { IndexedDBAdapter, LocalStorageAdapter, StorageFactory, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebExtendedCryptoAdapter, VircleWeb as default };
+export { IndexedDBAdapter, LinkDecorator, LocalStorageAdapter, StorageFactory, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebExtendedCryptoAdapter, VircleWeb as default };
 //# sourceMappingURL=index.esm.js.map