@adstage/react-native-sdk 1.0.0

package/src/event/AdStageEvent.ts

@@ -0,0 +1,844 @@
+/**
+ * AdStage Event 모듈
+ *
+ * 이벤트 트래킹을 담당합니다.
+ * Android AdStageEvent, iOS AdStageEventProtocol, Unity AdStageEvent와 동일한 표준 이벤트를 제공합니다.
+ *
+ * @since 3.0.0
+ */
+
+import { NativeModules } from 'react-native';
+import type {
+  TrackEventParams,
+  TrackEventResult,
+  SignUpMethod,
+  PaymentMethod,
+  EcommerceItem,
+  AdPlatform,
+  AdFormat,
+  GameServerInfo,
+  PatchInfo,
+  StockTransactionInfo,
+  AccountOpenInfo,
+  CardApplicationInfo,
+} from '../types';
+
+const { AdStageModule } = NativeModules;
+
+/**
+ * AdStage Event 클래스
+ *
+ * @example
+ * ```typescript
+ * // 커스텀 이벤트
+ * await AdStage.event.track('button_click', { buttonId: 'cta_1' });
+ *
+ * // 표준 이벤트
+ * await AdStage.event.trackPurchase({
+ *   value: 29.99,
+ *   currency: 'USD',
+ *   transactionId: 'TX_123'
+ * });
+ * ```
+ */
+export class AdStageEvent {
+  // ============================================
+  // Generic Event Tracking
+  // ============================================
+
+  /**
+   * 커스텀 이벤트 전송
+   *
+   * @param eventName - 이벤트 이름
+   * @param params - 이벤트 파라미터 (자유 형식)
+   * @returns 전송 결과
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.track('button_click', {
+   *   buttonId: 'cta_purchase',
+   *   screenName: 'product_detail'
+   * });
+   * ```
+   */
+  static async track(
+    eventName: string,
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    if (!AdStageModule) {
+      throw new Error('AdStage: Native module is not available');
+    }
+
+    try {
+      const result = await AdStageModule.trackEvent(eventName, params);
+      return {
+        success: true,
+        eventId: result.eventId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error:
+          error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  // ============================================
+  // 📌 광고 추적 이벤트
+  // ============================================
+
+  /**
+   * 클릭 이벤트
+   */
+  static async trackClick(params: TrackEventParams = {}): Promise<TrackEventResult> {
+    return this.track('click', params);
+  }
+
+  /**
+   * 뷰/노출 이벤트
+   */
+  static async trackView(params: TrackEventParams = {}): Promise<TrackEventResult> {
+    return this.track('view', params);
+  }
+
+  /**
+   * 설치 이벤트 (일반적으로 SDK가 자동 전송)
+   */
+  static async trackInstall(params: TrackEventParams = {}): Promise<TrackEventResult> {
+    return this.track('install', params);
+  }
+
+  // ============================================
+  // 👤 사용자 라이프사이클
+  // ============================================
+
+  /**
+   * 회원가입 완료 이벤트
+   *
+   * @param method - 가입 방법
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackSignUp('google');
+   * ```
+   */
+  static async trackSignUp(
+    method?: SignUpMethod
+  ): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (method) params.method = method;
+    return this.track('sign_up', params);
+  }
+
+  /**
+   * 회원가입 시작 이벤트
+   */
+  static async trackSignUpStart(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('sign_up_start', params);
+  }
+
+  /**
+   * 로그인 이벤트
+   *
+   * @param method - 로그인 방법
+   */
+  static async trackLogin(method?: SignUpMethod): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (method) params.method = method;
+    return this.track('login', params);
+  }
+
+  /**
+   * 로그아웃 이벤트
+   */
+  static async trackLogout(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('logout', params);
+  }
+
+  // ============================================
+  // 📄 콘텐츠 조회
+  // ============================================
+
+  /**
+   * 홈 화면 조회 이벤트
+   */
+  static async trackHomeView(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('home_view', params);
+  }
+
+  /**
+   * 상품 목록 조회 이벤트
+   *
+   * @param itemCategory - 상품 카테고리
+   */
+  static async trackProductListView(
+    itemCategory?: string
+  ): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (itemCategory) params.item_category = itemCategory;
+    return this.track('product_list_view', params);
+  }
+
+  /**
+   * 검색 결과 조회 이벤트
+   *
+   * @param searchTerm - 검색어
+   */
+  static async trackSearchResultView(
+    searchTerm?: string
+  ): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (searchTerm) params.search_term = searchTerm;
+    return this.track('search_result_view', params);
+  }
+
+  /**
+   * 상품 상세 조회 이벤트
+   */
+  static async trackProductDetailsView(options?: {
+    itemId?: string;
+    itemName?: string;
+  }): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (options?.itemId) params.item_id = options.itemId;
+    if (options?.itemName) params.item_name = options.itemName;
+    return this.track('product_details_view', params);
+  }
+
+  /**
+   * 화면 조회 이벤트
+   */
+  static async trackScreenView(options?: {
+    screenName?: string;
+    screenClass?: string;
+  }): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (options?.screenName) params.screen_name = options.screenName;
+    if (options?.screenClass) params.screen_class = options.screenClass;
+    return this.track('screen_view', params);
+  }
+
+  // ============================================
+  // 🛒 전자상거래
+  // ============================================
+
+  /**
+   * 장바구니 추가 이벤트
+   */
+  static async trackAddToCart(options: {
+    items: EcommerceItem[];
+    value?: number;
+    currency?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('add_to_cart', {
+      items: options.items,
+      value: options.value,
+      currency: options.currency,
+    });
+  }
+
+  /**
+   * 장바구니 제거 이벤트
+   */
+  static async trackRemoveFromCart(options: {
+    items: EcommerceItem[];
+    value?: number;
+    currency?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('remove_from_cart', {
+      items: options.items,
+      value: options.value,
+      currency: options.currency,
+    });
+  }
+
+  /**
+   * 결제 시작 이벤트
+   */
+  static async trackBeginCheckout(options?: {
+    items?: EcommerceItem[];
+    value?: number;
+    currency?: string;
+    coupon?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('begin_checkout', options ?? {});
+  }
+
+  /**
+   * 결제 정보 추가 이벤트
+   */
+  static async trackAddPaymentInfo(options?: {
+    paymentMethod?: PaymentMethod;
+  }): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (options?.paymentMethod) params.payment_method = options.paymentMethod;
+    return this.track('add_payment_info', params);
+  }
+
+  /**
+   * 구매 완료 이벤트
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackPurchase({
+   *   value: 99000,
+   *   currency: 'KRW',
+   *   transactionId: 'TX_123456',
+   *   items: [
+   *     { itemId: 'SKU_001', itemName: '상품명', price: 99000, quantity: 1 }
+   *   ]
+   * });
+   * ```
+   */
+  static async trackPurchase(options: {
+    value: number;
+    currency: string;
+    transactionId?: string;
+    items?: EcommerceItem[];
+    paymentMethod?: PaymentMethod;
+    coupon?: string;
+    shipping?: number;
+    tax?: number;
+  }): Promise<TrackEventResult> {
+    return this.track('purchase', {
+      value: options.value,
+      currency: options.currency,
+      transaction_id: options.transactionId,
+      items: options.items,
+      payment_method: options.paymentMethod,
+      coupon: options.coupon,
+      shipping: options.shipping,
+      tax: options.tax,
+    });
+  }
+
+  /**
+   * 환불 이벤트
+   */
+  static async trackRefund(options: {
+    transactionId: string;
+    value?: number;
+    currency?: string;
+    items?: EcommerceItem[];
+  }): Promise<TrackEventResult> {
+    return this.track('refund', {
+      transaction_id: options.transactionId,
+      value: options.value,
+      currency: options.currency,
+      items: options.items,
+    });
+  }
+
+  // ============================================
+  // 🎮 게임 이벤트
+  // ============================================
+
+  /**
+   * 레벨업 이벤트
+   */
+  static async trackLevelUp(options: {
+    level: number;
+    character?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('level_up', {
+      level: options.level,
+      character: options.character,
+    });
+  }
+
+  /**
+   * 튜토리얼 시작 이벤트
+   */
+  static async trackTutorialBegin(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('tutorial_begin', params);
+  }
+
+  /**
+   * 튜토리얼 완료 이벤트
+   */
+  static async trackTutorialComplete(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('tutorial_complete', params);
+  }
+
+  /**
+   * 업적 달성 이벤트
+   */
+  static async trackUnlockAchievement(options: {
+    achievementId: string;
+    achievementName?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('unlock_achievement', {
+      achievement_id: options.achievementId,
+      achievement_name: options.achievementName,
+    });
+  }
+
+  /**
+   * 스테이지 클리어 이벤트
+   */
+  static async trackStageClear(options: {
+    stageName: string;
+    stageNumber?: number;
+    score?: number;
+    duration?: number;
+  }): Promise<TrackEventResult> {
+    return this.track('stage_clear', {
+      stage_name: options.stageName,
+      stage_number: options.stageNumber,
+      score: options.score,
+      duration: options.duration,
+    });
+  }
+
+  // ============================================
+  // 💎 가상화폐
+  // ============================================
+
+  /**
+   * 가상화폐 획득 이벤트
+   */
+  static async trackEarnVirtualCurrency(options: {
+    virtualCurrencyName: string;
+    value: number;
+  }): Promise<TrackEventResult> {
+    return this.track('earn_virtual_currency', {
+      virtual_currency_name: options.virtualCurrencyName,
+      value: options.value,
+    });
+  }
+
+  /**
+   * 가상화폐 사용 이벤트
+   */
+  static async trackSpendVirtualCurrency(options: {
+    virtualCurrencyName: string;
+    value: number;
+    itemName?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('spend_virtual_currency', {
+      virtual_currency_name: options.virtualCurrencyName,
+      value: options.value,
+      item_name: options.itemName,
+    });
+  }
+
+  // ============================================
+  // 🔔 기타 이벤트
+  // ============================================
+
+  /**
+   * 공유 이벤트
+   */
+  static async trackShare(options: {
+    method: string;
+    contentType?: string;
+    itemId?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('share', {
+      method: options.method,
+      content_type: options.contentType,
+      item_id: options.itemId,
+    });
+  }
+
+  /**
+   * 앱 평가 이벤트
+   */
+  static async trackRate(options: {
+    rating: number;
+    maxRating?: number;
+  }): Promise<TrackEventResult> {
+    return this.track('rate', {
+      rating: options.rating,
+      max_rating: options.maxRating ?? 5,
+    });
+  }
+
+  /**
+   * 구독 시작 이벤트
+   */
+  static async trackSubscribe(options: {
+    subscriptionId: string;
+    value?: number;
+    currency?: string;
+    period?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('subscribe', {
+      subscription_id: options.subscriptionId,
+      value: options.value,
+      currency: options.currency,
+      period: options.period,
+    });
+  }
+
+  /**
+   * 푸시 알림 클릭 이벤트
+   */
+  static async trackNotificationClick(options?: {
+    notificationId?: string;
+    title?: string;
+    body?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('notification_click', {
+      notification_id: options?.notificationId,
+      title: options?.title,
+      body: options?.body,
+    });
+  }
+
+  // ============================================
+  // 🆕 Unity 호환 추가 이벤트
+  // ============================================
+
+  /**
+   * 앱 최초 실행 이벤트 (Unity: FirstOpenEvent)
+   */
+  static async trackFirstOpen(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('first_open', params);
+  }
+
+  /**
+   * 페이지 조회 이벤트 (Unity: PageViewEvent) - 웹뷰용
+   */
+  static async trackPageView(options?: {
+    pageUrl?: string;
+    pageTitle?: string;
+    pagePath?: string;
+    referrer?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('page_view', {
+      page_url: options?.pageUrl,
+      page_title: options?.pageTitle,
+      page_path: options?.pagePath,
+      referrer: options?.referrer,
+    });
+  }
+
+  /**
+   * 위시리스트 추가 이벤트 (Unity: AddToWishlistEvent)
+   */
+  static async trackAddToWishlist(options?: {
+    itemId?: string;
+    itemName?: string;
+    value?: number;
+    currency?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('add_to_wishlist', {
+      item_id: options?.itemId,
+      item_name: options?.itemName,
+      value: options?.value,
+      currency: options?.currency,
+    });
+  }
+
+  /**
+   * 체험판 시작 이벤트 (Unity: StartTrialEvent)
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackStartTrial({
+   *   value: 9900.0,
+   *   currency: 'KRW',
+   *   trialDays: 14
+   * });
+   * ```
+   */
+  static async trackStartTrial(options?: {
+    value?: number;
+    currency?: string;
+    trialDays?: number;
+  }): Promise<TrackEventResult> {
+    return this.track('start_trial', {
+      value: options?.value,
+      currency: options?.currency,
+      trial_days: options?.trialDays,
+    });
+  }
+
+  /**
+   * 구독 해지 이벤트 (Unity: UnsubscribeEvent)
+   */
+  static async trackUnsubscribe(subscriptionId: string): Promise<TrackEventResult> {
+    return this.track('unsubscribe', {
+      subscription_id: subscriptionId,
+    });
+  }
+
+  // ============================================
+  // 📢 인앱 광고 이벤트
+  // ============================================
+
+  /**
+   * 인앱 광고 노출 이벤트 (Unity: AdImpressionEvent)
+   */
+  static async trackAdImpression(options?: {
+    adPlatform?: AdPlatform | string;
+    adSource?: string;
+    adFormat?: AdFormat | string;
+    adUnitName?: string;
+    value?: number;
+    currency?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('ad_impression', {
+      ad_platform: options?.adPlatform,
+      ad_source: options?.adSource,
+      ad_format: options?.adFormat,
+      ad_unit_name: options?.adUnitName,
+      value: options?.value,
+      currency: options?.currency,
+    });
+  }
+
+  /**
+   * 인앱 광고 클릭 이벤트 (Unity: AdClickEvent)
+   */
+  static async trackAdClick(options?: {
+    adPlatform?: AdPlatform | string;
+    adSource?: string;
+    adFormat?: AdFormat | string;
+    adUnitName?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('ad_click', {
+      ad_platform: options?.adPlatform,
+      ad_source: options?.adSource,
+      ad_format: options?.adFormat,
+      ad_unit_name: options?.adUnitName,
+    });
+  }
+
+  // ============================================
+  // 🎮 게임 특화 이벤트
+  // ============================================
+
+  /**
+   * 게임 플레이 이벤트 (Unity: GamePlayEvent)
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackGamePlay({
+   *   level: 10,
+   *   levelName: "Dragon's Lair",
+   *   character: 'mage',
+   *   contentType: 'dungeon'
+   * });
+   * ```
+   */
+  static async trackGamePlay(options?: {
+    level?: number;
+    levelName?: string;
+    character?: string;
+    contentType?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('game_play', {
+      level: options?.level,
+      level_name: options?.levelName,
+      character: options?.character,
+      content_type: options?.contentType,
+    });
+  }
+
+  /**
+   * 보너스 획득 이벤트 (Unity: AcquireBonusEvent)
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackAcquireBonus({
+   *   contentType: 'reward',
+   *   itemId: 'ITEM_123',
+   *   itemName: 'Gold Chest',
+   *   quantity: 1
+   * });
+   * ```
+   */
+  static async trackAcquireBonus(options?: {
+    contentType?: string;
+    itemId?: string;
+    itemName?: string;
+    quantity?: number;
+  }): Promise<TrackEventResult> {
+    return this.track('acquire_bonus', {
+      content_type: options?.contentType,
+      item_id: options?.itemId,
+      item_name: options?.itemName,
+      quantity: options?.quantity,
+    });
+  }
+
+  /**
+   * 게임 서버 선택 이벤트 (Unity: SelectGameServerEvent)
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackSelectGameServer({
+   *   contentId: 'SERVER_01',
+   *   contentType: 'pvp',
+   *   itemName: 'Asia Server'
+   * });
+   * ```
+   */
+  static async trackSelectGameServer(
+    serverInfo: GameServerInfo
+  ): Promise<TrackEventResult> {
+    return this.track('select_game_server', {
+      content_id: serverInfo.contentId,
+      content_type: serverInfo.contentType,
+      item_name: serverInfo.itemName,
+    });
+  }
+
+  /**
+   * 패치 완료 이벤트 (Unity: CompletePatchEvent)
+   *
+   * @example
+   * ```typescript
+   * await AdStage.event.trackCompletePatch({
+   *   contentId: 'PATCH_2.1.0',
+   *   contentType: 'update'
+   * });
+   * ```
+   */
+  static async trackCompletePatch(patchInfo: PatchInfo): Promise<TrackEventResult> {
+    return this.track('complete_patch', {
+      content_id: patchInfo.contentId,
+      content_type: patchInfo.contentType,
+    });
+  }
+
+  // ============================================
+  // 💬 상호작용 이벤트
+  // ============================================
+
+  /**
+   * 검색 이벤트 (Unity: SearchEvent)
+   */
+  static async trackSearch(searchTerm?: string): Promise<TrackEventResult> {
+    const params: TrackEventParams = {};
+    if (searchTerm) params.search_term = searchTerm;
+    return this.track('search', params);
+  }
+
+  /**
+   * 콘텐츠 선택 이벤트 (Unity: SelectContentEvent)
+   */
+  static async trackSelectContent(options?: {
+    contentType?: string;
+    contentId?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('select_content', {
+      content_type: options?.contentType,
+      content_id: options?.contentId,
+    });
+  }
+
+  /**
+   * 좋아요 이벤트 (Unity: LikeEvent)
+   */
+  static async trackLike(options?: {
+    contentType?: string;
+    contentId?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('like', {
+      content_type: options?.contentType,
+      content_id: options?.contentId,
+    });
+  }
+
+  /**
+   * 일정 등록 이벤트 (Unity: ScheduleEvent)
+   */
+  static async trackSchedule(
+    params: TrackEventParams = {}
+  ): Promise<TrackEventResult> {
+    return this.track('schedule', params);
+  }
+
+  /**
+   * 크레딧 사용 이벤트 (Unity: SpendCreditsEvent)
+   */
+  static async trackSpendCredits(options?: {
+    value?: number;
+    contentType?: string;
+    contentId?: string;
+  }): Promise<TrackEventResult> {
+    return this.track('spend_credits', {
+      value: options?.value,
+      content_type: options?.contentType,
+      content_id: options?.contentId,
+    });
+  }
+
+  // ============================================
+  // 💼 금융 특화 이벤트
+  // ============================================
+
+  /**
+   * 주식 매도 이벤트 (Unity: SellStockEvent)
+   */
+  static async trackSellStock(
+    transaction: StockTransactionInfo
+  ): Promise<TrackEventResult> {
+    return this.track('sell_stock', {
+      item_id: transaction.itemId,
+      item_name: transaction.itemName,
+      quantity: transaction.quantity,
+      price: transaction.price,
+      value: transaction.value,
+      currency: transaction.currency,
+    });
+  }
+
+  /**
+   * 주식 매수 이벤트 (Unity: BuyStockEvent)
+   */
+  static async trackBuyStock(
+    transaction: StockTransactionInfo
+  ): Promise<TrackEventResult> {
+    return this.track('buy_stock', {
+      item_id: transaction.itemId,
+      item_name: transaction.itemName,
+      quantity: transaction.quantity,
+      price: transaction.price,
+      value: transaction.value,
+      currency: transaction.currency,
+    });
+  }
+
+  /**
+   * 계좌 개설 완료 이벤트 (Unity: CompleteOpenAccountEvent)
+   */
+  static async trackCompleteOpenAccount(
+    accountInfo: AccountOpenInfo
+  ): Promise<TrackEventResult> {
+    return this.track('complete_open_account', {
+      content_type: accountInfo.contentType,
+      content_id: accountInfo.contentId,
+      method: accountInfo.method,
+    });
+  }
+
+  /**
+   * 카드 신청 이벤트 (Unity: ApplyCardEvent)
+   */
+  static async trackApplyCard(
+    cardInfo: CardApplicationInfo
+  ): Promise<TrackEventResult> {
+    return this.track('apply_card', {
+      content_type: cardInfo.contentType,
+      item_name: cardInfo.itemName,
+      item_id: cardInfo.itemId,
+    });
+  }
+}