@adstage/web-sdk 3.0.8 → 3.0.10

package/dist/index.d.ts

@@ -433,14 +433,6 @@ declare class EventsModule implements BaseModule {
      * 모듈 설정 반환
      */
     getConfig(): AdStageConfig | null;
-    /**
-     * 사용자 ID 설정
-     */
-    setUserId(userId: string): void;
-    /**
-     * 현재 사용자 ID 반환
-     */
-    getUserId(): string | undefined;
     /**
      * 사용자 속성 설정
      */
@@ -489,10 +481,43 @@ declare class EventsModule implements BaseModule {
      * @param properties 이벤트 속성
      */
     track(eventName: string, properties?: EventProperties): Promise<void>;
+    /**
+     * Attribution 등록 (서버 기반 Attribution ID 패턴)
+     *
+     * 사용 사례:
+     * 1. 앱 설치 시 Install Referrer 전송
+     * 2. 웹 첫 방문 시 URL 파라미터 전송
+     *
+     * @param deviceId 디바이스 고유 ID
+     * @returns Attribution ID 및 파싱된 정보
+     */
+    registerAttribution(deviceId: string): Promise<{
+        attributionId: string;
+        channel: string;
+        campaign?: string;
+        attribution: Record<string, any>;
+        installedAt: Date;
+        expiresAt: Date;
+    } | null>;
+    /**
+     * 저장된 Attribution ID 반환
+     */
+    getAttributionId(): string | null;
+    /**
+     * Attribution ID로 이벤트 전송 (별칭 메서드)
+     * track() 메서드가 자동으로 Attribution ID를 사용하므로 동일하게 동작
+     * @param eventName 이벤트 이름
+     * @param properties 이벤트 속성
+     */
+    trackWithAttributionId(eventName: string, properties?: EventProperties): Promise<void>;
     /**
      * 서버에 이벤트 전송
      */
     private sendEventToServer;
+    /**
+     * 서버에 Attribution 등록
+     */
+    private sendAttributionToServer;
 }
 
 /**
@@ -525,7 +550,7 @@ declare class AdStage {
      */
     static getInstance(): AdStage;
     /**
-     * 편의성을 위한 정적 모듈 접근자들
+     * 편의성을 위한 정적 모듈 접근자들 (안전장치 포함)
      */
     static get ads(): AdsModule;
     static get events(): EventsModule;
@@ -534,6 +559,11 @@ declare class AdStage {
      * SDK 리셋 (테스트용)
      */
     static reset(): void;
+    /**
+     * Device ID 생성 (브라우저 fingerprint 기반)
+     * localStorage에 저장하여 재사용
+     */
+    private generateDeviceId;
     /**
      * 디버그용 메서드들
      */
@@ -566,18 +596,6 @@ declare class AdStage {
  * });
  */
 declare function track(eventName: string, properties?: EventProperties): Promise<void>;
-/**
- * 사용자 ID 설정
- * @param userId 사용자 ID
- *
- * @example
- * setUserId('user123');
- */
-declare function setUserId(userId: string): void;
-/**
- * 현재 사용자 ID 반환
- */
-declare function getUserId(): string | undefined;
 /**
  * 사용자 속성 설정
  * @param properties 사용자 속성 객체
@@ -622,6 +640,109 @@ declare function useAdStageContext(): AdStageContextType;
  */
 declare function useAdStageInstance(): typeof AdStage | null;
 
+/**
+ * AdStage SDK - Tracking Parameters Module
+ * URL에서 광고 추적 파라미터를 자동으로 추출하여 저장
+ *
+ * 지원 파라미터:
+ * - 클릭 ID: gclid, fbclid, ttclid, nclid (플랫폼별)
+ * - 캠페인 정보: campaign, campaign_id, ad_group, ad_creative, term
+ * - UTM 파라미터: utm_source, utm_medium, utm_campaign, utm_content, utm_term
+ *
+ * 동작 방식:
+ * 1. SDK 초기화 시 URL에서 파라미터 자동 추출
+ * 2. sessionStorage에 저장 (SPA 페이지 전환 시에도 유지)
+ * 3. EventsModule에서 track() 호출 시 자동으로 attribution 정보 주입
+ */
+interface TrackingParams {
+    gclid?: string;
+    fbclid?: string;
+    ttclid?: string;
+    nclid?: string;
+    liclid?: string;
+    msclkid?: string;
+    twclid?: string;
+    channel?: string;
+    campaign?: string;
+    campaign_id?: string;
+    ad_group?: string;
+    ad_group_id?: string;
+    ad_creative?: string;
+    creative_id?: string;
+    term?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+}
+/**
+ * TrackingParams 모듈
+ * URL 파라미터 추출 및 저장 관리
+ */
+declare class TrackingParamsModule {
+    private static readonly STORAGE_KEY;
+    private static readonly CLICK_ID_KEYS;
+    private static readonly CAMPAIGN_KEYS;
+    private static readonly UTM_KEYS;
+    private static readonly ALL_KEYS;
+    /**
+     * 현재 URL에서 추적 파라미터 추출 및 저장
+     * SDK 초기화 시 자동 호출됨
+     *
+     * 지원 형식:
+     * 1. 일반 URL 파라미터: ?gclid=abc123&campaign=summer
+     * 2. adstage_referrer 인코딩 파라미터: ?adstage_referrer=channel%3Dgoogle.ads%26gclid%3Dabc123
+     */
+    static captureFromUrl(): TrackingParams | null;
+    /**
+     * 추적 파라미터를 sessionStorage에 저장
+     * (SPA 페이지 전환 시에도 유지)
+     */
+    static store(params: TrackingParams): void;
+    /**
+     * 저장된 추적 파라미터 반환
+     * EventsModule에서 track() 호출 시 사용됨
+     */
+    static get(): TrackingParams | null;
+    /**
+     * 저장된 추적 파라미터 삭제
+     */
+    static clear(): void;
+    /**
+     * 현재 추적 파라미터 보유 여부 확인
+     */
+    static hasParams(): boolean;
+    /**
+     * 특정 클릭 ID 보유 여부 확인
+     * 어트리뷰션이 가능한 상태인지 체크
+     */
+    static hasClickId(): boolean;
+    /**
+     * Click 이벤트 자동 전송 여부 확인
+     * 새로운 클릭 ID가 발견되면 true 반환
+     */
+    static shouldSendClickEvent(): boolean;
+    /**
+     * Click 이벤트 전송 완료 마킹
+     */
+    static markClickEventSent(): void;
+    /**
+     * Click 이벤트 전송 여부 확인
+     */
+    static isClickEventSent(): boolean;
+    /**
+     * Event 스키마의 attribution 객체로 변환
+     * EventsModule에서 사용
+     *
+     * 변환 규칙:
+     * - 클릭 ID, channel: 그대로 전달
+     * - 광고 플랫폼 파라미터: snake_case → camelCase 변환 (웹 호환)
+     * - UTM 파라미터: snake_case 그대로 유지 (앱/웹 공통 표준)
+     */
+    static toAttributionObject(): Record<string, any> | null;
+}
+
 /**
  * AdStage Web SDK
  * 네임스페이스 아키텍처 기반 SDK
@@ -630,4 +751,4 @@ declare function useAdStageInstance(): typeof AdStage | null;
 declare const SDK_VERSION = "2.0.0";
 declare const SUPPORTED_MODULES: readonly ["ads", "events", "config"];
 
-export { AdEventType, AdOptions, AdSlot, AdStage, AdStageConfig, AdStageProvider, AdType, Advertisement, ApiResponse, BaseModule, EventProperties, ModuleName, OrganizationInfo, SDK_VERSION, SUPPORTED_MODULES, UserProperties, getUserId, getUserProperties, setUserId, setUserProperties, track, useAdStageContext, useAdStageInstance };
+export { AdEventType, AdOptions, AdSlot, AdStage, AdStageConfig, AdStageProvider, AdType, Advertisement, ApiResponse, BaseModule, EventProperties, ModuleName, OrganizationInfo, SDK_VERSION, SUPPORTED_MODULES, TrackingParams, TrackingParamsModule, UserProperties, getUserProperties, setUserProperties, track, useAdStageContext, useAdStageInstance };