@adstage/react-native-sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * AdStage React Native SDK
+ *
+ * 광고 어트리뷰션, 딥링크, 프로모션을 위한 통합 SDK
+ *
+ * @since 3.0.0
+ */
+
+export { AdStage } from './AdStage';
+export { AdStageDeepLink } from './deeplink/AdStageDeepLink';
+export { AdStagePromotion } from './promotion/AdStagePromotion';
+export { AdStageEvent } from './event/AdStageEvent';
+
+// Types
+export type {
+  // Core
+  AdStageConfig,
+  // DeepLink
+  DeepLinkData,
+  DeepLinkSource,
+  DeepLinkListener,
+  CreateDeepLinkRequest,
+  CreateDeepLinkResponse,
+  RedirectConfig,
+  PlatformConfig,
+  // Promotion
+  PromotionListParams,
+  PromotionListResponse,
+  Promotion,
+  PromotionDeepLink,
+  PromotionClickResult,
+  // Event
+  TrackEventParams,
+  TrackEventResult,
+  UserAttributes,
+  // Event - Standard Types
+  SignUpMethod,
+  PaymentMethod,
+  EcommerceItem,
+  // Event - Unity Parity Types
+  AdPlatform,
+  AdFormat,
+  GameServerInfo,
+  PatchInfo,
+  StockTransactionInfo,
+  AccountOpenInfo,
+  CardApplicationInfo,
+} from './types';

package/src/promotion/AdStagePromotion.ts

