@adstage/react-native-sdk 1.0.0

package/src/deeplink/AdStageDeepLink.ts

@@ -0,0 +1,246 @@
+/**
+ * AdStage DeepLink 모듈
+ *
+ * 딥링크 생성, 수신, 처리를 담당합니다.
+ * Android DeeplinkHandler, iOS DeepLinkManager와 동일한 API를 제공합니다.
+ *
+ * @since 3.0.0
+ */
+
+import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
+import type {
+  DeepLinkData,
+  DeepLinkListener,
+  CreateDeepLinkRequest,
+  CreateDeepLinkResponse,
+} from '../types';
+
+const { AdStageModule } = NativeModules;
+const eventEmitter = AdStageModule
+  ? new NativeEventEmitter(AdStageModule)
+  : null;
+
+/**
+ * AdStage DeepLink 클래스
+ *
+ * @example
+ * ```typescript
+ * // 딥링크 리스너 설정
+ * const unsubscribe = AdStage.deepLink.setListener((data) => {
+ *   console.log('딥링크 수신:', data.shortPath);
+ *   console.log('파라미터:', data.parameters);
+ * });
+ *
+ * // 딥링크 생성
+ * const result = await AdStage.deepLink.create({
+ *   name: '여름 프로모션',
+ *   channel: 'google-ads',
+ *   campaign: 'summer_2024'
+ * });
+ * console.log('Short URL:', result.shortUrl);
+ *
+ * // 리스너 해제
+ * unsubscribe();
+ * ```
+ */
+export class AdStageDeepLink {
+  private static subscription: ReturnType<
+    NativeEventEmitter['addListener']
+  > | null = null;
+
+  // ============================================
+  // Listener Management
+  // ============================================
+
+  /**
+   * 딥링크 리스너 설정
+   *
+   * 딥링크가 수신되면 콜백이 호출됩니다.
+   * 반환된 함수를 호출하면 리스너가 해제됩니다.
+   *
+   * @param listener - 딥링크 수신 콜백
+   * @returns 리스너 해제 함수
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = AdStage.deepLink.setListener((data) => {
+   *   // URL Scheme: myapp://adstage.net/ABCDEF
+   *   // Universal Link: https://adstage.net/ABCDEF
+   *   console.log('Short Path:', data.shortPath);      // "ABCDEF"
+   *   console.log('Link ID:', data.linkId);
+   *   console.log('Parameters:', data.parameters);
+   *   console.log('Source:', data.source);             // "realtime" | "install"
+   *   console.log('Event Type:', data.eventType);     // "OPEN" | "INSTALL"
+   * });
+   *
+   * // 컴포넌트 unmount 시
+   * unsubscribe();
+   * ```
+   */
+  static setListener(listener: DeepLinkListener): () => void {
+    if (!eventEmitter) {
+      console.warn('AdStage: Native event emitter is not available');
+      return () => {};
+    }
+
+    // 기존 리스너 제거
+    this.removeListener();
+
+    this.subscription = eventEmitter.addListener(
+      'onDeepLinkReceived',
+      (event: DeepLinkData) => {
+        listener(event);
+      }
+    );
+
+    // 네이티브에 리스너 설정 알림
+    AdStageModule?.setDeepLinkListener?.();
+
+    return () => this.removeListener();
+  }
+
+  /**
+   * 딥링크 리스너 제거
+   */
+  static removeListener(): void {
+    if (this.subscription) {
+      this.subscription.remove();
+      this.subscription = null;
+    }
+    AdStageModule?.removeDeepLinkListener?.();
+  }
+
+  // ============================================
+  // DeepLink Creation
+  // ============================================
+
+  /**
+   * 딥링크 생성
+   *
+   * @param request - 딥링크 생성 요청
+   * @returns 생성된 딥링크 정보
+   *
+   * @example
+   * ```typescript
+   * const result = await AdStage.deepLink.create({
+   *   name: '여름 프로모션 링크',
+   *   description: '2024년 여름 시즌용',
+   *   channel: 'google-ads',
+   *   campaign: 'summer_promotion_2024',
+   *   redirectConfig: {
+   *     type: 'STORE',
+   *     android: {
+   *       packageName: 'com.example.app',
+   *       appScheme: 'myapp://promo'
+   *     },
+   *     ios: {
+   *       appStoreId: '123456789',
+   *       appScheme: 'myapp://promo'
+   *     }
+   *   },
+   *   parameters: {
+   *     productId: 'SUMMER_2024',
+   *     discount: '20'
+   *   }
+   * });
+   *
+   * console.log('Short URL:', result.shortUrl);   // https://adstage.net/ABCDEF
+   * console.log('Short Path:', result.shortPath); // ABCDEF
+   * ```
+   */
+  static async create(
+    request: CreateDeepLinkRequest
+  ): Promise<CreateDeepLinkResponse> {
+    if (!AdStageModule) {
+      throw new Error('AdStage: Native module is not available');
+    }
+
+    if (!request.name) {
+      throw new Error('AdStage: name is required for creating a deep link');
+    }
+
+    const result = await AdStageModule.createDeepLink(request);
+
+    return {
+      shortUrl: result.shortUrl,
+      shortPath: result.shortPath,
+      linkId: result.linkId,
+    };
+  }
+
+  // ============================================
+  // DeepLink Handling
+  // ============================================
+
+  /**
+   * Pending 딥링크 확인 및 처리
+   *
+   * 앱이 종료된 상태에서 딥링크로 실행된 경우,
+   * SDK 초기화 후 이 메서드를 호출하여 pending 딥링크를 처리합니다.
+   *
+   * @example
+   * ```typescript
+   * // SDK 초기화 후
+   * await AdStage.initialize({ apiKey: '...' });
+   *
+   * // 리스너 설정
+   * AdStage.deepLink.setListener((data) => {
+   *   console.log('딥링크:', data);
+   * });
+   *
+   * // Pending 딥링크 확인
+   * AdStage.deepLink.checkPendingDeepLink();
+   * ```
+   */
+  static checkPendingDeepLink(): void {
+    AdStageModule?.checkPendingDeepLink?.();
+  }
+
+  /**
+   * Intent 처리 (Android 전용)
+   *
+   * MainActivity에서 새로운 Intent가 들어올 때 호출합니다.
+   * iOS에서는 호출해도 무시됩니다.
+   *
+   * @example
+   * ```typescript
+   * // React Native에서 AppState 변경 감지
+   * import { Linking } from 'react-native';
+   *
+   * Linking.addEventListener('url', ({ url }) => {
+   *   // Android에서는 네이티브에서 자동 처리되므로 필요 없음
+   *   // 필요한 경우 수동 호출
+   *   AdStage.deepLink.handleIntent();
+   * });
+   * ```
+   */
+  static handleIntent(): void {
+    if (Platform.OS === 'android') {
+      AdStageModule?.handleIntent?.();
+    }
+  }
+
+  /**
+   * URL에서 Short Path 추출
+   *
+   * @param url - 딥링크 URL
+   * @returns Short Path 또는 null
+   *
+   * @example
+   * ```typescript
+   * const shortPath = AdStage.deepLink.extractShortPath('https://adstage.net/ABCDEF');
+   * console.log(shortPath); // "ABCDEF"
+   * ```
+   */
+  static extractShortPath(url: string): string | null {
+    try {
+      const urlObj = new URL(url);
+      const pathParts = urlObj.pathname.split('/').filter(Boolean);
+      return pathParts[0] ?? null;
+    } catch {
+      // URL Scheme인 경우
+      const match = url.match(/adstage\.(?:net|app)\/([A-Za-z0-9]+)/);
+      return match?.[1] ?? null;
+    }
+  }
+}