@adstage/web-sdk 3.0.13 → 3.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "3.0.13",
+  "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/core/adstage.ts

@@ -109,8 +109,11 @@ export class AdStage {
         }
       }
 
-      // � 서버에 Attribution 자동 등록 (클릭 ID가 있는 경우, 단 URL로 이미 전달된 경우는 생략)
-      if (!aidFromUrl && trackingParams && TrackingParamsModule.hasClickId()) {
+      // 🎯 서버에 Attribution 자동 등록 (클릭 ID 또는 channel이 있는 경우, 단 URL로 이미 전달된 경우는 생략)
+      const hasClickId = TrackingParamsModule.hasClickId();
+      const hasChannel = !!(trackingParams && trackingParams.channel);
+
+      if (!aidFromUrl && trackingParams && (hasClickId || hasChannel)) {
         // Attribution 등록을 Promise로 처리
         const attributionPromise = (async () => {
           try {

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);
@@ -217,7 +228,7 @@ export class TrackingParamsModule {
 
   /**
    * Click 이벤트 자동 전송 여부 확인
-   * 새로운 클릭 ID가 발견되면 true 반환
+   * 새로운 클릭 ID 또는 channel 파라미터가 발견되면 true 반환
    */
   public static shouldSendClickEvent(): boolean {
     if (typeof window === 'undefined') {
@@ -225,24 +236,33 @@ export class TrackingParamsModule {
     }
 
     const params = TrackingParamsModule.get();
-    if (!params || !TrackingParamsModule.hasClickId()) {
+    if (!params) {
+      return false;
+    }
+
+    // 클릭 ID 또는 channel 파라미터가 있어야 함
+    const hasClickId = TrackingParamsModule.hasClickId();
+    const hasChannel = !!params.channel;
+
+    if (!hasClickId && !hasChannel) {
       return false;
     }
 
-    // 현재 클릭 ID 추출
-    const currentClickId =
-      params.gclid || params.fbclid || params.ttclid || params.nclid || params.liclid || params.msclkid || params.twclid;
+    // 현재 식별자 추출 (clickId 우선, 없으면 channel+term 조합)
+    const currentIdentifier = hasClickId
+      ? (params.gclid || params.fbclid || params.ttclid || params.nclid || params.liclid || params.msclkid || params.twclid)
+      : `${params.channel || ''}:${params.term || ''}`;
 
-    if (!currentClickId) {
+    if (!currentIdentifier) {
       return false;
     }
 
-    // 이미 처리된 클릭 ID인지 확인 (중복 방지)
+    // 이미 처리된 식별자인지 확인 (중복 방지)
     const lastClickId = sessionStorage.getItem('adstage_last_click_id');
 
-    // 새로운 클릭 ID면 전송 필요
-    if (currentClickId !== lastClickId) {
-      sessionStorage.setItem('adstage_last_click_id', currentClickId);
+    // 새로운 식별자면 전송 필요
+    if (currentIdentifier !== lastClickId) {
+      sessionStorage.setItem('adstage_last_click_id', currentIdentifier);
       return true;
     }
 
@@ -306,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);
   }
 }