@tenqube/visual-reward-react-native 1.1.3

package/README.md

@@ -0,0 +1,690 @@
+# React Native
+
+React Native WebView 기반 리워드 광고 SDK입니다.
+
+---
+
+## 요구사항
+
+- React Native 0.72+
+- iOS 13.0+
+- Android minSdk 21
+
+---
+
+## 설치
+
+### 방법 1) npm (권장)
+
+```sh
+npm install @tenqube/visual-reward-react-native
+```
+
+SDK가 의존하는 패키지(`react-native-webview`, `react-native-device-info`, `react-native-idfa-aaid`, `react-native-orientation-locker`, `react-native-permissions`, `@react-native-community/netinfo`)는 함께 설치됩니다. 아래 **peer dependency**만 호스트 앱에 직접 설치합니다.
+
+```sh
+npm install react-native-safe-area-context
+```
+
+### 방법 2) 수동 설치 (GitHub Release)
+
+npm을 쓰지 않는 경우, [GitHub Release](https://github.com/tenqube/visual-reward-sdk-react-native/releases)에서 `visual-reward-react-native-<버전>.zip`을 내려받아 압축을 풀고 프로젝트 내 원하는 위치에 복사합니다. (zip에는 `android/`, `ios/` 네이티브 모듈이 포함되어 있습니다.) 그런 다음 `package.json`에 `file:` 경로로 추가합니다.
+
+```json
+"dependencies": {
+  "@tenqube/visual-reward-react-native": "file:./visual-reward-react-native",
+  "react-native-safe-area-context": ">=4.0.0"
+}
+```
+
+```sh
+npm install
+```
+
+### 공통) iOS pod install
+
+두 방법 모두 iOS는 추가로 pod install을 실행합니다.
+
+```sh
+cd ios && pod install
+```
+
+> 이 패키지는 GMA registerWebView / AdPopcorn 브릿지 등록을 위한 **네이티브 모듈**(iOS Swift / Android Kotlin)을 포함하며, React Native 오토링크로 자동 연결됩니다. (iOS는 `pod install`, Android는 Gradle sync 시 자동 반영)
+
+### VisualRewardContainer 루트 추가
+
+앱의 루트 컴포넌트(예: `App.tsx`)에 `<VisualRewardContainer />`을 추가합니다.
+
+```tsx
+import { VisualRewardContainer } from '@tenqube/visual-reward-react-native';
+
+export default function App() {
+  return (
+    <>
+      <YourNavigator />
+      <VisualRewardContainer />
+    </>
+  );
+}
+```
+
+---
+
+## 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>;
+}
+```
+
+---
+
+## AdMob / Ad Manager WebView 광고 연동 (선택)
+
+WebView 내부 광고(AdSense / Google Publisher Tag / IMA HTML5)의 수익화·측정 신호를 개선하는 WebView API for Ads를 지원합니다. AdMob과 Google Ad Manager(GAM)는 동일한 Google Mobile Ads SDK를 사용하므로 양쪽 모두 동작합니다.
+
+이 SDK는 호스트 앱에 **GMA SDK가 있을 때만** 네이티브 모듈에서 리플렉션으로 `registerWebView`를 자동 호출합니다. AdPopcorn SSP 오퍼월을 쓰는 경우에는 **AdPopcorn 네이티브 브릿지(`AdPopcornSSPJsBridge`)도 자동 주입**합니다(오퍼월의 웹 배너 SDK가 네이티브 컨텍스트를 필요로 하므로 **실제 네이티브 브릿지**를 연결 — 순수 JS shim 으로는 불가). SDK가 하는 일은 이 연결뿐이며, **SDK 의존성·App ID·초기화는 모두 호스트 앱에서 설정**해야 합니다.
+
+> react-native-webview는 "로드 전 네이티브 인터페이스 주입" 훅이 없어, SDK는 실제 오퍼월 URL 로드 전에 `about:blank`를 먼저 띄워 브릿지를 주입한 뒤 URL을 로드합니다. 덕분에 오퍼월은 한 번만 로드되고 첫 페이지부터 브릿지가 바인딩됩니다(리로드 불필요).
+
+### 1. 의존성 (호스트 앱)
+
+```sh
+# 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 와 동일 버전대.
+
+```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")
+```
+
+> 이 SDK는 위 패키지에 **컴파일 의존하지 않습니다**(리플렉션·뷰탐색만 사용). 호스트가 링크하면 동작하고, 없으면 무시됩니다. `react-native-google-mobile-ads`는 GMA 네이티브 심볼을 앱에 링크하는 용도이며, 등록 자체는 이 SDK가 직접 수행합니다. AdPopcorn 은 `react-native-adpopcorn-ssp` 가 번들한 **네이티브 SSP SDK** 를 SDK 가 리플렉션으로 웹뷰에 연결합니다.
+
+### 2. App ID / 초기화 — 아래 두 경우 중 해당하는 쪽으로 설정
+
+- **WebView 신호 전용**: 이 앱으로 **자체 광고를 서빙하지 않고** WebView 안 광고 신호만 쓰는 경우
+- **자체 광고 병행**: 호스트 앱이 GMA로 자기 앱에 **자체 인앱 광고(배너·전면 등)도 함께** 서빙하는 경우
+
+| 경우 | 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를 리워드 웹뷰로 간주합니다.
+
+---
+
+## 권한
+
+### Android
+
+`AndroidManifest.xml`에 광고 ID 접근 권한을 추가합니다.
+
+```xml
+<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
+```
+
+### iOS
+
+IDFA 조회(`getIDFA`)를 사용하려면 `Info.plist`에 ATT 사용 목적 문자열을 추가해야 합니다.
+
+```xml
+<key>NSUserTrackingUsageDescription</key>
+<string>맞춤형 광고 제공을 위해 기기 식별자를 사용합니다.</string>
+```
+
+> ATT 권한 요청은 SDK가 웹뷰 로드 전 자동으로 처리합니다. 이미 권한이 결정된 경우 팝업 없이 즉시 진행됩니다. `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';
+
+VisualReward.setDebugEnabled(__DEV__);
+```
+
+---
+
+### 초기화
+
+`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) => { /* 초기화 실패 */ },
+  });
+}, []);
+```
+
+### initialize 파라미터
+
+| 파라미터        | 타입                        | 필수 | 기본값         | 설명                                        |
+| --------------- | --------------------------- | ---- | -------------- | ------------------------------------------- |
+| `appKey`        | `string`                    | ✅   |                | 앱 식별 키                                  |
+| `timeoutMs`     | `number`                    |      | `5000`         | 초기화 완료 대기 시간 (ms). 초과 시 `INITIALIZE_TIMEOUT` 에러 발생 |
+| `onSuccess`     | `() => void`                |      | `undefined`    | 초기화 성공 콜백 (선택)                     |
+| `onFailure`     | `(error: VisualRewardError) => void` |      | `undefined`    | 초기화 실패 콜백 (선택)                     |
+
+---
+
+### 사용자 설정
+
+로그인 후 또는 사용자가 변경될 때 호출합니다. `open()` 전에 반드시 호출해야 합니다.
+
+```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: () => { /* 웹뷰 닫힘 */ },
+});
+```
+
+### open 파라미터
+
+| 파라미터      | 타입                  | 필수 | 기본값      | 설명                                 |
+| ------------- | --------------------- | ---- | ----------- | ------------------------------------ |
+| `serviceName` | `string`              | ✅   |             | 서비스 이름                          |
+| `locale`      | `string \| undefined` |      | `'ko'` | 언어 코드 |
+| `extra`       | `string \| undefined` |      | `undefined` | 추가 query parameter (선택)          |
+| `onClose`     | `() => void`          |      | `undefined` | 웹뷰가 닫힐 때 호출되는 콜백 (선택) |
+| `onError`     | `(error: VisualRewardError) => void` |      | `undefined` | 열기 실패 콜백 (선택). `open` 은 예외를 던지지 않음 |
+
+---
+
+## 에러 처리
+
+### 에러 타입
+
+`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()` 호출    |
+
+### 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; // 응답 파싱 실패
+      }
+    }
+  },
+});
+```
+
+### 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`으로 열린 웹뷰 화면에만 적용됩니다. 호스트 앱의 다른 화면이나 웹뷰에는 영향을 주지 않습니다.
+
+### 가로 모드 차단
+
+웹뷰 화면은 항상 세로 모드로 고정됩니다(`react-native-orientation-locker`). 화면을 닫으면 기존 방향 설정이 자동으로 복원됩니다.
+
+### 영상 광고 자동재생
+
+사용자 제스처 없이 미디어(영상 광고)가 자동으로 인라인 재생됩니다.
+
+- `javaScriptEnabled` — JavaScript 활성화
+- `domStorageEnabled` — DOM Storage 활성화
+- `mediaPlaybackRequiresUserAction={false}` — 제스처 없이 자동재생 허용
+- `allowsInlineMediaPlayback` (iOS) — 전체화면 강제 전환 없이 인라인 재생
+
+### ATT 권한 요청 (iOS)
+
+웹뷰 로드 전 `react-native-permissions`를 통해 `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 스택에 추가 (기본) |
+
+---