@@ -0,0 +1,162 @@
+/**
+ * AdStage Promotion 모듈
+ *
+ * 프로모션 조회, 표시, 클릭 처리를 담당합니다.
+ * Android/iOS PromotionHandler, PromotionManager와 동일한 API를 제공합니다.
+ *
+ * @since 3.0.0
+ */
+
+import { NativeModules } from 'react-native';
+import type {
+  PromotionListParams,
+  PromotionListResponse,
+  Promotion,
+  PromotionClickResult,
+} from '../types';
+
+const { AdStageModule } = NativeModules;
+
+/**
+ * AdStage Promotion 클래스
+ *
+ * @example
+ * ```typescript
+ * // 프로모션 목록 조회
+ * const response = await AdStage.promotion.getList({
+ *   bannerType: 'NATIVE',
+ *   region: 'KR',
+ *   limit: 10
+ * });
+ *
+ * // 프로모션 클릭 처리
+ * const result = await AdStage.promotion.handleClick(response.promotions[0]);
+ * ```
+ */
+export class AdStagePromotion {
+  // ============================================
+  // Promotion List
+  // ============================================
+
+  /**
+   * 프로모션 목록 조회
+   *
+   * @param params - 조회 파라미터
+   * @returns 프로모션 목록 응답
+   *
+   * @example
+   * ```typescript
+   * const response = await AdStage.promotion.getList({
+   *   bannerType: 'NATIVE',          // NATIVE, INTERSTITIAL, REWARDED_VIDEO, POPUP
+   *   region: 'KR',                   // KR, JP, US, SEA, EU, GLOBAL
+   *   deviceType: 'HIGH_END',         // LOW_END, MID_END, HIGH_END
+   *   limit: 10,
+   *   status: 'ACTIVE',
+   *   partner: 'game_company',
+   *   primaryInterest: 'GAMES',
+   *   primaryAgeGroup: '18-24',
+   *   gameGenrePreference: 'RPG',
+   *   playerSpendingTier: 'DOLPHIN',  // F2P, DOLPHIN, WHALE
+   *   playTimePattern: 'EVENING'
+   * });
+   *
+   * console.log('Total:', response.totalItems);
+   * response.promotions.forEach(promo => {
+   *   console.log(`${promo.appName}: ${promo.bannerUrl}`);
+   * });
+   * ```
+   */
+  static async getList(
+    params: PromotionListParams = {}
+  ): Promise<PromotionListResponse> {
+    if (!AdStageModule) {
+      throw new Error('AdStage: Native module is not available');
+    }
+
+    const result = await AdStageModule.getPromotionList(params);
+
+    return {
+      totalItems: result.totalItems ?? 0,
+      promotions: result.promotions ?? [],
+    };
+  }
+
+  // ============================================
+  // Promotion Click Handling
+  // ============================================
+
+  /**
+   * 프로모션 클릭 처리
+   *
+   * 클릭 이벤트를 서버에 전송하고 스토어를 엽니다.
+   *
+   * @param promotion - 클릭할 프로모션
+   * @returns 클릭 처리 결과
+   *
+   * @example
+   * ```typescript
+   * const result = await AdStage.promotion.handleClick(promotion);
+   *
+   * if (result.success) {
+   *   console.log('스토어로 이동:', result.storeUrl);
+   * } else {
+   *   console.error('클릭 처리 실패:', result.error);
+   * }
+   * ```
+   */
+  static async handleClick(promotion: Promotion): Promise<PromotionClickResult> {
+    if (!AdStageModule) {
+      throw new Error('AdStage: Native module is not available');
+    }
+
+    try {
+      const result = await AdStageModule.handlePromotionClick(promotion);
+      return {
+        success: true,
+        storeUrl: result.storeUrl,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error:
+          error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * 프로모션 노출 이벤트 전송
+   *
+   * 프로모션이 화면에 표시될 때 호출합니다.
+   *
+   * @param promotion - 노출된 프로모션
+   *
+   * @example
+   * ```typescript
+   * // 프로모션 배너가 화면에 보일 때
+   * AdStage.promotion.trackImpression(promotion);
+   * ```
+   */
+  static async trackImpression(promotion: Promotion): Promise<void> {
+    if (!AdStageModule) {
+      return;
+    }
+    await AdStageModule.trackPromotionImpression?.(promotion);
+  }
+
+  // ============================================
+  // Utility
+  // ============================================
+
+  /**
+   * 플랫폼에 맞는 스토어 URL 추출
+   *
+   * @param promotion - 프로모션
+   * @returns 스토어 URL 또는 null
+   */
+  static getStoreUrl(promotion: Promotion): string | null {
+    const platform =
+      require('react-native').Platform.OS === 'ios' ? 'ios' : 'android';
+    return promotion.storeUrls?.[platform] ?? null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,392 @@
+/**
+ * AdStage SDK 타입 정의
+ *
+ * Android/iOS 네이티브 SDK와 동일한 타입 구조를 제공합니다.
+ *
+ * @since 3.0.0
+ */
+
+// ============================================
+// Core Types
+// ============================================
+
+/**
+ * AdStage SDK 초기화 설정
+ */
+export interface AdStageConfig {
+  /** API 인증 키 (필수) */
+  apiKey: string;
+  /** 서버 URL (선택, 기본값: https://api.adstage.app) */
+  serverUrl?: string;
+}
+
+// ============================================
+// DeepLink Types
+// ============================================
+
+/**
+ * 딥링크 소스 타입
+ */
+export type DeepLinkSource = 'realtime' | 'install' | 'unknown';
+
+/**
+ * 딥링크 데이터
+ */
+export interface DeepLinkData {
+  /** 딥링크 ID (서버 발급) */
+  linkId: string;
+  /** Short Path (예: "SDGWNBB") */
+  shortPath: string;
+  /** 딥링크 파라미터 */
+  parameters: Record<string, string>;
+  /** 딥링크 소스 */
+  source: DeepLinkSource;
+  /** 이벤트 타입 (OPEN, INSTALL) */
+  eventType: string;
+  /** 타임스탬프 (Unity 호환) */
+  timestamp?: string;
+}
+
+/**
+ * 딥링크 리스너
+ */
+export type DeepLinkListener = (data: DeepLinkData) => void;
+
+/**
+ * 플랫폼별 리다이렉트 설정
+ */
+export interface PlatformConfig {
+  /** 앱 스토어 URL */
+  storeUrl?: string;
+  /** 앱 커스텀 스킴 */
+  appScheme?: string;
+  /** 웹 폴백 URL */
+  webUrl?: string;
+  /** 패키지명 (Android) / 번들 ID (iOS) */
+  packageName?: string;
+  /** App Store ID (iOS) */
+  appStoreId?: string;
+}
+
+/**
+ * 리다이렉트 설정
+ */
+export interface RedirectConfig {
+  /** 리다이렉트 타입: STORE, APP, WEB */
+  type: 'STORE' | 'APP' | 'WEB';
+  /** Android 플랫폼 설정 */
+  android?: PlatformConfig;
+  /** iOS 플랫폼 설정 */
+  ios?: PlatformConfig;
+  /** 데스크톱 설정 */
+  desktop?: { webUrl?: string };
+}
+
+/**
+ * 딥링크 생성 요청
+ */
+export interface CreateDeepLinkRequest {
+  /** 딥링크 이름 (필수) */
+  name: string;
+  /** 딥링크 설명 */
+  description?: string;
+  /** Short Path 커스텀 */
+  shortPath?: string;
+  /** 채널 */
+  channel?: string;
+  /** 서브 채널 */
+  subChannel?: string;
+  /** 캠페인 */
+  campaign?: string;
+  /** 광고 그룹 */
+  adGroup?: string;
+  /** 광고 크리에이티브 */
+  creative?: string;
+  /** 콘텐츠 (Unity 호환) */
+  content?: string;
+  /** 키워드 */
+  keyword?: string;
+  /** 리다이렉트 설정 */
+  redirectConfig?: RedirectConfig;
+  /** 커스텀 파라미터 */
+  parameters?: Record<string, string>;
+}
+
+/**
+ * 딥링크 생성 응답
+ */
+export interface CreateDeepLinkResponse {
+  /** 생성된 Short URL */
+  shortUrl: string;
+  /** Short Path */
+  shortPath: string;
+  /** 딥링크 ID */
+  linkId: string;
+}
+
+// ============================================
+// Promotion Types
+// ============================================
+
+/**
+ * 프로모션 조회 파라미터
+ */
+export interface PromotionListParams {
+  /** 배너 타입: NATIVE, INTERSTITIAL, REWARDED_VIDEO, POPUP */
+  bannerType?: string;
+  /** 타겟 사용자 필터 */
+  targetAudience?: string;
+  /** 디바이스 타입: LOW_END, MID_END, HIGH_END */
+  deviceType?: string;
+  /** 지역: KR, JP, US, SEA, EU, GLOBAL */
+  region?: string;
+  /** 조회 개수 제한 */
+  limit?: number;
+  /** 상태: ACTIVE, PENDING, PAUSED, ENDED */
+  status?: string;
+  /** 파트너(광고주) 필터 */
+  partner?: string;
+  /** 주요 관심사 */
+  primaryInterest?: string;
+  /** 주요 연령대: 13-17, 18-24, 25-34, 35-44, 45+ */
+  primaryAgeGroup?: string;
+  /** 게임 장르 선호도 */
+  gameGenrePreference?: string;
+  /** 플레이어 지출 티어: F2P, DOLPHIN, WHALE */
+  playerSpendingTier?: string;
+  /** 플레이 시간 패턴 */
+  playTimePattern?: string;
+}
+
+/**
+ * 프로모션 딥링크 정보
+ */
+export interface PromotionDeepLink {
+  id: string;
+  name: string;
+  description: string;
+  shortPath: string;
+  linkType: string;
+  channel: string;
+  subChannel: string;
+  campaign: string;
+  content: string;
+  keyword: string;
+  status: string;
+}
+
+/**
+ * 프로모션 데이터
+ */
+export interface Promotion {
+  /** 프로모션 ID */
+  id: string;
+  /** 파트너(광고주) 이름 */
+  partner: string;
+  /** 앱 이름 */
+  appName: string;
+  /** 배너 이미지 URL */
+  bannerUrl: string;
+  /** 배너 타입 */
+  bannerType: string;
+  /** 앱 설명 */
+  appDescription: string;
+  /** 딥링크 정보 */
+  deeplink: PromotionDeepLink;
+  /** 스토어 URL */
+  storeUrls?: {
+    android?: string;
+    ios?: string;
+  };
+}
+
+/**
+ * 프로모션 리스트 응답
+ */
+export interface PromotionListResponse {
+  /** 전체 개수 */
+  totalItems: number;
+  /** 프로모션 목록 */
+  promotions: Promotion[];
+}
+
+/**
+ * 프로모션 클릭 결과
+ */
+export interface PromotionClickResult {
+  /** 성공 여부 */
+  success: boolean;
+  /** 이동한 스토어 URL */
+  storeUrl?: string;
+  /** 에러 메시지 */
+  error?: string;
+}
+
+// ============================================
+// Event Tracking Types
+// ============================================
+
+/**
+ * 사용자 속성
+ */
+export interface UserAttributes {
+  /** 성별: male, female, other */
+  gender?: string;
+  /** 국가 코드: KR, US, JP 등 */
+  country?: string;
+  /** 도시 */
+  city?: string;
+  /** 나이 */
+  age?: string;
+  /** 언어: ko-KR, en-US 등 */
+  language?: string;
+}
+
+/**
+ * 이벤트 파라미터 (자유 형식)
+ */
+export type TrackEventParams = Record<string, unknown>;
+
+/**
+ * 이벤트 전송 결과
+ */
+export interface TrackEventResult {
+  /** 성공 여부 */
+  success: boolean;
+  /** 이벤트 ID */
+  eventId?: string;
+  /** 에러 메시지 */
+  error?: string;
+}
+
+// ============================================
+// Standard Event Types
+// ============================================
+
+/**
+ * 회원가입 방법
+ */
+export type SignUpMethod =
+  | 'email'
+  | 'google'
+  | 'apple'
+  | 'facebook'
+  | 'kakao'
+  | 'naver'
+  | 'twitter'
+  | 'line'
+  | 'guest';
+
+/**
+ * 결제 방법
+ */
+export type PaymentMethod =
+  | 'credit_card'
+  | 'debit_card'
+  | 'paypal'
+  | 'google_pay'
+  | 'apple_pay'
+  | 'samsung_pay'
+  | 'kakao_pay'
+  | 'naver_pay'
+  | 'toss'
+  | 'bank_transfer'
+  | 'virtual_account'
+  | 'carrier_billing'
+  | 'gift_card'
+  | 'cryptocurrency'
+  | 'other';
+
+/**
+ * 이커머스 아이템
+ */
+export interface EcommerceItem {
+  itemId: string;
+  itemName: string;
+  price?: number;
+  quantity?: number;
+  itemCategory?: string;
+  itemBrand?: string;
+}
+
+// ============================================
+// Additional Event Types (Unity Parity)
+// ============================================
+
+/**
+ * 광고 플랫폼 타입
+ */
+export type AdPlatform =
+  | 'admob'
+  | 'applovin'
+  | 'ironsource'
+  | 'unity_ads'
+  | 'facebook'
+  | 'vungle'
+  | 'chartboost'
+  | 'mopub'
+  | 'other';
+
+/**
+ * 광고 포맷 타입
+ */
+export type AdFormat =
+  | 'banner'
+  | 'interstitial'
+  | 'rewarded'
+  | 'rewarded_interstitial'
+  | 'native'
+  | 'app_open'
+  | 'other';
+
+/**
+ * 게임 서버 정보 (Unity 문서 기준)
+ */
+export interface GameServerInfo {
+  /** 서버 ID (Unity: contentId) */
+  contentId?: string;
+  /** 서버 타입 (Unity: contentType) - 예: 'pvp', 'pve' */
+  contentType?: string;
+  /** 서버 이름 (Unity: itemName) */
+  itemName?: string;
+}
+
+/**
+ * 패치 정보 (Unity 문서 기준)
+ */
+export interface PatchInfo {
+  /** 패치 ID (Unity: contentId) - 예: 'PATCH_2.1.0' */
+  contentId?: string;
+  /** 패치 타입 (Unity: contentType) - 예: 'update', 'hotfix' */
+  contentType?: string;
+}
+
+/**
+ * 금융 거래 정보
+ */
+export interface StockTransactionInfo {
+  itemId?: string;
+  itemName?: string;
+  quantity?: number;
+  price?: number;
+  value?: number;
+  currency?: string;
+}
+
+/**
+ * 계좌 개설 정보
+ */
+export interface AccountOpenInfo {
+  contentType?: string;
+  contentId?: string;
+  method?: string;
+}
+
+/**
+ * 카드 신청 정보
+ */
+export interface CardApplicationInfo {
+  contentType?: string;
+  itemName?: string;
+  itemId?: string;
+}