@adstage/web-sdk/src/utils/ad-click-handler.ts

AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration

import { AdEventType } from '../types/advertisement';
import type { AdSlot, Advertisement } from '../types/advertisement';

/**
 * 광고 클릭 이벤트 핸들러 유틸리티
 * 모든 광고 타입에서 일관된 클릭 이벤트 처리를 위한 공통 컴포넌트
 */
export class AdClickHandler {
  /**
   * 광고 요소에 클릭 이벤트를 추가하는 공통 함수
   * @param element - 클릭 이벤트를 추가할 DOM 요소
   * @param advertisement - 광고 데이터
   * @param slot - 광고 슬롯 정보
   * @param trackEventCallback - 이벤트 추적 콜백 함수
   * @param debug - 디버그 모드
   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
   */
  static addClickEvent(
    element: HTMLElement,
    advertisement: Advertisement,
    slot: AdSlot,
    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
    debug: boolean = false,
    adTypeLabel?: string
  ): void {
    // linkUrl이 없으면 클릭 이벤트 추가하지 않음
    if (!advertisement.linkUrl) {
      return;
    }

    // 커서 스타일 설정
    element.style.cursor = 'pointer';

    // 클릭 이벤트 리스너 추가
    element.addEventListener('click', (e) => {
      e.preventDefault();
      e.stopPropagation();

      // 이벤트 추적
      if (trackEventCallback) {
        trackEventCallback(advertisement._id, slot.id, AdEventType.CLICK);
      }

      // 링크 이동
      window.open(advertisement.linkUrl!, '_blank');

      // 디버그 로그
      if (debug) {
        const typeLabel = adTypeLabel || String(slot.adType).toLowerCase();
        console.log(`🔗 ${typeLabel} ad clicked: ${advertisement._id} -> ${advertisement.linkUrl}`);
      }
    });
  }

  /**
   * 렌더러에서 사용할 수 있는 간편한 클릭 이벤트 추가 함수
   * BaseAdRenderer를 상속받은 클래스에서 사용
   * @param element - 클릭 이벤트를 추가할 DOM 요소
   * @param advertisement - 광고 데이터
   * @param slot - 광고 슬롯 정보
   * @param createEventTrackingCallback - 이벤트 추적 콜백 생성 함수
   * @param debug - 디버그 모드
   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
   */
  static addClickEventForRenderer(
    element: HTMLElement,
    advertisement: Advertisement,
    slot: AdSlot,
    createEventTrackingCallback: () => (adId: string, slotId: string, eventType: AdEventType) => void,
    debug: boolean = false,
    adTypeLabel?: string
  ): void {
    // linkUrl이 없으면 클릭 이벤트 추가하지 않음
    if (!advertisement.linkUrl) {
      return;
    }

    // 커서 스타일 설정
    element.style.cursor = 'pointer';

    // 클릭 이벤트 리스너 추가
    element.addEventListener('click', (e) => {
      e.preventDefault();
      e.stopPropagation();

      // 이벤트 추적 콜백 생성
      const trackEventCallback = createEventTrackingCallback();
      trackEventCallback(advertisement._id, slot.id, AdEventType.CLICK);

      // 링크 이동
      window.open(advertisement.linkUrl!, '_blank');

      // 디버그 로그
      if (debug) {
        const typeLabel = adTypeLabel || String(slot.adType).toLowerCase();
        console.log(`🔗 ${typeLabel} ad clicked: ${advertisement._id} -> ${advertisement.linkUrl}`);
      }
    });
  }

  /**
   * 슬라이더/매니저에서 사용할 수 있는 클릭 이벤트 추가 함수
   * 이미 trackEventCallback이 준비된 상황에서 사용
   * @param element - 클릭 이벤트를 추가할 DOM 요소
   * @param advertisement - 광고 데이터
   * @param slot - 광고 슬롯 정보
   * @param trackEventCallback - 준비된 이벤트 추적 콜백
   * @param debug - 디버그 모드
   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
   */
  static addClickEventForSlider(
    element: HTMLElement,
    advertisement: Advertisement,
    slot: AdSlot,
    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
    debug: boolean = false,
    adTypeLabel?: string
  ): void {
    this.addClickEvent(element, advertisement, slot, trackEventCallback, debug, adTypeLabel);
  }

  /**
   * 클릭 가능한 광고인지 확인하는 헬퍼 함수
   * @param advertisement - 광고 데이터
   * @returns linkUrl이 있으면 true, 없으면 false
   */
  static isClickable(advertisement: Advertisement): boolean {
    return Boolean(advertisement.linkUrl);
  }

  /**
   * 여러 요소에 대해 일괄적으로 클릭 이벤트를 추가하는 함수
   * @param elements - 클릭 이벤트를 추가할 DOM 요소들
   * @param advertisements - 광고 데이터 배열 (elements와 같은 순서)
   * @param slot - 광고 슬롯 정보
   * @param trackEventCallback - 이벤트 추적 콜백
   * @param debug - 디버그 모드
   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
   */
  static addClickEventsBatch(
    elements: HTMLElement[],
    advertisements: Advertisement[],
    slot: AdSlot,
    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
    debug: boolean = false,
    adTypeLabel?: string
  ): void {
    elements.forEach((element, index) => {
      const advertisement = advertisements[index];
      if (advertisement) {
        this.addClickEvent(element, advertisement, slot, trackEventCallback, debug, adTypeLabel);
      }
    });
  }
}