@adstage/web-sdk 3.0.14 → 3.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "3.0.14",
+  "version": "3.0.15",
   "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/modules/tracking/tracking-params.ts

@@ -33,6 +33,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)
@@ -51,7 +59,7 @@ export class TrackingParamsModule {
   // 추출할 파라미터 키 정의
   private static readonly CLICK_ID_KEYS = ['gclid', 'fbclid', 'ttclid', 'nclid', 'liclid', 'msclkid', 'twclid'];
 
-  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'];
 
@@ -130,6 +138,9 @@ export class TrackingParamsModule {
         else if (params.liclid) params.channel = 'linkedin.ads';
         else if (params.msclkid) params.channel = 'microsoft.ads';
         else if (params.twclid) params.channel = 'twitter.ads';
+        // 카카오 키워드광고: 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 +326,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/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);
   }
 }