npm - @tenqube/visual-reward-react-native - Versions diffs - 1.1.5 → 1.1.6 - Mend

@tenqube/visual-reward-react-native 1.1.5 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md +6 -0
package/README.md +200 -597
package/android/src/main/AndroidManifest.xml +5 -0
package/package.json +1 -1
package/src/ConfigCache.ts +1 -7
package/src/VisualReward.ts +4 -6
package/src/types.ts +12 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,11 @@
 # @tenqube/visual-reward
+## 1.1.6
+### Patch Changes
+- 4c13cbd: feat: setStorage 제거 및 initialize storage 파라미터 추가합니다.
 ## 1.1.5
 ### Patch Changes

package/README.md CHANGED Viewed

@@ -2,62 +2,51 @@
 React Native WebView 기반 리워드 광고 SDK입니다.
----
 ## 요구사항
 - React Native 0.76+
 - iOS 13.0+
-- Android minSdk 21
----
+- Android minSdk 24
 ## 설치
-### 방법 1) npm (권장)
-```sh
-npm install @tenqube/visual-reward-react-native
-```
-이 SDK는 WebView 렌더 표면인 `react-native-webview` **하나만** peer dependency로 요구합니다. 호스트 앱과 **버전이 충돌하지 않도록**(단일 버전 보장) 호스트 앱에 직접 설치하며, 이미 설치되어 있으면 그대로 두면 됩니다.
-```sh
-npm install react-native-webview
-```
-> 기기·앱 정보, 광고 식별자(ADID/IDFA), ATT 요청, 방향 고정, safe-area inset 등은 SDK가 네이티브(iOS Swift / Android Kotlin) 모듈로 직접 처리하므로, `react-native-device-info`·`react-native-idfa-aaid`·`@react-native-community/netinfo`·`react-native-permissions`·`react-native-orientation-locker`·`react-native-safe-area-context` 같은 추가 플러그인을 설치할 필요가 없습니다. (호스트 앱의 해당 플러그인 버전과 충돌하지 않습니다.)
+### npm (권장)
-> 광고 연동(GMA / AdPopcorn SSP)은 **선택적 peer dependency**이며, 사용할 때만 설치합니다. ([AdMob / Ad Manager WebView 광고 연동](#admob--ad-manager-webview-광고-연동-선택) 참고)
+- https://www.npmjs.com/package/@tenqube/visual-reward-react-native
-### 방법 2) 수동 설치 (GitHub Release)
+    ```bash
+    npm install @tenqube/visual-reward-react-native react-native-webview
+    ```
-npm을 쓰지 않는 경우, [GitHub Release](https://github.com/tenqube/visual-reward-sdk-react-native/releases)에서 `visual-reward-react-native-<버전>.zip`을 내려받아 압축을 풀고 프로젝트 내 원하는 위치에 복사합니다. (zip에는 `android/`, `ios/` 네이티브 모듈이 포함되어 있습니다.) 그런 다음 `package.json`에 `file:` 경로 및 `react-native-webview`를 추가합니다.
+### 수동 설치
-```json
-"dependencies": {
-  "@tenqube/visual-reward-react-native": "file:./visual-reward-react-native",
-  "react-native-webview": ">=13.0.0"
-}
-```
+- **Visual Reward React Native SDK**
+    - https://github.com/tenqube/visual-reward-sdk-react-native/releases
+- `visual-reward-react-native-{version}.zip`을 다운로드한 뒤 압축을 해제합니다 (zip에는 `android/`, `ios/` 네이티브 모듈이 포함되어 있습니다).
+- `package.json`에 `file:` 경로 및 `react-native-webview`를 추가합니다.
-```sh
-npm install
-```
+    ```json
+    "dependencies": {
+      "@tenqube/visual-reward-react-native": "file:./visual-reward-react-native",
+      "react-native-webview": ">=13.0.0"
+    }
+    ```
-### 공통) iOS pod install
+    ```bash
+    npm install
+    ```
-두 방법 모두 iOS는 추가로 pod install을 실행합니다.
+### iOS pod install
-```sh
-cd ios && pod install
-```
+- 두 방법 모두 iOS는 추가로 `pod install`을 실행합니다.
-> 이 패키지는 GMA registerWebView / AdPopcorn 브릿지 등록을 위한 **네이티브 모듈**(iOS Swift / Android Kotlin)을 포함하며, React Native 오토링크로 자동 연결됩니다. (iOS는 `pod install`, Android는 Gradle sync 시 자동 반영)
+    ```bash
+    cd ios && pod install
+    ```
 ### VisualRewardContainer 루트 추가
-앱의 루트 컴포넌트(예: `App.tsx`)에 `<VisualRewardContainer />`을 추가합니다.
+- 앱의 루트 컴포넌트(예: `App.tsx`)에 `<VisualRewardContainer />`을 추가합니다.
 ```tsx
 import { VisualRewardContainer } from '@tenqube/visual-reward-react-native';
@@ -72,626 +61,240 @@ export default function App() {
 }
 ```
----
-## R8 / ProGuard
-GMA / AdPopcorn 리플렉션 대상 보존 규칙(`AdPopcornSSPJsBridge`, `MobileAds`)은 SDK의 `consumer-rules.pro`에 포함되어 호스트 앱 R8에 **자동 전파**됩니다. 별도 추가가 필요 없습니다.
-`minifyEnabled = true`를 쓰는 경우 호스트 앱의 WebView JavascriptInterface 보존을 위해 아래만 확인합니다.
-```proguard
-# react-native-webview
--keep class com.reactnativecommunity.webview.** { *; }
+## 권한
-# WebView JavascriptInterface
--keepclassmembers class * {
-    @android.webkit.JavascriptInterface <methods>;
-}
-```
+### iOS
----
+- IDFA 조회(`getIDFA`)를 사용하려면 `Info.plist`에 ATT 사용 목적 문자열을 추가해야 합니다.
-## AdMob / Ad Manager WebView 광고 연동 (선택)
+    ```xml
+    <key>NSUserTrackingUsageDescription</key>
+    <string>맞춤형 광고 제공을 위해 기기 식별자를 사용합니다.</string>
+    ```
-WebView 내부 광고(AdSense / Google Publisher Tag / IMA HTML5)의 수익화·측정 신호를 개선하는 WebView API for Ads를 지원합니다. AdMob과 Google Ad Manager(GAM)는 동일한 Google Mobile Ads SDK를 사용하므로 양쪽 모두 동작합니다.
+    > ATT 권한 요청은 SDK가 웹뷰 로드 전 네이티브 `ATTrackingManager`로 자동 처리합니다. 이미 권한이 결정된 경우 팝업 없이 즉시 진행됩니다.
-이 SDK는 호스트 앱에 **GMA SDK가 있을 때만** 네이티브 모듈에서 리플렉션으로 `registerWebView`를 자동 호출합니다. AdPopcorn SSP 오퍼월을 쓰는 경우에는 **AdPopcorn 네이티브 브릿지(`AdPopcornSSPJsBridge`)도 자동 주입**합니다(오퍼월의 웹 배너 SDK가 네이티브 컨텍스트를 필요로 하므로 **실제 네이티브 브릿지**를 연결 — 순수 JS shim 으로는 불가). SDK가 하는 일은 이 연결뿐이며, **SDK 의존성·App ID·초기화는 모두 호스트 앱에서 설정**해야 합니다.
+## Ad Manager WebView 광고 연동
-> react-native-webview는 "로드 전 네이티브 인터페이스 주입" 훅이 없어, SDK는 실제 오퍼월 URL 로드 전에 `about:blank`를 먼저 띄워 브릿지를 주입한 뒤 URL을 로드합니다. 덕분에 오퍼월은 한 번만 로드되고 첫 페이지부터 브릿지가 바인딩됩니다(리로드 불필요).
+- **SDK 의존성·App ID·초기화는 모두 호스트 앱에서 설정이 필요합니다.**
+- 호스트 앱에 Google Mobile Ads SDK가 링크돼 있으면, SDK가 리워드 웹뷰를 자동으로 `registerWebView`에 등록해 WebView 내부 광고(AdSense/GPT/IMA HTML5)의 수익화·측정 신호를 개선합니다.
+- 기존에 애드몹 등을 사용 중인 경우 정상 적용 여부만 확인해주시면 됩니다.
-### 1. 의존성 (호스트 앱)
+### 의존성
-```sh
+```bash
 # GMA WebView API for Ads
 npm install react-native-google-mobile-ads
-# AdPopcorn SSP (오퍼월 배너/전면 광고를 쓰면 필요 — 네이티브 SSP SDK 번들)
-npm install react-native-adpopcorn-ssp
 ```
-AdPopcorn 미디에이션으로 **AppLovin MAX** 를 쓰면 네트워크 SDK 를 추가합니다 (어댑터는 AdPopcorn SSP 코어에 번들, 네트워크 SDK 만 추가). flutter/kotlin/swift 와 동일 버전대.
+### App ID
-```ruby
-# iOS — ios/Podfile 의 target 안
-pod 'AppLovinSDK', '~> 13.6.3'
-```
-```gradle
-// Android — android/app/build.gradle 의 dependencies
-implementation("com.applovin:applovin-sdk:13.6.2")
-```
+1. AndroidManifest.xml
-> 이 SDK는 위 패키지에 **컴파일 의존하지 않습니다**(리플렉션·뷰탐색만 사용). 호스트가 링크하면 동작하고, 없으면 무시됩니다. `react-native-google-mobile-ads`는 GMA 네이티브 심볼을 앱에 링크하는 용도이며, 등록 자체는 이 SDK가 직접 수행합니다. AdPopcorn 은 `react-native-adpopcorn-ssp` 가 번들한 **네이티브 SSP SDK** 를 SDK 가 리플렉션으로 웹뷰에 연결합니다.
+    ```xml
+    <!-- App ID 누락 시 시작 크래시 -->
+    <meta-data
+        android:name="com.google.android.gms.ads.APPLICATION_ID"
+        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
+    <!-- WebView 전용일 때만 추가. 자체 광고도 서빙하면 이 메타데이터는 삭제 -->
+    <meta-data
+        android:name="com.google.android.gms.ads.INTEGRATION_MANAGER"
+        android:value="webview" />
+    ```
-### 2. App ID / 초기화 — 아래 두 경우 중 해당하는 쪽으로 설정
+2. Info.plist
-- **WebView 신호 전용**: 이 앱으로 **자체 광고를 서빙하지 않고** WebView 안 광고 신호만 쓰는 경우
-- **자체 광고 병행**: 호스트 앱이 GMA로 자기 앱에 **자체 인앱 광고(배너·전면 등)도 함께** 서빙하는 경우
+    ```xml
+    <!-- App ID 누락 시 시작 크래시 -->
+    <key>GADApplicationIdentifier</key>
+    <string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>
+    <!-- WebView 전용일 때만 추가. 자체 광고도 서빙하면 이 키는 삭제 -->
+    <key>GADIntegrationManager</key>
+    <string>webview</string>
+    ```
-| 경우 | iOS (`Info.plist`) | Android (`AndroidManifest.xml`) |
-|---|---|---|
-| **WebView 신호 전용** | 실제 App ID(`GADApplicationIdentifier`) + `GADIntegrationManager=webview` | 실제 App ID(`APPLICATION_ID`) + `INTEGRATION_MANAGER=webview` |
-| **자체 광고 병행** | 실제 App ID만 | 실제 App ID만 (**`INTEGRATION_MANAGER` 생략**) |
-> WebView 전용이어도 **실제 App ID가 필수**입니다(없으면 시작 크래시).
-호스트 앱 시작 시 각 SDK를 1회 초기화합니다. (앱키·App ID는 호스트 설정 — 다른 플랫폼과 동일)
-```tsx
-import mobileAds from 'react-native-google-mobile-ads';
-import { AdPopcornSSP } from 'react-native-adpopcorn-ssp';
-import { Platform } from 'react-native';
-useEffect(() => {
-  mobileAds().initialize();
-  AdPopcornSSP.init(Platform.OS === 'ios' ? IOS_APP_KEY : ANDROID_APP_KEY);
-}, []);
-```
-**iOS** — `ios/<App>/Info.plist` (아래는 *WebView 전용* 예시)
-```xml
-<key>GADApplicationIdentifier</key>
-<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>
-<key>GADIntegrationManager</key>
-<string>webview</string>
-```
-**Android** — `android/app/src/main/AndroidManifest.xml` (아래는 *WebView 전용* 예시)
-```xml
-<!-- App ID 누락 시 시작 크래시 -->
-<meta-data
-    android:name="com.google.android.gms.ads.APPLICATION_ID"
-    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
-<!-- WebView 전용일 때만 추가. 자체 광고도 서빙하면 이 메타데이터는 삭제 -->
-<meta-data
-    android:name="com.google.android.gms.ads.INTEGRATION_MANAGER"
-    android:value="webview" />
-<!-- 애드팝콘 SSP 앱 키 -->
-<meta-data android:name="adpopcorn_ssp_app_key" android:value="YOUR_APP_KEY" />
-```
-### 연동 검증
-등록이 실행되면 네이티브 로그(프리픽스 `VisualReward`)가 남습니다. (Android: Logcat / iOS: Xcode 콘솔)
-- 성공(GMA): `AdMob registerWebView registered` — Android는 괄호 안에 사용된 클래스명 표시
-- 성공(AdPopcorn): `AdPopcornSSPJsBridge registered`
-- 미링크(GMA): `Google Mobile Ads SDK not linked / not on classpath — AdMob WebView API not registered`
-- 미링크(AdPopcorn): `AdPopcornSSPJsBridge class not on classpath — bridge not registered`
-- WebView 미검출: `attachAdBridges skipped (WebView 미검출)`
-Google [테스트 페이지](https://google.github.io/webview-ads/test/#api-for-ads-tests)로 초록 상태 바까지 확인하려면, 해당 도메인(`google.github.io`)을 원격 설정 `allowedDomains`에 추가한 상태에서 그 페이지를 SDK 웹뷰로 로드해야 합니다. (설정 캐시 TTL 1시간 주의)
+### 초기화
-> ⚠️ react-native-webview가 내부 WebView 인스턴스를 노출하지 않아, 네이티브 뷰 계층에서 WebView를 탐색해 등록하는 **best-effort** 방식입니다. 화면에 보이는 가장 큰 WebView를 리워드 웹뷰로 간주합니다.
+- 호스트 앱 시작 시 1회 초기화합니다.
----
+    ```tsx
+    import mobileAds from 'react-native-google-mobile-ads';
-## 권한
+    useEffect(() => {
+      mobileAds().initialize();
+    }, []);
+    ```
-### Android
+## 시퀀스 다이어그램
-광고 ID 접근 권한(`com.google.android.gms.permission.AD_ID`)은 SDK가 의존하는 `play-services-ads-identifier`가 매니페스트 병합으로 **자동 추가**하므로, 호스트가 별도로 선언할 필요가 없습니다. (광고 ID를 수집하는 앱이 이 권한을 선언하는 것은 Play 정책상 올바른 동작입니다.)
+```mermaid
+sequenceDiagram
+    title interaction VisualReward SDK
-아동 대상 앱 등 광고 ID 권한을 원치 않는 경우에만 호스트 `AndroidManifest.xml`에서 명시적으로 제거할 수 있습니다.
+    participant A as Host App
+    participant B as VisualReward SDK
+    participant C as VisualReward 서버
+    participant D as WebView 화면
-```xml
-<uses-permission android:name="com.google.android.gms.permission.AD_ID"
-    tools:node="remove" />
-```
+    A->>B: initialize(appKey, ...)
+    B->>C: config 요청
+    C-->>B: config 응답
+    B-->>A: onSuccess()
-### iOS
+    A->>B: setUserId(userId)
-IDFA 조회(`getIDFA`)를 사용하려면 `Info.plist`에 ATT 사용 목적 문자열을 추가해야 합니다.
+    A->>B: open(serviceName, ...)
+    B->>D: 웹뷰 열기
-```xml
-<key>NSUserTrackingUsageDescription</key>
-<string>맞춤형 광고 제공을 위해 기기 식별자를 사용합니다.</string>
+    D->>B: 웹뷰 닫힘
+    B-->>A: onClose
 ```
-> ATT 권한 요청은 SDK가 웹뷰 로드 전 네이티브 `ATTrackingManager`로 자동 처리합니다. 이미 권한이 결정된 경우 팝업 없이 즉시 진행됩니다. `NSUserTrackingUsageDescription`이 없으면 요청을 스킵하고 바로 로드합니다.
----
 ## 사용법
-### 스토리지 설정
-config 캐싱을 위해 `initialize()` 전에 `AsyncStorage`를 주입합니다. 설정하지 않으면 매번 네트워크에서 config를 fetch합니다.
-```tsx
-import { VisualReward } from '@tenqube/visual-reward-react-native';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-VisualReward.setStorage(AsyncStorage);
-```
-> `@react-native-async-storage/async-storage`가 설치되어 있지 않다면 `npm install @react-native-async-storage/async-storage`로 설치합니다.
----
 ### 디버그 설정
-`initialize()` 전에 호출합니다.
-```tsx
-import { VisualReward } from '@tenqube/visual-reward-react-native';
+- `initialize()` 전에 호출합니다.
-VisualReward.setDebugEnabled(__DEV__);
-```
+    ```tsx
+    import { VisualReward } from '@tenqube/visual-reward-react-native';
----
+    VisualReward.setDebugEnabled(__DEV__);
+    ```
 ### 초기화
-`App.tsx`의 `useEffect` 등 앱 시작 시 한 번만 호출합니다.
+- `App.tsx`의 `useEffect` 등 앱 시작 시 한 번만 호출합니다.
-```tsx
-import { VisualReward } from '@tenqube/visual-reward-react-native';
-useEffect(() => {
-  VisualReward.initialize({
-    appKey: 'tq_live_xxx',
-    timeoutMs: 5000,        // 기본값 (ms)
-    onSuccess: () => { /* SDK 준비 완료 */ },
-    onFailure: (e) => { /* 초기화 실패 */ },
-  });
-}, []);
-```
+    ```tsx
+    import { VisualReward } from '@tenqube/visual-reward-react-native';
+    import AsyncStorage from '@react-native-async-storage/async-storage';
+    useEffect(() => {
+      VisualReward.initialize({
+        appKey: 'tq_live_xxx',
+        storage: AsyncStorage,  // config 캐싱용 (선택)
+        timeoutMs: 5000,        // 기본값 (ms)
+        onSuccess: () => { /* SDK 준비 완료 */ },
+        onFailure: (e) => { /* 초기화 실패 */ },
+      });
+    }, []);
+    ```
-### initialize 파라미터
+    > config 캐싱을 사용하려면 `storage`에 `AsyncStorage`를 주입합니다. 미주입 시 매번 네트워크에서 config를 fetch합니다. `@react-native-async-storage/async-storage`가 설치되어 있지 않다면 `npm install @react-native-async-storage/async-storage`로 설치합니다.
-| 파라미터        | 타입                        | 필수 | 기본값         | 설명                                        |
-| --------------- | --------------------------- | ---- | -------------- | ------------------------------------------- |
-| `appKey`        | `string`                    | ✅   |                | 앱 식별 키                                  |
-| `timeoutMs`     | `number`                    |      | `5000`         | 초기화 완료 대기 시간 (ms). 초과 시 `INITIALIZE_TIMEOUT` 에러 발생 |
-| `onSuccess`     | `() => void`                |      | `undefined`    | 초기화 성공 콜백 (선택)                     |
-| `onFailure`     | `(error: VisualRewardError) => void` |      | `undefined`    | 초기화 실패 콜백 (선택)                     |
+- initialize 파라미터
----
+    | **파라미터** | **타입** | **필수** | **설명** | 기본값 |
+    | --- | --- | --- | --- | --- |
+    | `appKey` | `string` | ✅ | stage별 app_key 발급 요청이 필요합니다. |  |
+    | `storage` | `AsyncStorageLike` |  | config 캐싱용 AsyncStorage 구현체. 미주입 시 캐싱 없이 매번 fetch | `undefined` |
+    | `timeoutMs` | `number` |  | 초기화 완료 대기 시간 (ms). 초과 시 `INITIALIZE_TIMEOUT` 에러 발생 | `5000` |
+    | `onSuccess` | `() => void` |  | 초기화 성공 콜백 | `undefined` |
+    | `onFailure` | `(error: VisualRewardError) => void` |  | 초기화 실패 콜백 | `undefined` |
 ### 사용자 설정
-로그인 후 또는 사용자가 변경될 때 호출합니다. `open()` 전에 반드시 호출해야 합니다.
+- 로그인 후 또는 사용자가 변경될 때 호출합니다. `open()` 전에 반드시 호출해야 합니다.
-```tsx
-VisualReward.setUserId(user.id);
-```
----
+    ```tsx
+    VisualReward.setUserId(user.id);
+    ```
 ### 웹뷰 열기
-```tsx
-import { VisualReward } from '@tenqube/visual-reward-react-native';
-await VisualReward.open({
-  serviceName: 'reward_home',
-  locale: 'ko',
-  extra: undefined,
-  onClose: () => { /* 웹뷰 닫힘 */ },
-});
-```
+- `initialize()` 후에 호출합니다.
+    ```tsx
+    import { VisualReward } from '@tenqube/visual-reward-react-native';
-### open 파라미터
+    await VisualReward.open({
+      serviceName: 'reward_home',
+      locale: 'ko',
+      extra: undefined,
+      onClose: () => { /* 웹뷰 닫힘 */ },
+    });
+    ```
-| 파라미터      | 타입                  | 필수 | 기본값      | 설명                                 |
-| ------------- | --------------------- | ---- | ----------- | ------------------------------------ |
-| `serviceName` | `string`              | ✅   |             | 서비스 이름                          |
-| `locale`      | `string \| undefined` |      | `'ko'` | 언어 코드 |
-| `extra`       | `string \| undefined` |      | `undefined` | 추가 query parameter (선택)          |
-| `onClose`     | `() => void`          |      | `undefined` | 웹뷰가 닫힐 때 호출되는 콜백 (선택) |
-| `onError`     | `(error: VisualRewardError) => void` |      | `undefined` | 열기 실패 콜백 (선택). `open` 은 예외를 던지지 않음 |
+- open 파라미터
----
+    | **파라미터** | **타입** | **필수** | **설명** | 기본값 |
+    | --- | --- | --- | --- | --- |
+    | `serviceName` | `string` | ✅ | 사용 서비스별 serviceName 전달 예정입니다. |  |
+    | `locale` | `string \| undefined` |  | BCP 47 (RFC 5646) 언어 서브태그(ISO 639-1, 2자리 소문자)를 사용 | `"ko"` |
+    | `extra` | `string \| undefined` |  | 포스트백 추가 데이터 (JSON serialize된 문자열) | `undefined` |
+    | `onClose` | `() => void` |  | 웹뷰가 닫힐 때 호출되는 콜백 | `undefined` |
+    | `onError` | `(error: VisualRewardError) => void` |  | 에러 발생 시 호출되는 콜백 | `undefined` |
 ## 에러 처리
 ### 에러 타입
-`VisualRewardError`의 `code` 프로퍼티로 에러 종류를 구분합니다.
-| `code`               | 설명                                      |
-| -------------------- | ----------------------------------------- |
-| `NETWORK_ERROR`      | 네트워크 연결 실패                        |
-| `INITIALIZE_TIMEOUT` | `initialize()` 호출 후 완료까지 타임아웃  |
-| `INVALID_APP_KEY`    | 존재하지 않는 앱 키 (404)                 |
-| `SERVER_ERROR`       | 서버 오류 (5xx)                           |
-| `PARSE_ERROR`        | 응답 파싱 실패                            |
-| `NOT_INITIALIZED`    | `initialize()` 호출 없이 `open()` 호출   |
-| `USER_ID_NOT_SET`    | `setUserId()` 호출 없이 `open()` 호출    |
+| 타입 | 설명 |
+| --- | --- |
+| `NETWORK_ERROR` | 네트워크 연결 실패 |
+| `INITIALIZE_TIMEOUT` | `initialize()` 호출 후 완료까지 타임아웃 |
+| `INVALID_APP_KEY` | 유효하지 않은 앱 키 (404) |
+| `SERVER_ERROR` | 서버 오류 (5xx) |
+| `PARSE_ERROR` | 응답 파싱 실패 |
+| `NOT_INITIALIZED` | `initialize()` 호출 없이 `open()` 호출 |
+| `USER_ID_NOT_SET` | `setUserId()` 호출 없이 `open()` 호출 |
 ### initialize 에러 처리
-`onFailure` 콜백에서 `VisualRewardError`의 `code`를 분기합니다.
-```tsx
-import { VisualReward, VisualRewardError } from '@tenqube/visual-reward-react-native';
-VisualReward.initialize({
-  appKey: 'tq_live_xxx',
-  timeoutMs: 5000,
-  onSuccess: () => { /* SDK 준비 완료 */ },
-  onFailure: (e) => {
-    if (e instanceof VisualRewardError) {
-      switch (e.code) {
-        case 'NETWORK_ERROR':
-          break; // 네트워크 연결 실패
-        case 'INITIALIZE_TIMEOUT':
-          break; // 초기화 타임아웃
-        case 'INVALID_APP_KEY':
-          break; // 존재하지 않는 앱 키
-        case 'SERVER_ERROR':
-          break; // 서버 오류
-        case 'PARSE_ERROR':
-          break; // 응답 파싱 실패
-      }
-    }
-  },
-});
-```
+- `onFailure` 콜백에서 에러 타입을 분기합니다.
+    ```tsx
+    import { VisualReward, VisualRewardError } from '@tenqube/visual-reward-react-native';
+    VisualReward.initialize({
+      appKey: 'tq_live_xxx',
+      timeoutMs: 5000,
+      onSuccess: () => { /* SDK 준비 완료 */ },
+      onFailure: (e) => {
+        if (e instanceof VisualRewardError) {
+          switch (e.code) {
+            case 'NETWORK_ERROR':
+              break; // 네트워크 연결 실패
+            case 'INITIALIZE_TIMEOUT':
+              break; // 초기화 타임아웃
+            case 'INVALID_APP_KEY':
+              break; // 존재하지 않는 앱 키
+            case 'SERVER_ERROR':
+              break; // 서버 오류
+            case 'PARSE_ERROR':
+              break; // 응답 파싱 실패
+          }
+        }
+      },
+    });
+    ```
 ### open 에러 처리
-`open()`은 예외를 던지지 않습니다. 오류는 `onError` 콜백으로 전달됩니다 (flutter/kotlin/swift SDK 와 동일).
-```tsx
-import { VisualReward, VisualRewardError } from '@tenqube/visual-reward-react-native';
-await VisualReward.open({
-  serviceName: 'reward_home',
-  locale: 'ko',
-  extra: undefined,
-  onClose: () => { /* 웹뷰 닫힘 */ },
-  onError: (e: VisualRewardError) => {
-    switch (e.code) {
-      case 'NOT_INITIALIZED':
-        break; // initialize() 미호출
-      case 'USER_ID_NOT_SET':
-        break; // setUserId() 미호출
-      case 'INITIALIZE_TIMEOUT':
-        break; // 초기화 대기 타임아웃
-      case 'NETWORK_ERROR':
-        break; // 네트워크 연결 실패
-      default:
-        break; // 기타 오류
-    }
-  },
-});
-```
----
-## SDK 동작
-아래 동작은 모두 `VisualReward.open`으로 열린 웹뷰 화면에만 적용됩니다. 호스트 앱의 다른 화면이나 웹뷰에는 영향을 주지 않습니다.
-### 가로 모드 차단
-웹뷰 화면은 항상 세로 모드로 고정됩니다. 화면을 닫으면 기존 방향 설정이 자동으로 복원됩니다. (Android는 Activity `requestedOrientation`, iOS는 iOS 16+ 공개 API `requestGeometryUpdate`로 처리하며, iOS에서는 호스트 앱이 지원 방향을 세로로 제한하지 않은 경우 회전 요청이 best-effort로 동작합니다.)
-### 영상 광고 자동재생
-사용자 제스처 없이 미디어(영상 광고)가 자동으로 인라인 재생됩니다.
-- `javaScriptEnabled` — JavaScript 활성화
-- `domStorageEnabled` — DOM Storage 활성화
-- `mediaPlaybackRequiresUserAction={false}` — 제스처 없이 자동재생 허용
-- `allowsInlineMediaPlayback` (iOS) — 전체화면 강제 전환 없이 인라인 재생
-### ATT 권한 요청 (iOS)
-웹뷰 로드 전 네이티브 `ATTrackingManager`로 `NSUserTrackingUsageDescription`이 설정된 경우 ATT 권한을 자동으로 요청합니다. 이미 권한이 결정된 경우 팝업 없이 즉시 진행됩니다. `NSUserTrackingUsageDescription`이 없으면 요청을 스킵하고 바로 로드합니다.
-### 스와이프 백 (iOS)
-웹뷰 내 이전 페이지로 돌아가는 스와이프 백 제스처가 기본으로 활성화되어 있습니다(`allowsBackForwardNavigationGestures`). `swipeBackEnabled` JS 핸들러로 웹에서 활성화 여부를 제어할 수 있습니다.
-### Mixed Content 허용 (Android)
-HTTPS 페이지 내 HTTP 리소스 로드를 허용합니다(`mixedContentMode="always"`). Android 5.0 이상에서 기본 차단되는 mixed content를 광고 크리에이티브가 정상적으로 로드될 수 있도록 허용합니다.
-### 서드파티 쿠키 허용
-WebView 내부 광고의 쿠키 기반 타게팅·빈도제한·전환측정을 위해 서드파티 쿠키를 허용합니다(`thirdPartyCookiesEnabled` / `sharedCookiesEnabled`). 다른 플랫폼과 동일합니다.
-### 서브프레임(iframe) 링크 처리 (iOS)
-메인 프레임 네비게이션은 항상 도메인 정책으로 평가하고, 서브프레임(iframe)은 사용자가 직접 누른 링크(`navigationType === 'click'`)가 외부 대상일 때만 가로챕니다. 광고 iframe의 자체 네비게이션이 끊기지 않도록 하기 위함이며, Swift SDK와 동일합니다.
-### 스크롤 바운스 비활성화
-웹뷰 스크롤이 콘텐츠 끝에 도달해도 바운스 효과가 발생하지 않습니다(`bounces={false}`).
-### 백그라운드 미디어 중단
-앱이 백그라운드로 진입하면(`AppState` 감지) JS로 페이지 내 모든 `<video>`, `<audio>` 요소에 `.pause()`를 호출합니다.
-### URL 처리
-| 케이스                                              | 동작                                  |
-| --------------------------------------------------- | ------------------------------------- |
-| 허용 도메인 링크                                    | 내부 웹뷰에서 로드                    |
-| 비허용 도메인 링크                                  | 외부 브라우저로 오픈                  |
-| `window.open` / `target="_blank"`                   | 도메인 정책에 따라 내부/외부 분기     |
-| `intent://` (Android)                               | 네이티브에서 `Intent.parseUri` 로 앱 실행, 미설치 시 `browser_fallback_url` → Play Store(`market://`) 폴백 |
-| `market://` (Android)                               | 스토어 앱으로 오픈                    |
-| `mailto:`, `tel:`, `itms-apps:` 등 비 http(s) 스킴 | 외부로 전달                           |
-> 허용 도메인은 `initialize()` 시 서버에서 수신한 `allowedDomains` 설정이 적용됩니다.
----
-## JS Interface
-웹에서 네이티브 기능을 호출하는 인터페이스입니다.
-### 호출 형식
-SDK는 웹뷰 로드 전 폴리필을 주입하여 Android 방식과 iOS 방식을 모두 지원합니다.
-**Android 방식**
-```js
-// 파라미터 없음
-window.nativeBridge.getAppVersion();
-// 파라미터 있음 (JSON 문자열)
-window.nativeBridge.pushUrl(JSON.stringify({ url: 'https://example.com', replace: false }));
-// openExternalBrowser: url 직접 전달
-window.nativeBridge.openExternalBrowser('https://example.com');
-```
-**iOS 방식**
-```js
-// 파라미터 없음
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({ fncName: 'getAppVersion' })
-);
-// 파라미터 있음
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({ fncName: 'pushUrl', params: { url: 'https://example.com', replace: false } })
-);
-```
-콜백은 `window.nativeCallback` 객체로 수신합니다.
-```js
-window.nativeCallback.fncName = (result) => { ... };
-```
----
-### getAppVersion()
-앱 버전을 가져옵니다.
-```js
-// Android
-window.nativeBridge.getAppVersion();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'getAppVersion' }));
-window.nativeCallback.getAppVersion = (version) => {
-  console.log(version); // "1.0.0"
-};
-```
----
-### getADID() — Android Only
-디바이스 광고 식별자(Advertising ID)를 가져옵니다. iOS는 빈 문자열을 반환합니다.
-```js
-// Android
-window.nativeBridge.getADID();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'getADID' }));
-window.nativeCallback.getADID = (adId) => {
-  console.log(adId); // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
-};
-```
----
-### getIDFA() — iOS Only
-디바이스 광고 식별자(IDFA)를 가져옵니다. ATT 권한 허용 시 IDFA 반환, 미허용 시 빈 문자열을 반환합니다. Android는 빈 문자열을 반환합니다.
-```js
-// Android
-window.nativeBridge.getIDFA();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'getIDFA' }));
-window.nativeCallback.getIDFA = (idfa) => {
-  console.log(idfa); // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
-};
-```
----
-### getIDFV() — iOS Only
-디바이스 벤더 식별자(IDFV)를 가져옵니다. Android는 빈 문자열을 반환합니다.
-```js
-// Android
-window.nativeBridge.getIDFV();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'getIDFV' }));
-window.nativeCallback.getIDFV = (idfv) => {
-  console.log(idfv); // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
-};
-```
----
-### getDeviceInfo()
-기기 정보를 JSON 문자열로 가져옵니다.
-```js
-// Android
-window.nativeBridge.getDeviceInfo();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'getDeviceInfo' }));
-window.nativeCallback.getDeviceInfo = (deviceInfo) => {
-  const info = JSON.parse(deviceInfo);
-  // Android: { network: "wifi", model: "SM-S911N", manufacturer: "Samsung", osVersion: "14" }
-  // iOS:     { network: "wifi", model: "iPhone16,1", manufacturer: "Apple", osVersion: "17.2" }
-};
-```
-| 필드           | 타입     | 값                                        |
-| -------------- | -------- | ----------------------------------------- |
-| `network`      | `string` | `"wifi"` \| `"mobile"`. 연결 없으면 키 생략 |
-| `model`        | `string` | 기기 모델명                               |
-| `manufacturer` | `string` | 제조사                                    |
-| `osVersion`    | `string` | OS 버전                                   |
----
-### registerBackKeyListener() — Android Only
-디바이스 Back Key 이벤트 권한을 얻습니다. 등록 후 Back Key가 눌리면 `onBackKeyPress`가 호출됩니다. iOS는 항상 `"0"`을 반환합니다.
-```js
-// Android
-window.nativeBridge.registerBackKeyListener();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'registerBackKeyListener' }));
-window.nativeCallback.registerBackKeyListener = (success) => {
-  // "1": 권한 획득 성공
-  // "0": 권한 획득 실패 (또는 iOS)
-};
-window.nativeCallback.onBackKeyPress = () => {
-  // Back Key 눌렸을 때 처리
-};
-```
----
-### unregisterBackKeyListener() — Android Only
-Back Key 이벤트 권한을 해제합니다. 호출 후 Back Key는 웹뷰 히스토리 뒤로가기 또는 화면 종료로 동작합니다. iOS는 항상 no-op입니다.
-```js
-// Android
-window.nativeBridge.unregisterBackKeyListener();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'unregisterBackKeyListener' }));
-```
----
-### swipeBackEnabled() — iOS Only
-iOS 스와이프 백 기능 활성화 여부를 설정합니다.
-```js
-// Android
-window.nativeBridge.swipeBackEnabled(JSON.stringify({ enabled: false }));
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({ fncName: 'swipeBackEnabled', params: { enabled: false } })
-);
-```
----
-### finish()
-현재 웹뷰를 종료합니다.
-```js
-// Android
-window.nativeBridge.finish();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(JSON.stringify({ fncName: 'finish' }));
-```
----
-### openTrackingSettings()
-앱 설정 화면을 엽니다. 광고 추적 권한을 변경할 수 있도록 안내할 때 사용합니다.
-```js
-// Android
-window.nativeBridge.openTrackingSettings();
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({ fncName: 'openTrackingSettings' })
-);
-```
----
-### openExternalBrowser()
-외부 브라우저를 엽니다.
-```js
-// Android
-window.nativeBridge.openExternalBrowser('https://example.com');
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({ fncName: 'openExternalBrowser', params: { url: 'https://example.com' } })
-);
-```
----
-### pushUrl()
-현재 웹뷰에서 URL을 변경합니다.
-```js
-// Android
-window.nativeBridge.pushUrl(JSON.stringify({ url: 'https://example.com', replace: false }));
-// iOS
-window.webkit.messageHandlers.nativeBridge.postMessage(
-  JSON.stringify({
-    fncName: 'pushUrl',
-    params: { url: 'https://example.com', replace: false }
-  })
-);
-```
-| 파라미터  | 타입      | 설명                                                      |
-| --------- | --------- | --------------------------------------------------------- |
-| `url`     | `string`  | 이동할 URL                                                |
-| `replace` | `boolean` | `true`: history 교체, `false`: history 스택에 추가 (기본) |
----
+- `open()`은 예외를 throw하지 않고 `onError` 콜백으로 에러를 전달합니다. 콜백에서 에러 타입을 분기합니다.
+    ```tsx
+    import { VisualReward, VisualRewardError } from '@tenqube/visual-reward-react-native';
+    await VisualReward.open({
+      serviceName: 'reward_home',
+      locale: 'ko',
+      extra: undefined,
+      onClose: () => { /* 웹뷰 닫힘 */ },
+      onError: (e: VisualRewardError) => {
+        switch (e.code) {
+          case 'NOT_INITIALIZED':
+            break; // initialize() 미호출
+          case 'USER_ID_NOT_SET':
+            break; // setUserId() 미호출
+          case 'INITIALIZE_TIMEOUT':
+            break; // 초기화 대기 타임아웃
+          case 'NETWORK_ERROR':
+            break; // 네트워크 연결 실패
+          default:
+            break; // 기타 오류
+        }
+      },
+    });
+    ```

package/android/src/main/AndroidManifest.xml CHANGED Viewed

@@ -1,5 +1,10 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.tenqube.visualreward">
+    <!-- WebView 원격 URL 로드 / config HTTP fetch 용. -->
+    <uses-permission android:name="android.permission.INTERNET" />
     <!-- 네트워크 타입(wifi/mobile) 조회용 — @react-native-community/netinfo 제거에 따라 직접 선언. -->
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- 광고 ID(AAID) 조회용. play-services-ads-identifier 가 병합으로도 가져오지만,
+         Kotlin 네이티브 SDK 와 동일하게 명시 선언한다. -->
+    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
 </manifest>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tenqube/visual-reward-react-native",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Tenqube Visual Reward SDK for React Native",
   "main": "index.ts",
   "types": "index.ts",

package/src/ConfigCache.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { RemoteConfig } from './types';
+import type { AsyncStorageLike, RemoteConfig } from './types';
 const TTL_MS = 3600 * 1000;
 const KEY_PREFIX = 'visual_reward_config_';
@@ -10,12 +10,6 @@ interface CacheEntry {
 let _storage: AsyncStorageLike | null = null;
-export interface AsyncStorageLike {
-  getItem(key: string): Promise<string | null>;
-  setItem(key: string, value: string): Promise<void>;
-  removeItem(key: string): Promise<void>;
-}
 export function setStorage(storage: AsyncStorageLike): void {
   _storage = storage;
 }

package/src/VisualReward.ts CHANGED Viewed

@@ -5,7 +5,7 @@ import type {
   VisualRewardInitializeOptions,
   VisualRewardOpenOptions,
 } from './types';
-import { readCache, writeCache, setStorage, AsyncStorageLike } from './ConfigCache';
+import { readCache, writeCache, setStorage } from './ConfigCache';
 const OPEN_TIMEOUT_MS = 5_000;
 // config fetch 연결/읽기 타임아웃 (다른 플랫폼과 동일: 10초).
@@ -39,10 +39,13 @@ export class VisualReward {
   static initialize(options: VisualRewardInitializeOptions): void {
     const {
       appKey,
+      storage,
       timeoutMs = 5_000,
       onSuccess,
       onFailure,
     } = options;
+    // config 캐싱용 AsyncStorage 주입 (선택). fetchConfig가 캐시를 읽기 전에 설정한다.
+    if (storage) setStorage(storage);
     VisualReward._initGeneration++;
     const generation = VisualReward._initGeneration;
     VisualReward._openTimeoutMs = timeoutMs;
@@ -65,11 +68,6 @@ export class VisualReward {
     VisualReward._debugEnabled = enabled;
   }
-  /** AsyncStorage 구현체를 주입합니다. initialize() 전에 호출합니다. */
-  static setStorage(storage: AsyncStorageLike): void {
-    setStorage(storage);
-  }
   /** 사용자 식별자를 설정합니다. open() 전에 반드시 호출합니다. */
   static setUserId(userId: string): void {
     VisualReward._userId = userId;

package/src/types.ts CHANGED Viewed

@@ -18,9 +18,21 @@ export class VisualRewardError extends Error {
   }
 }
+/** AsyncStorage 호환 인터페이스 (config 캐시 저장소). */
+export interface AsyncStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
 export interface VisualRewardInitializeOptions {
   /** 앱 식별 키 */
   appKey: string;
+  /**
+   * config 캐싱용 AsyncStorage 구현체 (선택).
+   * 주입하지 않으면 매번 네트워크에서 config를 fetch합니다.
+   */
+  storage?: AsyncStorageLike;
   /** initialize() 완료 대기 타임아웃 (ms). 기본값 `5000`. */
   timeoutMs?: number;
   /** 초기화 성공 콜백 (선택). */