@adstage/web-sdk 3.0.14 → 3.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "3.0.14",
+  "version": "3.0.16",
   "description": "AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/core/{adstage.ts → AdStage.ts}

@@ -10,6 +10,7 @@ import { EventsModule } from '../modules/events/events-module';
 import { ViewableEventTracker } from '../managers/ads/viewable-event-tracker';
 import { endpoints } from '../constants/endpoints';
 import { TrackingParamsModule } from '../modules/tracking/tracking-params';
+import { installTrackingLinkDecorator, decorateTrackingUrl } from '../utils/tracking-link-decorator';
 
 export class AdStage {
   private static instance: AdStage;
@@ -100,6 +101,17 @@ export class AdStage {
         }
       }
 
+      // 🔗 아웃바운드 트래킹 링크(adg.im) 데코레이터 설치.
+      // 페이지의 adg.im 링크 클릭 시 방문자 신원(클릭 ID + attribution_id)을 부착 → redirect 서버가
+      // Play Install Referrer 로 전달 → 네이티브 설치가 원본 채널(google.ads 등) 인계 (web→app 연결).
+      // 신원 값은 클릭 시점에 읽으므로(비동기 attribution 등록 이후 반영) getter 로 전달한다.
+      installTrackingLinkDecorator({
+        getClickParams: () => TrackingParamsModule.get(),
+        getAttributionId: () => instance.events.getAttributionId(),
+        domains: instance._config?.trackingLinkDomains,
+        debug: config.debug,
+      });
+
       // 🎯 Click 이벤트 자동 전송 (새로운 클릭 ID 발견 시)
       const shouldSend = TrackingParamsModule.shouldSendClickEvent();
       if (config.debug) {
@@ -237,6 +249,25 @@ export class AdStage {
     return AdStage.instance?._config || null;
   }
 
+  /**
+   * 트래킹 링크(adg.im 등)에 현재 방문자 신원(클릭 ID + attribution_id)을 부착해 반환.
+   * <a> 클릭은 자동 데코레이션되지만, window.open() 등 프로그램적 이동에는 이 헬퍼를 직접 사용한다.
+   * 트래킹 도메인이 아니면 원본 URL 을 그대로 반환한다.
+   */
+  public static decorateUrl(url: string): string {
+    try {
+      const instance = AdStage.getInstance();
+      return decorateTrackingUrl(url, {
+        clickParams: TrackingParamsModule.get(),
+        attributionId: instance.events.getAttributionId(),
+        domains: instance._config?.trackingLinkDomains,
+        baseHref: typeof window !== 'undefined' ? window.location.href : undefined,
+      });
+    } catch (_) {
+      return url;
+    }
+  }
+
   /**
    * SDK 인스턴스 반환 (공개 메소드로 변경)
    */

package/src/events/global-events.ts

@@ -3,7 +3,7 @@
  * Firebase Analytics와 유사한 간단한 API 제공
  */
 
-import AdStage from '../core/adstage';
+import AdStage from '../core/AdStage';
 import type { EventProperties } from '../modules/events/events-module';
 
 /**

package/src/index.ts

@@ -4,8 +4,8 @@
  */
 
 // 메인 네임스페이스 클래스
-export { default as AdStage } from './core/adstage';
-import AdStageCore from './core/adstage';
+export { default as AdStage } from './core/AdStage';
+import AdStageCore from './core/AdStage';
 
 // 전역 이벤트 함수들 (Firebase 스타일)
 export { track, setUserProperties, getUserProperties } from './events/global-events';

package/src/modules/tracking/tracking-params.ts

@@ -16,12 +16,21 @@
 export interface TrackingParams {
   // ========== 클릭 ID (광고 플랫폼별) ==========
   gclid?: string; // Google Ads Click ID
+  gbraid?: string; // Google Ads (iOS/web-to-app)
+  wbraid?: string; // Google Ads (web-to-web)
   fbclid?: string; // Meta Ads (Facebook) Click ID
   ttclid?: string; // TikTok Ads Click ID
   nclid?: string; // Naver SA Click ID
+  naverclk?: string; // Naver SA Click ID (legacy)
   liclid?: string; // LinkedIn Ads Click ID
-  msclkid?: string; // Microsoft Ads Click ID
+  li_fat_id?: string; // LinkedIn Ads Click ID (공식)
+  msclkid?: string; // Microsoft Ads (Bing) Click ID
   twclid?: string; // Twitter Ads Click ID
+  sccid?: string; // Snapchat Ads Click ID
+  ScCid?: string; // Snapchat Ads Click ID (대문자형)
+  yclid?: string; // Yahoo Ads Click ID
+  pnclid?: string; // Pinterest Ads Click ID
+  kakaoclk?: string; // Kakao Moment Click ID
 
   // ========== 광고 계층 정보 ==========
   channel?: string; // 광고 채널 (google.ads, meta.ads, naver.searchad 등)
@@ -33,6 +42,14 @@ export interface TrackingParams {
   creative_id?: string; // 광고소재 ID
   term?: string; // 키워드
 
+  // ========== 카카오 키워드광고 파라미터 ==========
+  k_campaign?: string; // 카카오 키워드광고 캠페인 ID
+  k_adgroup?: string; // 카카오 키워드광고 광고그룹 ID
+  k_keyword?: string; // 카카오 키워드광고 등록 키워드
+  k_keyword_id?: string; // 카카오 키워드광고 키워드 ID
+  k_creative?: string; // 카카오 키워드광고 소재 ID
+  k_rank?: string; // 카카오 키워드광고 노출 순위
+
   // ========== UTM 파라미터 ==========
   utm_source?: string; // 트래픽 소스 (예: google, facebook, newsletter)
   utm_medium?: string; // 마케팅 매체 (예: cpc, banner, email)
@@ -48,10 +65,13 @@ export interface TrackingParams {
 export class TrackingParamsModule {
   private static readonly STORAGE_KEY = 'adstage_tracking_params';
 
-  // 추출할 파라미터 키 정의
-  private static readonly CLICK_ID_KEYS = ['gclid', 'fbclid', 'ttclid', 'nclid', 'liclid', 'msclkid', 'twclid'];
+  // 추출할 파라미터 키 정의 (백엔드 extractClickId/detectChannel 와 동일하게 유지)
+  private static readonly CLICK_ID_KEYS = [
+    'gclid', 'gbraid', 'wbraid', 'fbclid', 'ttclid', 'twclid', 'li_fat_id', 'liclid',
+    'msclkid', 'sccid', 'ScCid', 'yclid', 'pnclid', 'nclid', 'naverclk', 'kakaoclk',
+  ];
 
-  private static readonly CAMPAIGN_KEYS = ['channel', 'campaign', 'campaign_id', 'ad_group', 'ad_group_id', 'ad_creative', 'creative_id', 'term'];
+  private static readonly CAMPAIGN_KEYS = ['channel', 'campaign', 'campaign_id', 'ad_group', 'ad_group_id', 'ad_creative', 'creative_id', 'term', 'k_campaign', 'k_adgroup', 'k_keyword', 'k_keyword_id', 'k_creative', 'k_rank'];
 
   private static readonly UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
 
@@ -123,13 +143,21 @@ export class TrackingParamsModule {
     if (hasParams) {
       // 클릭 ID 기반으로 channel 자동 추론 (channel이 없는 경우)
       if (!params.channel) {
-        if (params.gclid) params.channel = 'google.ads';
+        // 백엔드 detectChannel 과 동일한 우선순위/채널명 유지
+        if (params.gclid || params.gbraid || params.wbraid) params.channel = 'google.ads';
         else if (params.fbclid) params.channel = 'meta.ads';
         else if (params.ttclid) params.channel = 'tiktok.ads';
-        else if (params.nclid) params.channel = 'naver.searchad';
-        else if (params.liclid) params.channel = 'linkedin.ads';
-        else if (params.msclkid) params.channel = 'microsoft.ads';
         else if (params.twclid) params.channel = 'twitter.ads';
+        else if (params.li_fat_id || params.liclid) params.channel = 'linkedin.ads';
+        else if (params.msclkid) params.channel = 'microsoft.ads';
+        else if (params.sccid || params.ScCid) params.channel = 'snapchat.ads';
+        else if (params.yclid) params.channel = 'yahoo.ads';
+        else if (params.pnclid) params.channel = 'pinterest.ads';
+        else if (params.naverclk || params.nclid) params.channel = 'naver.searchad';
+        else if (params.kakaoclk) params.channel = 'kakao.moment';
+        // 카카오 키워드광고: utm_source=kakao & utm_medium=keyword 또는 k_ 파라미터
+        else if (params.utm_source === 'kakao' && params.utm_medium === 'keyword') params.channel = 'kakao.keyword';
+        else if (params.k_campaign || params.k_keyword) params.channel = 'kakao.keyword';
       }
 
       TrackingParamsModule.store(params);
@@ -315,6 +343,14 @@ export class TrackingParamsModule {
     if (params.creative_id) attribution.creativeId = params.creative_id;
     if (params.term) attribution.term = params.term;
 
+    // ========== 카카오 키워드광고 파라미터 ==========
+    if (params.k_campaign) attribution.campaignId = attribution.campaignId || params.k_campaign;
+    if (params.k_adgroup) attribution.adGroupId = attribution.adGroupId || params.k_adgroup;
+    if (params.k_keyword) attribution.keyword = params.k_keyword;
+    if (params.k_keyword_id) attribution.keywordId = params.k_keyword_id;
+    if (params.k_creative) attribution.creativeId = attribution.creativeId || params.k_creative;
+    if (params.k_rank) attribution.adRank = params.k_rank;
+
     // ========== UTM 파라미터 (앱/웹 공통 - snake_case 유지) ==========
     if (params.utm_source) attribution.utm_source = params.utm_source;
     if (params.utm_medium) attribution.utm_medium = params.utm_medium;

package/src/react/ad-stage-provider.tsx

@@ -4,7 +4,7 @@
  */
 
 import React, { createContext, useContext, useEffect, useState, ReactNode } from 'react';
-import AdStage from '../core/adstage';
+import AdStage from '../core/AdStage';
 import { AdStageConfig } from '../types/config';
 
 interface AdStageContextType {

package/src/types/config.ts

@@ -26,7 +26,13 @@ export interface AdStageConfig {
   
   /** 플레이스홀더 스타일 모드 (기본값: 'subtle') */
   placeholderMode?: 'invisible' | 'transparent' | 'subtle' | 'minimal' | 'debug' | 'legacy';
-  
+
+  /**
+   * 아웃바운드 트래킹 링크 데코레이션 대상 도메인 (기본값: ['adg.im'])
+   * 이 도메인으로 향하는 <a> 클릭 시 방문자 신원(클릭 ID + attribution_id)을 자동 부착해
+   * web→app 어트리뷰션이 끊기지 않게 한다.
+   */
+  trackingLinkDomains?: string[];
 
 }
 

package/src/utils/api-headers.ts

@@ -6,11 +6,14 @@
 export class ApiHeaders {
   /**
    * 표준 API 헤더 생성
+   *
+   * 주의: `User-Agent`는 브라우저 forbidden header라 fetch에서 수동 설정하면 안 된다.
+   * (Chromium은 무시하지만 Safari/WebKit은 설정값을 CORS preflight에 포함시켜
+   *  서버가 허용하지 않으면 요청 자체가 차단됨.) 브라우저가 모든 요청에 진짜
+   * `User-Agent`를 자동 첨부하므로, 서버는 `req.headers['user-agent']`로 동일한 값을 받는다.
    */
   static create(apiKey: string, options?: {
     contentType?: string;
-    userAgent?: string;
-    currentUrl?: string;
   }): Record<string, string> {
     if (!apiKey) {
       throw new Error('API key is required');
@@ -21,32 +24,20 @@ export class ApiHeaders {
       'Content-Type': options?.contentType || 'application/json'
     };
 
-    // User-Agent는 이벤트 추적에서 실제로 사용됨
-    if (typeof navigator !== 'undefined') {
-      headers['User-Agent'] = options?.userAgent || navigator.userAgent;
-    }
-
-    // X-Current-URL은 현재 서버에서 사용하지 않으므로 제거
-    // 필요시 이벤트 데이터 body에 포함
+    // X-Current-URL 등 부가 정보는 HTTP 헤더가 아닌 이벤트 데이터 body에 포함
 
     return headers;
   }
 
   /**
    * 이벤트 추적용 헤더 생성
-   * User-Agent는 서버에서 실제로 사용됨
+   *
+   * 디바이스 `userAgent`는 HTTP 헤더가 아니라 요청 body(eventData) 또는 브라우저가
+   * 자동 첨부하는 `User-Agent`로 전달된다. (서버 advertisement 컨트롤러는
+   * `req.headers['user-agent']`를 직접 사용.) 헤더 수동 override는 Safari CORS
+   * preflight를 깨뜨리므로 하지 않는다. 시그니처는 호출처 호환을 위해 유지.
    */
-  static createForEvents(apiKey: string, eventData?: Record<string, any>): Record<string, string> {
-    const baseHeaders = ApiHeaders.create(apiKey);
-    
-    // User-Agent 오버라이드 (서버에서 실제 사용)
-    if (eventData?.userAgent) {
-      baseHeaders['User-Agent'] = eventData.userAgent;
-    }
-
-    // 다른 정보들은 HTTP 헤더가 아닌 이벤트 데이터 body에 포함하는 것이 적절
-    // (currentUrl, referrer 등은 POST body로 전송)
-
-    return baseHeaders;
+  static createForEvents(apiKey: string, _eventData?: Record<string, any>): Record<string, string> {
+    return ApiHeaders.create(apiKey);
   }
 }

package/src/utils/config-utils.ts

@@ -12,7 +12,7 @@ export class ConfigUtils {
   static getConfig(): AdStageConfig | null {
     // AdStage 클래스 동적 임포트로 순환 참조 방지
     try {
-      const { AdStage } = require('../core/adstage');
+      const { AdStage } = require('../core/AdStage');
       return AdStage.getConfig();
     } catch {
       return null;

package/src/utils/tracking-link-decorator.ts

@@ -0,0 +1,135 @@
+/**
+ * 트래킹 링크 데코레이터 (web → app 신원 전달)
+ *
+ * 웹 페이지에서 adg.im(트래킹/딥링크) 링크로 나가는 클릭 시점에, 현재 방문자의 신원
+ * (클릭 ID = gclid 등 + attribution_id)을 해당 링크 URL에 부착한다.
+ *
+ * redirect 서버(deeplink-redirect.controller)는 이 값을 Google Play Install Referrer 로
+ * 전달하고, 네이티브 설치 이벤트가 그 referrer 를 백엔드로 보내 원본 채널(google.ads 등)을
+ * 인계받는다. → 검색광고(웹 랜딩)→앱 설치 경로에서 어트리뷰션이 organic 으로 새는 것을 막는다.
+ *
+ * Google Play Install Referrer API 는 referrer= 파라미터만 캡처하므로, attribution_id 를
+ * redirect 단계에서 referrer 문자열 안에 넣어야 한다(서버 측 처리). 여기서는 redirect 서버가
+ * 읽을 수 있도록 쿼리로만 전달하면 된다.
+ */
+
+// SDK 의 TrackingParamsModule.CLICK_ID_KEYS 와 동일하게 유지 (백엔드 extractClickId 와도 일치)
+const CLICK_ID_KEYS = [
+  'gclid', 'gbraid', 'wbraid', 'fbclid', 'ttclid', 'twclid', 'li_fat_id', 'liclid',
+  'msclkid', 'sccid', 'ScCid', 'yclid', 'pnclid', 'nclid', 'naverclk', 'kakaoclk',
+];
+
+// 기본 트래킹 도메인 (딥링크 단축 도메인)
+const DEFAULT_TRACKING_DOMAINS = ['adg.im'];
+
+function hostMatches(hostname: string, domains: string[]): boolean {
+  const h = (hostname || '').toLowerCase();
+  return domains.some((d) => {
+    const dd = (d || '').toLowerCase();
+    return !!dd && (h === dd || h.endsWith('.' + dd));
+  });
+}
+
+export interface DecorateInput {
+  /** 현재 방문자의 클릭 파라미터 (TrackingParamsModule.get() 결과) */
+  clickParams?: Record<string, any> | null;
+  /** 현재 방문자의 attribution_id (events.getAttributionId() 결과) */
+  attributionId?: string | null;
+  /** 데코레이션 대상 도메인 (기본 ['adg.im']) */
+  domains?: string[];
+  /** 상대 URL 해석용 base (보통 window.location.href) */
+  baseHref?: string;
+}
+
+/**
+ * URL 이 트래킹 도메인으로 향하면 클릭 ID + attribution_id 를 부착한 새 URL 반환.
+ * 트래킹 도메인이 아니거나 파싱 실패 시 원본 URL 그대로 반환.
+ * 기존에 같은 파라미터가 이미 있으면 덮어쓰지 않는다.
+ */
+export function decorateTrackingUrl(rawUrl: string, input: DecorateInput = {}): string {
+  if (!rawUrl) return rawUrl;
+  const domains = input.domains && input.domains.length ? input.domains : DEFAULT_TRACKING_DOMAINS;
+
+  try {
+    const url = new URL(rawUrl, input.baseHref);
+    if (!hostMatches(url.hostname, domains)) return rawUrl;
+
+    const clickParams = input.clickParams || null;
+    if (clickParams) {
+      for (const key of CLICK_ID_KEYS) {
+        const value = clickParams[key];
+        if (value && !url.searchParams.has(key)) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+
+    if (input.attributionId && !url.searchParams.has('attribution_id')) {
+      url.searchParams.set('attribution_id', input.attributionId);
+    }
+
+    return url.toString();
+  } catch (_) {
+    return rawUrl;
+  }
+}
+
+export interface InstallDecoratorOptions {
+  getClickParams: () => Record<string, any> | null;
+  getAttributionId: () => string | null;
+  domains?: string[];
+  debug?: boolean;
+}
+
+let installed = false;
+
+/**
+ * document 레벨 capture-phase 클릭 리스너를 설치한다.
+ * 내비게이션 직전에 adg.im 링크의 href 를 신원 파라미터로 갱신 → SPA 동적 링크/새 탭(auxclick) 포함 대응.
+ * 신원 값은 클릭 시점에 읽으므로(비동기 attribution 등록 이후 값 반영) getter 로 전달받는다.
+ */
+export function installTrackingLinkDecorator(options: InstallDecoratorOptions): void {
+  if (installed) return;
+  if (typeof document === 'undefined') return;
+  installed = true;
+
+  const domains = options.domains && options.domains.length ? options.domains : DEFAULT_TRACKING_DOMAINS;
+
+  const handler = (event: Event) => {
+    try {
+      const target = event.target as Element | null;
+      if (!target || typeof (target as any).closest !== 'function') return;
+      const anchor = target.closest('a[href]') as HTMLAnchorElement | null;
+      if (!anchor) return;
+
+      const href = anchor.getAttribute('href');
+      if (!href) return;
+
+      const decorated = decorateTrackingUrl(href, {
+        clickParams: options.getClickParams(),
+        attributionId: options.getAttributionId(),
+        domains,
+        baseHref: typeof window !== 'undefined' ? window.location.href : undefined,
+      });
+
+      if (decorated !== href) {
+        anchor.setAttribute('href', decorated);
+        if (options.debug) {
+          // eslint-disable-next-line no-console
+          console.log('🔗 [AdStage] Decorated tracking link:', decorated);
+        }
+      }
+    } catch (_) {
+      // no-op: 데코레이션 실패가 사용자 클릭/내비게이션을 막아선 안 됨
+    }
+  };
+
+  // capture phase 로 navigation 직전에 실행
+  document.addEventListener('click', handler, true);
+  document.addEventListener('auxclick', handler, true);
+}
+
+/** 테스트용: 설치 플래그 리셋 */
+export function __resetTrackingLinkDecorator(): void {
+  installed = false;
+}