@tenqube/visual-reward-react-native 1.1.3

package/src/VisualReward.ts

@@ -0,0 +1,190 @@
+import { VisualRewardError } from './types';
+import type {
+  RemoteConfig,
+  RewardHandler,
+  VisualRewardInitializeOptions,
+  VisualRewardOpenOptions,
+} from './types';
+import { readCache, writeCache, setStorage, AsyncStorageLike } from './ConfigCache';
+
+const OPEN_TIMEOUT_MS = 5_000;
+// config fetch 연결/읽기 타임아웃 (다른 플랫폼과 동일: 10초).
+const CONFIG_FETCH_TIMEOUT_MS = 10_000;
+
+export class VisualReward {
+  private static readonly CONFIG_BASE_URL = 'https://visual.reward.tenqube.com';
+  private static _handler: RewardHandler | null = null;
+  private static _remoteConfig: RemoteConfig | null = null;
+  private static _configPromise: Promise<RemoteConfig> | null = null;
+  private static _initGeneration = 0;
+  private static _debugEnabled = false;
+  private static _userId = '';
+  private static _openTimeoutMs = OPEN_TIMEOUT_MS;
+
+  private constructor() {}
+
+  /** @internal Portal이 마운트될 때 핸들러를 등록합니다. */
+  static _register(handler: RewardHandler): void {
+    VisualReward._handler = handler;
+  }
+
+  /** @internal Portal이 언마운트될 때 핸들러를 해제합니다. */
+  static _unregister(): void {
+    VisualReward._handler = null;
+  }
+
+  /**
+   * SDK를 초기화합니다. App.tsx의 useEffect 등 앱 시작 시 한 번만 호출합니다.
+   */
+  static initialize(options: VisualRewardInitializeOptions): void {
+    const {
+      appKey,
+      timeoutMs = 5_000,
+      onSuccess,
+      onFailure,
+    } = options;
+    VisualReward._initGeneration++;
+    const generation = VisualReward._initGeneration;
+    VisualReward._openTimeoutMs = timeoutMs;
+    VisualReward._remoteConfig = null;
+    VisualReward._configPromise = VisualReward.fetchConfig(appKey, VisualReward.CONFIG_BASE_URL);
+    VisualReward._configPromise
+      .then((config) => {
+        if (VisualReward._initGeneration !== generation) return;
+        VisualReward._remoteConfig = config;
+        onSuccess?.();
+      })
+      .catch((e) => {
+        if (VisualReward._initGeneration !== generation) return;
+        onFailure?.(e);
+      });
+  }
+
+  /** WebView 디버깅 활성화 여부를 설정합니다. initialize() 전에 호출합니다. */
+  static setDebugEnabled(enabled: boolean): void {
+    VisualReward._debugEnabled = enabled;
+  }
+
+  /** AsyncStorage 구현체를 주입합니다. initialize() 전에 호출합니다. */
+  static setStorage(storage: AsyncStorageLike): void {
+    setStorage(storage);
+  }
+
+  /** 사용자 식별자를 설정합니다. open() 전에 반드시 호출합니다. */
+  static setUserId(userId: string): void {
+    VisualReward._userId = userId;
+  }
+
+  /**
+   * 리워드 웹뷰를 엽니다.
+   *
+   * 호스트 앱 루트에 `<VisualRewardContainer />`이 마운트되어 있어야 합니다.
+   */
+  static async open(options: VisualRewardOpenOptions): Promise<void> {
+    const { serviceName, locale: localeOption, extra, onClose, onError } = options;
+    // flutter/kotlin/swift 와 1:1: open 은 예외를 던지지 않고 모든 오류를 onError 로 전달한다.
+    try {
+      const userId = VisualReward._userId;
+      if (!userId) {
+        throw new VisualRewardError(
+          'USER_ID_NOT_SET',
+          'setUserId()가 호출되지 않았습니다. open() 전에 setUserId()를 호출해주세요.',
+        );
+      }
+
+      if (!VisualReward._handler) {
+        throw new VisualRewardError(
+          'NOT_INITIALIZED',
+          'VisualRewardContainer가 마운트되지 않았습니다. 앱 루트에 <VisualRewardContainer />을 추가해주세요.',
+        );
+      }
+
+      const locale = localeOption ?? 'ko';
+      const config = await VisualReward.resolveConfig();
+      const url = VisualReward.buildFinalUrl(config.baseUrl, serviceName, userId, locale, extra);
+
+      VisualReward._handler({
+        url,
+        allowedDomains: config.allowedDomains,
+        debugEnabled: VisualReward._debugEnabled,
+        onClose,
+      });
+    } catch (e) {
+      const err =
+        e instanceof VisualRewardError
+          ? e
+          : new VisualRewardError('NETWORK_ERROR', `열기 실패: ${e}`, e);
+      onError?.(err);
+    }
+  }
+
+  private static async resolveConfig(): Promise<RemoteConfig> {
+    if (VisualReward._remoteConfig) return VisualReward._remoteConfig;
+    const promise = VisualReward._configPromise;
+    if (!promise) {
+      throw new VisualRewardError('NOT_INITIALIZED', 'initialize() 호출 없이 open() 호출됨');
+    }
+    const config = await Promise.race([
+      promise,
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () => reject(new VisualRewardError('INITIALIZE_TIMEOUT', 'initialize() 타임아웃')),
+          VisualReward._openTimeoutMs,
+        ),
+      ),
+    ]);
+    VisualReward._remoteConfig = config;
+    return config;
+  }
+
+  private static async fetchConfig(appKey: string, baseUrl: string): Promise<RemoteConfig> {
+    const cached = await readCache(appKey);
+    if (cached) return cached;
+
+    const url = `${baseUrl}/sdk/config/v1/${appKey}.json`;
+    // 다른 플랫폼과 동일하게 연결/읽기 10초 타임아웃 (초과 시 abort → NETWORK_ERROR).
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), CONFIG_FETCH_TIMEOUT_MS);
+    try {
+      let response: Response;
+      try {
+        response = await fetch(url, { signal: controller.signal });
+      } catch (e) {
+        throw new VisualRewardError('NETWORK_ERROR', `네트워크 오류: ${e}`, e);
+      }
+      if (response.status === 404) {
+        throw new VisualRewardError('INVALID_APP_KEY', '존재하지 않는 앱 키');
+      }
+      if (!response.ok) {
+        throw new VisualRewardError('SERVER_ERROR', `서버 오류: ${response.status}`, response.status);
+      }
+      try {
+        const config = (await response.json()) as RemoteConfig;
+        await writeCache(appKey, config);
+        return config;
+      } catch (e) {
+        throw new VisualRewardError('PARSE_ERROR', `응답 파싱 오류: ${e}`, e);
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private static buildFinalUrl(
+    baseUrl: string,
+    serviceName: string,
+    userId: string,
+    locale: string,
+    extra?: string,
+  ): string {
+    const url = new URL(`${baseUrl}${serviceName}/`);
+    // 예약 키는 base 쿼리에 이미 있어도 덮어쓴다 (flutter/kotlin/swift 와 동일).
+    url.searchParams.delete('userId');
+    url.searchParams.delete('hl');
+    url.searchParams.delete('extra');
+    url.searchParams.set('userId', userId);
+    url.searchParams.set('hl', locale);
+    if (extra !== undefined && extra !== null && extra !== '') url.searchParams.set('extra', extra);
+    return url.toString();
+  }
+}

package/src/VisualRewardContainer.tsx

@@ -0,0 +1,121 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import {
+  BackHandler,
+  Modal,
+  Platform,
+  StatusBar,
+  StyleSheet,
+  View,
+} from "react-native";
+import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
+import RewardWebView from "./RewardWebView";
+import { VisualReward } from "./VisualReward";
+import type { RewardWebViewHandle, RewardWebViewProps } from "./types";
+
+/**
+ * VisualRewardContainer
+ *
+ * 앱 루트에 한 번만 추가합니다. `VisualReward.open()` 호출 시 리워드 웹뷰를 Modal 로 렌더링합니다.
+ *
+ * 항상 최상단에 뜨는 것을 크로스플랫폼으로 보장하기 위해 `Modal`(별도 window)을 사용합니다.
+ * (비-Modal 오버레이는 react-navigation native-stack 의 네이티브 화면에 가려질 수 있음)
+ * Modal window 는 RN `StatusBar` API 로 아이콘 색을 못 바꾸므로, 상단 safe-area 를 다크로 두고
+ * 밝은 상태바 아이콘이 보이도록 한다.
+ *
+ * @example
+ * // App.tsx
+ * import { VisualRewardContainer } from '@tenqube/visual-reward-react-native';
+ * export default function App() {
+ *   return (
+ *     <>
+ *       <YourNavigator />
+ *       <VisualRewardContainer />
+ *     </>
+ *   );
+ * }
+ */
+const VisualRewardContainer: React.FC = () => {
+  const [options, setOptions] = useState<RewardWebViewProps | null>(null);
+  const visible = options !== null;
+  const rewardWebViewRef = useRef<RewardWebViewHandle>(null);
+  const optionsRef = useRef<RewardWebViewProps | null>(null);
+  optionsRef.current = options;
+
+  // VisualReward 싱글톤에 핸들러 등록
+  useEffect(() => {
+    VisualReward._register((opts) => {
+      setOptions(opts);
+    });
+    return () => {
+      VisualReward._unregister();
+    };
+  }, []);
+
+  const handleClose = useCallback(() => {
+    optionsRef.current?.onClose?.();
+    setOptions(null);
+  }, []);
+
+  // Android Back 키: RewardWebView 가 처리한 경우(true 반환) 닫지 않는다.
+  const handleBackPress = useCallback(() => {
+    const consumed = rewardWebViewRef.current?.handleBackPress() ?? false;
+    if (!consumed) {
+      handleClose();
+    }
+    return true; // 항상 true (Activity 종료 방지)
+  }, [handleClose]);
+
+  // Android BackHandler: Modal 이 열린 동안만 등록
+  useEffect(() => {
+    if (!visible || Platform.OS !== "android") return;
+    const subscription = BackHandler.addEventListener(
+      "hardwareBackPress",
+      handleBackPress,
+    );
+    return () => subscription.remove();
+  }, [visible, handleBackPress]);
+
+  return (
+    <Modal
+      visible={visible}
+      animationType="slide"
+      presentationStyle="fullScreen"
+      statusBarTranslucent={Platform.OS === "android"}
+      onRequestClose={handleBackPress}
+    >
+      {/* Modal 은 별도 window 라 자체 SafeAreaProvider 로 inset 을 다시 측정한다.
+          상단 safe-area 를 흰색으로 두고 상태바 아이콘을 dark-content(검정)로 표시한다. */}
+      <SafeAreaProvider style={styles.safeArea}>
+        <StatusBar barStyle="dark-content" backgroundColor="#ffffff" />
+        <SafeAreaView style={styles.safeArea} edges={["top", "bottom"]}>
+          <View style={styles.container}>
+            {options && (
+              <RewardWebView
+                ref={rewardWebViewRef}
+                key={options.url}
+                url={options.url}
+                allowedDomains={options.allowedDomains}
+                debugEnabled={options.debugEnabled ?? false}
+                onClose={handleClose}
+              />
+            )}
+          </View>
+        </SafeAreaView>
+      </SafeAreaProvider>
+    </Modal>
+  );
+};
+
+const styles = StyleSheet.create({
+  // safe-area(상태바/제스처바) 영역. 검정 상태바 아이콘이 보이도록 흰색.
+  safeArea: {
+    flex: 1,
+    backgroundColor: "#ffffff",
+  },
+  container: {
+    flex: 1,
+    backgroundColor: "#ffffff",
+  },
+});
+
+export default VisualRewardContainer;

package/src/types.ts

@@ -0,0 +1,66 @@
+export type VisualRewardErrorCode =
+  | 'NETWORK_ERROR'
+  | 'INITIALIZE_TIMEOUT'
+  | 'INVALID_APP_KEY'
+  | 'SERVER_ERROR'
+  | 'PARSE_ERROR'
+  | 'NOT_INITIALIZED'
+  | 'USER_ID_NOT_SET';
+
+export class VisualRewardError extends Error {
+  constructor(
+    public readonly code: VisualRewardErrorCode,
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'VisualRewardError';
+  }
+}
+
+export interface VisualRewardInitializeOptions {
+  /** 앱 식별 키 */
+  appKey: string;
+  /** initialize() 완료 대기 타임아웃 (ms). 기본값 `5000`. */
+  timeoutMs?: number;
+  /** 초기화 성공 콜백 (선택). */
+  onSuccess?: () => void;
+  /** 초기화 실패 콜백 (선택). */
+  onFailure?: (error: VisualRewardError) => void;
+}
+
+export interface VisualRewardOpenOptions {
+  /** 지면 식별자 */
+  serviceName: string;
+  /** 언어 코드. 기본값 `'ko'` (선택). */
+  locale?: string;
+  /** 추가 파라미터 (옵션) */
+  extra?: string;
+  /** 웹뷰가 닫힐 때 호출되는 콜백. */
+  onClose?: () => void;
+  /** 리워드 웹뷰 열기 실패 시 호출되는 콜백. (open 은 예외를 던지지 않음) */
+  onError?: (error: VisualRewardError) => void;
+}
+
+/** RewardWebView 내부에서 사용하는 props */
+export interface RewardWebViewProps {
+  url: string;
+  allowedDomains: string[];
+  debugEnabled: boolean;
+  onClose?: () => void;
+}
+
+/** VisualRewardContainer 내부에서 사용하는 핸들러 타입 */
+export type RewardHandler = (options: RewardWebViewProps) => void;
+
+/** forwardRef로 노출되는 RewardWebView 핸들 */
+export interface RewardWebViewHandle {
+  /** Back 키 처리. true를 반환하면 기본 동작 차단. */
+  handleBackPress: () => boolean;
+}
+
+/** 서버 config 응답 */
+export interface RemoteConfig {
+  baseUrl: string;
+  allowedDomains: string[];
+}

package/src/utils.ts

@@ -0,0 +1,24 @@
+/** 문자열 시작에 `scheme://` 가 있는지 판별 (쿼리스트링 내부의 `://` 오탐 방지 위해 `^` 앵커). */
+const SCHEME_REGEX = /^[a-zA-Z][a-zA-Z0-9+.\-]*:\/\//;
+
+/**
+ * URL에 스킴이 없으면 `https://`를 붙여 반환합니다.
+ * Kotlin/Swift/Flutter SDK 의 `SdkConfig.normalizeUrl` 과 1:1.
+ */
+export function normalizeUrl(url: string | null | undefined): string {
+  const raw = (url ?? '').trim();
+  if (!raw) return raw;
+  return SCHEME_REGEX.test(raw) ? raw : `https://${raw}`;
+}
+
+/**
+ * host가 allowedDomains 내에 속하는지 확인합니다.
+ * 예) host="reward.tenqube.com", base="tenqube.com" → true
+ */
+export function isAllowedDomain(host: string, allowedDomains: string[]): boolean {
+  const h = host.toLowerCase();
+  return allowedDomains.some((base) => {
+    const b = base.toLowerCase();
+    return h === b || h.endsWith(`.${b}`);
+  });
+}

package/visual-reward-react-native.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "visual-reward-react-native"
+  s.version      = package["version"]
+  s.summary      = "Tenqube Visual Reward SDK for React Native"
+  s.homepage     = "https://tenqube.com"
+  s.license      = "MIT"
+  s.authors      = { "tenqube" => "dev@tenqube.com" }
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => "https://github.com/tenqube/visual-reward-sdk-react-native.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  # GMA / AdPopcorn 은 리플렉션으로만 참조하므로 컴파일 의존성 없음(옵셔널).
+  # react-native-webview 의 WKWebView 는 뷰 계층 탐색으로 찾으므로 의존성 불필요.
+  s.dependency "React-Core"
+end