> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 레퍼런스

> React Native SDK의 전체 API 레퍼런스입니다.

## Adrop

Adrop SDK를 초기화하고 전역 설정을 관리하는 클래스입니다.

### initialize

```typescript theme={null}
static initialize(
  production: boolean,
  targetCountries?: string[],
  useInAppBrowser?: boolean
): void
```

Adrop SDK를 초기화합니다.

**Parameters:**

* `production` (boolean): 프로덕션 모드 여부 (true: 프로덕션, false: 개발)
* `targetCountries` (string\[], optional): 타겟 국가 코드 배열 (기본값: \[])
* `useInAppBrowser` (boolean, optional): 인앱 브라우저 사용 여부 (기본값: false)

**Example:**

```typescript theme={null}
import { Adrop } from 'adrop-ads-react-native'

Adrop.initialize(true, ['KR', 'US'], false)
```

### setUID

```typescript theme={null}
static setUID(uid: string): void
```

사용자 고유 식별자를 설정합니다.

**Parameters:**

* `uid` (string): 사용자 고유 식별자

**Example:**

```typescript theme={null}
Adrop.setUID('user123')
```

### setTheme

```typescript theme={null}
static setTheme(theme: AdropTheme): void
```

앱의 테마를 설정합니다.

**Parameters:**

* `theme` (AdropTheme): 테마 값 ('light', 'dark', 'auto')

**Example:**

```typescript theme={null}
import { Adrop, AdropTheme } from 'adrop-ads-react-native'

Adrop.setTheme(AdropTheme.dark)
```

### registerWebView

```typescript theme={null}
static registerWebView(viewTag: number): Promise<void>
```

백필 광고 지원을 위해 네이티브 WebView를 등록합니다. WebView가 마운트된 후 호출하세요.

**Parameters:**

* `viewTag` (number): WebView를 감싸는 `View`에서 `findNodeHandle()`로 얻은 네이티브 뷰 태그

**Example:**

```typescript theme={null}
import { useEffect, useRef } from 'react'
import { findNodeHandle, View } from 'react-native'
import { Adrop } from 'adrop-ads-react-native'

const containerRef = useRef<View>(null)

useEffect(() => {
  if (containerRef.current) {
    const tag = findNodeHandle(containerRef.current)
    if (tag != null) {
      Adrop.registerWebView(tag)
    }
  }
}, [])
```

<Warning>
  `adrop-ads-backfill` 모듈이 필요합니다. 미설치 시 이 호출은 무시됩니다.
</Warning>

***

## AdropTheme

앱의 테마를 지정하는 상수 객체입니다.

```typescript theme={null}
const AdropTheme = {
  light: 'light',
  dark: 'dark',
  auto: 'auto',
} as const

type AdropTheme = (typeof AdropTheme)[keyof typeof AdropTheme]
```

**Values:**

* `light`: 라이트 테마
* `dark`: 다크 테마
* `auto`: 시스템 설정에 따름

***

## BrowserTarget

광고 목적지 URL을 여는 방식을 지정하는 enum입니다.

```typescript theme={null}
enum BrowserTarget {
  EXTERNAL = 0,
  INTERNAL = 1,
}
```

**값:**

* `EXTERNAL`: 외부 브라우저에서 URL 열기 (기본값)
* `INTERNAL`: 인앱 브라우저에서 URL 열기

***

## AdropErrorCode

광고 로드 및 표시 시 발생할 수 있는 에러 코드입니다.

```typescript theme={null}
enum AdropErrorCode {
  network = 'ERROR_CODE_NETWORK',
  internal = 'ERROR_CODE_INTERNAL',
  initialize = 'ERROR_CODE_INITIALIZE',
  invalidUnit = 'ERROR_CODE_INVALID_UNIT',
  notTargetCountry = 'ERROR_CODE_NOT_TARGET_COUNTRY',
  inactive = 'ERROR_CODE_AD_INACTIVE',
  adNoFill = 'ERROR_CODE_AD_NO_FILL',
  adDuplicated = 'ERROR_CODE_AD_LOAD_DUPLICATED',
  adLoading = 'ERROR_CODE_AD_LOADING',
  adEmpty = 'ERROR_CODE_AD_EMPTY',
  adShown = 'ERROR_CODE_AD_SHOWN',
  adHideForToday = 'ERROR_CODE_AD_HIDE_FOR_TODAY',
  adLandscapeUnsupported = 'ERROR_CODE_LANDSCAPE_UNSUPPORTED',
  backfillNoFill = 'ERROR_CODE_AD_BACKFILL_NO_FILL',
  undefined = 'UNDEFINED',
}
```

**Error Codes:**

* `network`: 네트워크 오류
* `internal`: 내부 오류
* `initialize`: SDK 초기화 오류
* `invalidUnit`: 유효하지 않은 광고 유닛
* `notTargetCountry`: 타겟 국가가 아님
* `inactive`: 비활성화된 광고
* `adNoFill`: 광고 없음
* `adDuplicated`: 중복된 광고 로드 요청
* `adLoading`: 광고 로딩 중
* `adEmpty`: 광고가 비어있음
* `adShown`: 이미 표시된 광고
* `adHideForToday`: 오늘 하루 숨김 처리된 광고
* `adLandscapeUnsupported`: 가로 모드 미지원
* `backfillNoFill`: 백필 광고 없음
* `undefined`: 정의되지 않은 오류

***

## AdropAdChoicesPosition

백필 네이티브 광고의 AdChoices 마크 표시 위치를 설정하는 enum입니다.

### Definition

```typescript theme={null}
enum AdropAdChoicesPosition {
  topLeft = 0,
  topRight = 1,
  bottomLeft = 2,
  bottomRight = 3,
}
```

### Values

| Value         | Integer | Description |
| ------------- | ------- | ----------- |
| `topLeft`     | 0       | 좌측 상단       |
| `topRight`    | 1       | 우측 상단 (기본값) |
| `bottomLeft`  | 2       | 좌측 하단       |
| `bottomRight` | 3       | 우측 하단       |

### Usage Example

```typescript theme={null}
import { AdropNativeAd, AdropAdChoicesPosition } from 'adrop-ads-react-native'

const nativeAd = new AdropNativeAd(
  'YOUR_UNIT_ID',
  false,
  AdropAdChoicesPosition.bottomRight
)
```

***

## AdropBanner

배너 광고를 표시하는 React 컴포넌트입니다.

### Props

```typescript theme={null}
type AdropBannerProp = {
  style: { height: number; width: number | string }
  unitId: string
  useCustomClick?: boolean
  adSize?: { width: number; height: number } | null
  autoLoad?: boolean
  onAdReceived?: (unitId: string, metadata?: AdropBannerMetadata) => void
  onAdImpression?: (unitId: string, metadata?: AdropBannerMetadata) => void
  onAdClicked?: (unitId: string, metadata?: AdropBannerMetadata) => void
  onAdFailedToReceive?: (unitId: string, errorCode?: any) => void
  onAdVideoStart?: (unitId: string) => void
  onAdVideoEnd?: (unitId: string) => void
}
```

**Props:**

* `style` (object, required): 배너 스타일 (높이와 너비 포함)
* `unitId` (string, required): 광고 유닛 ID
* `useCustomClick` (boolean, optional): 커스텀 클릭 처리 여부 (기본값: false)
* `adSize` (object, optional): 광고 크기 설정
* `autoLoad` (boolean, optional): 자동 로드 여부 (기본값: true)
* `onAdReceived` (function, optional): 광고 수신 시 호출
* `onAdImpression` (function, optional): 광고 노출 시 호출
* `onAdClicked` (function, optional): 광고 클릭 시 호출
* `onAdFailedToReceive` (function, optional): 광고 수신 실패 시 호출
* `onAdVideoStart` (function, optional): 동영상 광고 재생 시작 시 호출
* `onAdVideoEnd` (function, optional): 동영상 광고 재생 종료 시 호출

### Methods

**load()**

```typescript theme={null}
load(): void
```

광고를 로드합니다. (ref를 통해 호출)

### AdropBannerMetadata

```typescript theme={null}
type AdropBannerMetadata = {
  creativeId: string
  txId: string
  campaignId: string
  destinationURL: string
  browserTarget: BrowserTarget
}
```

**Example:**

```typescript theme={null}
import { AdropBanner } from 'adrop-ads-react-native'

<AdropBanner
  style={{ width: 320, height: 50 }}
  unitId="PUBLIC_TEST_UNIT_ID_320_50"
  onAdReceived={(unitId, metadata) => console.log('Ad received', metadata)}
  onAdFailedToReceive={(unitId, errorCode) => console.log('Ad failed', errorCode)}
/>
```

***

## AdropNativeAd

네이티브 광고를 관리하는 클래스입니다.

### Constructor

```typescript theme={null}
new AdropNativeAd(
  unitId: string,
  useCustomClick?: boolean,
  preferredAdChoicesPosition?: AdropAdChoicesPosition
)
```

**Parameters:**

| Parameter                    | Type                     | Description                                                             |
| ---------------------------- | ------------------------ | ----------------------------------------------------------------------- |
| `unitId`                     | `string`                 | 광고 유닛 ID                                                                |
| `useCustomClick`             | `boolean`                | 커스텀 클릭 처리 여부 (기본값: `false`)                                             |
| `preferredAdChoicesPosition` | `AdropAdChoicesPosition` | 백필 네이티브 광고의 AdChoices 마크 표시 위치 (기본값: `AdropAdChoicesPosition.topRight`) |

### Properties

**isLoaded** (readonly)

```typescript theme={null}
get isLoaded(): boolean
```

광고 로드 여부를 반환합니다.

**unitId** (readonly)

```typescript theme={null}
get unitId(): string
```

광고 유닛 ID를 반환합니다.

**requestId** (readonly, deprecated)

```typescript theme={null}
get requestId(): string // deprecated - 항상 '' 반환
```

*Deprecated.* 이 속성은 항상 빈 문자열을 반환하며 향후 버전에서 제거됩니다.

**creativeId** (readonly)

```typescript theme={null}
get creativeId(): string
```

크리에이티브 ID를 반환합니다.

**txId** (readonly)

```typescript theme={null}
get txId(): string
```

트랜잭션 ID를 반환합니다.

**campaignId** (readonly)

```typescript theme={null}
get campaignId(): string
```

캠페인 ID를 반환합니다.

**useCustomClick** (readonly)

```typescript theme={null}
get useCustomClick(): boolean
```

커스텀 클릭 처리 여부를 반환합니다.

**isBackfilled** (readonly)

```typescript theme={null}
get isBackfilled(): boolean
```

백필 광고 여부를 반환합니다.

**isVideoAd** (readonly)

```typescript theme={null}
get isVideoAd(): boolean
```

비디오 광고 여부를 반환합니다.

**browserTarget** (readonly)

```typescript theme={null}
get browserTarget(): BrowserTarget
```

브라우저 타겟 설정을 반환합니다.

**properties** (readonly)

```typescript theme={null}
get properties(): AdropNativeProperties
```

광고 속성을 반환합니다.

**listener**

```typescript theme={null}
listener?: AdropNativeAdListener
```

광고 이벤트 리스너를 설정합니다.

### Methods

**load()**

```typescript theme={null}
load(): void
```

광고를 로드합니다.

**destroy()**

```typescript theme={null}
destroy(): void
```

광고 인스턴스를 해제합니다.

### AdropNativeProperties

```typescript theme={null}
type AdropNativeProperties = {
  icon?: string
  cover?: string
  headline?: string
  body?: string
  creative?: string
  asset?: string
  destinationURL?: string
  advertiserURL?: string
  accountTag?: string
  creativeTag?: string
  advertiser?: string
  callToAction?: string
  profile?: AdropNativeProfile
  extra?: Record<string, string>
  isBackfilled?: boolean
}
```

### AdropNativeProfile

```typescript theme={null}
type AdropNativeProfile = {
  displayName: string
  displayLogo: string
}
```

### AdropNativeAdListener

```typescript theme={null}
interface AdropNativeAdListener {
  onAdReceived?: (ad: AdropNativeAd) => void
  onAdClicked?: (ad: AdropNativeAd) => void
  onAdImpression?: (ad: AdropNativeAd) => void
  onAdFailedToReceive?: (ad: AdropNativeAd, errorCode?: any) => void
  onAdVideoStart?: (ad: AdropNativeAd) => void
  onAdVideoEnd?: (ad: AdropNativeAd) => void
}
```

**Example:**

```typescript theme={null}
import { AdropNativeAd } from 'adrop-ads-react-native'

const nativeAd = new AdropNativeAd('YOUR_UNIT_ID')

nativeAd.listener = {
  onAdReceived: (ad) => console.log('Ad received', ad.properties),
  onAdFailedToReceive: (ad, errorCode) => console.log('Ad failed', errorCode),
}

nativeAd.load()
```

***

## AdropNativeAdView

네이티브 광고를 표시하는 컨테이너 컴포넌트입니다.

### Props

```typescript theme={null}
type Props = ViewProps & {
  nativeAd?: AdropNativeAd
}
```

**Props:**

* `nativeAd` (AdropNativeAd, optional): 네이티브 광고 인스턴스
* ...ViewProps: React Native View의 모든 props

**Example:**

```typescript theme={null}
import { AdropNativeAdView } from 'adrop-ads-react-native'

<AdropNativeAdView nativeAd={nativeAd}>
  {/* 네이티브 광고 뷰들 */}
</AdropNativeAdView>
```

***

## 네이티브 광고 뷰 컴포넌트

네이티브 광고의 각 요소를 표시하는 컴포넌트들입니다. 모든 컴포넌트는 `AdropNativeAdView` 내부에서 사용해야 합니다.

### AdropIconView

광고 아이콘을 표시합니다.

```typescript theme={null}
interface IconViewProps extends Omit<ImageProps, 'source'> {
  source?: ImageSourcePropType | undefined
}
```

**Example:**

```typescript theme={null}
import { AdropIconView } from 'adrop-ads-react-native'

<AdropIconView style={{ width: 50, height: 50 }} />
```

### AdropHeadLineView

광고 헤드라인을 표시합니다.

```typescript theme={null}
const AdropHeadLineView: React.FC<TextProps>
```

**Example:**

```typescript theme={null}
import { AdropHeadLineView } from 'adrop-ads-react-native'

<AdropHeadLineView style={{ fontSize: 18, fontWeight: 'bold' }} />
```

### AdropBodyView

광고 본문을 표시합니다.

```typescript theme={null}
const AdropBodyView: React.FC<TextProps>
```

**Example:**

```typescript theme={null}
import { AdropBodyView } from 'adrop-ads-react-native'

<AdropBodyView style={{ fontSize: 14 }} />
```

### AdropMediaView

광고 미디어(이미지/비디오)를 표시합니다.

```typescript theme={null}
const AdropMediaView: React.FC<ViewProps>
```

**Example:**

```typescript theme={null}
import { AdropMediaView } from 'adrop-ads-react-native'

<AdropMediaView style={{ width: '100%', height: 200 }} />
```

### AdropCallToActionView

광고 CTA(Call To Action) 버튼을 표시합니다.

```typescript theme={null}
const AdropCallToActionView: React.FC<TextProps>
```

**Example:**

```typescript theme={null}
import { AdropCallToActionView } from 'adrop-ads-react-native'

<AdropCallToActionView
  style={{
    backgroundColor: '#007AFF',
    color: 'white',
    padding: 10
  }}
/>
```

### AdropAdvertiserView

광고주 정보를 표시합니다.

```typescript theme={null}
const AdropAdvertiserView: React.FC<TextProps>
```

**Example:**

```typescript theme={null}
import { AdropAdvertiserView } from 'adrop-ads-react-native'

<AdropAdvertiserView style={{ fontSize: 12, color: 'gray' }} />
```

### AdropProfileLogoView

프로필 로고를 표시합니다.

```typescript theme={null}
interface IconViewProps extends Omit<ImageProps, 'source'> {
  source?: ImageSourcePropType | undefined
}
```

**Example:**

```typescript theme={null}
import { AdropProfileLogoView } from 'adrop-ads-react-native'

<AdropProfileLogoView style={{ width: 30, height: 30, borderRadius: 15 }} />
```

### AdropProfileNameView

프로필 이름을 표시합니다.

```typescript theme={null}
const AdropProfileNameView: React.FC<TextProps>
```

**Example:**

```typescript theme={null}
import { AdropProfileNameView } from 'adrop-ads-react-native'

<AdropProfileNameView style={{ fontSize: 14, fontWeight: '600' }} />
```

***

## AdropInterstitialAd

전면 광고를 관리하는 클래스입니다.

### Constructor

```typescript theme={null}
constructor(unitId: string)
```

**Parameters:**

* `unitId` (string): 광고 유닛 ID

### Properties

**isLoaded** (readonly)

```typescript theme={null}
get isLoaded(): boolean
```

광고 로드 여부를 반환합니다.

**unitId** (readonly)

```typescript theme={null}
get unitId(): string
```

광고 유닛 ID를 반환합니다.

**creativeId** (readonly)

```typescript theme={null}
get creativeId(): string
```

크리에이티브 ID를 반환합니다.

**txId** (readonly)

```typescript theme={null}
get txId(): string
```

트랜잭션 ID를 반환합니다.

**campaignId** (readonly)

```typescript theme={null}
get campaignId(): string
```

캠페인 ID를 반환합니다.

**destinationURL** (readonly)

```typescript theme={null}
get destinationURL(): string
```

광고 랜딩 URL을 반환합니다.

**browserTarget** (readonly)

```typescript theme={null}
get browserTarget(): BrowserTarget
```

브라우저 타겟 설정을 반환합니다.

**listener**

```typescript theme={null}
listener?: AdropListener
```

광고 이벤트 리스너를 설정합니다.

### Methods

**load()**

```typescript theme={null}
load(): void
```

광고를 로드합니다.

**show()**

```typescript theme={null}
show(): void
```

광고를 표시합니다.

**close()**

```typescript theme={null}
close(): void
```

광고를 프로그래밍 방식으로 닫습니다.

**destroy()**

```typescript theme={null}
destroy(): void
```

광고 인스턴스를 해제합니다.

**Example:**

```typescript theme={null}
import { AdropInterstitialAd } from 'adrop-ads-react-native'

const interstitialAd = new AdropInterstitialAd('YOUR_UNIT_ID')

interstitialAd.listener = {
  onAdReceived: (ad) => {
    console.log('Ad loaded')
    ad.show()
  },
  onAdFailedToReceive: (ad, errorCode) => {
    console.log('Ad failed to load', errorCode)
  },
}

interstitialAd.load()
```

***

## AdropRewardedAd

보상형 광고를 관리하는 클래스입니다.

### Constructor

```typescript theme={null}
constructor(unitId: string)
```

**Parameters:**

* `unitId` (string): 광고 유닛 ID

### Properties

AdropInterstitialAd와 동일한 속성을 가집니다.

### Methods

AdropInterstitialAd와 동일한 메서드(`load()`, `show()`, `close()`, `destroy()`)를 가지며, 추가로 다음 메서드를 포함합니다.

**setServerSideVerificationOptions()**

```typescript theme={null}
setServerSideVerificationOptions(options: ServerSideVerificationOptions): void
```

서버 측 보상 검증을 위한 옵션을 설정합니다. `load()` 전에 호출하세요.

* `options.userId` (string, optional): 서버 콜백에 전송되는 사용자 식별자
* `options.customData` (string, optional): 서버 콜백에 전송되는 커스텀 데이터

**SSV 예시:**

```typescript theme={null}
import { AdropRewardedAd } from 'adrop-ads-react-native'

const rewardedAd = new AdropRewardedAd('YOUR_UNIT_ID')

// 서버 측 검증 옵션 설정
rewardedAd.setServerSideVerificationOptions({
  userId: 'user_12345',
  customData: 'extra_info',
})

rewardedAd.listener = {
  onAdReceived: (ad) => {
    console.log('광고 로드 완료')
    ad.show()
  },
  onAdEarnRewardHandler: (ad, type, amount) => {
    console.log(`보상 획득: type=${type}, amount=${amount}`)
  },
  onAdFailedToReceive: (ad, errorCode) => {
    console.log('광고 로드 실패', errorCode)
  },
}

rewardedAd.load()
```

***

## AdropPopupAd

팝업 광고를 관리하는 클래스입니다.

### Constructor

```typescript theme={null}
constructor(
  unitId: string,
  colors?: AdropPopupAdColors,
  useCustomClick?: boolean
)
```

**Parameters:**

* `unitId` (string): 광고 유닛 ID
* `colors` (AdropPopupAdColors, optional): 팝업 색상 커스터마이징
* `useCustomClick` (boolean, optional): 커스텀 클릭 처리 여부 (기본값: false)

### Properties

**isLoaded** (readonly)

```typescript theme={null}
get isLoaded(): boolean
```

광고 로드 여부를 반환합니다.

**unitId** (readonly)

```typescript theme={null}
get unitId(): string
```

광고 유닛 ID를 반환합니다.

**creativeId** (readonly)

```typescript theme={null}
get creativeId(): string
```

크리에이티브 ID를 반환합니다.

**txId** (readonly)

```typescript theme={null}
get txId(): string
```

트랜잭션 ID를 반환합니다.

**campaignId** (readonly)

```typescript theme={null}
get campaignId(): string
```

캠페인 ID를 반환합니다.

**destinationURL** (readonly)

```typescript theme={null}
get destinationURL(): string
```

목적지 URL을 반환합니다.

**browserTarget** (readonly)

```typescript theme={null}
get browserTarget(): BrowserTarget
```

브라우저 타겟 설정을 반환합니다.

**listener**

```typescript theme={null}
listener?: AdropListener
```

광고 이벤트 리스너를 설정합니다.

### Methods

**load()**

```typescript theme={null}
load(): void
```

광고를 로드합니다.

**show()**

```typescript theme={null}
show(): void
```

광고를 표시합니다.

**close()**

```typescript theme={null}
close(): void
```

팝업 광고를 닫습니다.

**destroy()**

```typescript theme={null}
destroy(): void
```

광고 인스턴스를 해제합니다.

### AdropPopupAdColors

```typescript theme={null}
type AdropPopupAdColors = {
  closeTextColor?: string
  hideForTodayTextColor?: string
  backgroundColor?: string
}
```

**Properties:**

* `closeTextColor` (string, optional): 닫기 버튼 텍스트 색상
* `hideForTodayTextColor` (string, optional): '오늘 하루 숨기기' 텍스트 색상
* `backgroundColor` (string, optional): 배경 색상

**Example:**

```typescript theme={null}
import { AdropPopupAd } from 'adrop-ads-react-native'

const popupAd = new AdropPopupAd(
  'YOUR_UNIT_ID',
  {
    closeTextColor: '#000000',
    hideForTodayTextColor: '#666666',
    backgroundColor: '#FFFFFF',
  }
)

popupAd.listener = {
  onAdReceived: (ad) => {
    console.log('Popup ad loaded')
    ad.show()
  },
  onAdFailedToReceive: (ad, errorCode) => {
    console.log('Popup ad failed to load', errorCode)
  },
}

popupAd.load()
```

***

## AdropListener

광고 이벤트를 수신하는 리스너 인터페이스입니다.

```typescript theme={null}
type AdropListener = {
  onAdReceived?: (ad: AdropAd) => void
  onAdClicked?: (ad: AdropAd) => void
  onAdImpression?: (ad: AdropAd) => void
  onAdFailedToReceive?: (ad: AdropAd, errorCode?: any) => void
  onAdDidPresentFullScreen?: (ad: AdropAd) => void
  onAdWillPresentFullScreen?: (ad: AdropAd) => void
  onAdDidDismissFullScreen?: (ad: AdropAd) => void
  onAdWillDismissFullScreen?: (ad: AdropAd) => void
  onAdFailedToShowFullScreen?: (ad: AdropAd, errorCode?: any) => void
  onAdEarnRewardHandler?: (ad: AdropAd, type: number, amount: number) => void
  onAdBackButtonPressed?: (ad: AdropAd) => void
  onAdVideoStart?: (ad: AdropAd) => void
  onAdVideoEnd?: (ad: AdropAd) => void
}
```

**Events:**

* `onAdReceived`: 광고 수신 완료
* `onAdClicked`: 광고 클릭
* `onAdImpression`: 광고 노출
* `onAdFailedToReceive`: 광고 수신 실패
* `onAdDidPresentFullScreen`: 전면 광고 표시 완료
* `onAdWillPresentFullScreen`: 전면 광고 표시 시작
* `onAdDidDismissFullScreen`: 전면 광고 닫힘 완료
* `onAdWillDismissFullScreen`: 전면 광고 닫힘 시작
* `onAdFailedToShowFullScreen`: 전면 광고 표시 실패
* `onAdEarnRewardHandler`: 보상 획득 (보상형 광고 전용)
* `onAdBackButtonPressed`: 뒤로 가기 버튼 눌림 (Android 전용)
* `onAdVideoStart`: 동영상 광고 재생 시작
* `onAdVideoEnd`: 동영상 광고 재생 종료

***

## useAdropInterstitialAd

전면 광고를 React Hook으로 관리합니다.

### Signature

```typescript theme={null}
function useAdropInterstitialAd(unitId: string | null): AdHookReturns & AdStates
```

**Parameters:**

* `unitId` (string | null): 광고 유닛 ID

**Returns:**

* `load`: 광고 로드 함수
* `show`: 광고 표시 함수
* `reset`: 상태 초기화 함수
* `isBackPressed`: 뒤로 가기 버튼 눌림 여부 (Android 전용)
* `isClicked`: 클릭 여부
* `isClosed`: 닫힘 여부
* `isEarnRewarded`: 보상 획득 여부
* `isLoaded`: 로드 여부
* `isOpened`: 열림 여부
* `isReady`: 준비 여부
* `errorCode`: 에러 코드
* `reward`: 보상 정보 (`{ type: number, amount: number }` 또는 `undefined`)
* `browserTarget`: 브라우저 타겟 설정 (`BrowserTarget` 또는 `undefined`)

**Example:**

```typescript theme={null}
import { useAdropInterstitialAd } from 'adrop-ads-react-native'

function MyComponent() {
  const { load, show, isLoaded, errorCode } = useAdropInterstitialAd('YOUR_UNIT_ID')

  useEffect(() => {
    load()
  }, [])

  useEffect(() => {
    if (isLoaded) {
      show()
    }
  }, [isLoaded])

  return <View />
}
```

***

## useAdropRewardedAd

보상형 광고를 React Hook으로 관리합니다.

### Signature

```typescript theme={null}
function useAdropRewardedAd(unitId: string | null): AdHookReturns & AdStates
```

**Parameters:**

* `unitId` (string | null): 광고 유닛 ID

**Returns:**
useAdropInterstitialAd와 동일한 반환값을 가지며, 보상형 광고의 핵심 반환값으로 `isEarnRewarded`(보상 획득 여부)와 `reward`(보상 정보: `{ type: number, amount: number }`)를 포함합니다.

**Example:**

```typescript theme={null}
import { useAdropRewardedAd } from 'adrop-ads-react-native'

function MyComponent() {
  const { load, show, isLoaded, isEarnRewarded, reward } = useAdropRewardedAd('YOUR_UNIT_ID')

  useEffect(() => {
    load()
  }, [])

  useEffect(() => {
    if (isLoaded) {
      show()
    }
  }, [isLoaded])

  useEffect(() => {
    if (isEarnRewarded && reward) {
      console.log(`Reward: type=${reward.type}, amount=${reward.amount}`)
    }
  }, [isEarnRewarded, reward])

  return <View />
}
```

***

## useAdropWebView

Adrop SDK에 WebView를 등록하는 훅입니다. 뷰 태그 해석과 등록을 자동으로 처리합니다.

### Signature

```typescript theme={null}
function useAdropWebView(): {
  containerRef: React.RefObject<View>
  isReady: boolean
  onLayout: () => void
}
```

**Returns:**

* `containerRef`: WebView를 감싸는 `View`에 연결할 ref
* `isReady`: WebView 등록 완료 여부
* `onLayout`: 레이아웃 시 등록을 트리거하는 콜백

**Example:**

```typescript theme={null}
import { View } from 'react-native'
import { WebView } from 'react-native-webview'
import { useAdropWebView } from 'adrop-ads-react-native'

function WebViewScreen() {
  const { containerRef, isReady, onLayout } = useAdropWebView()

  return (
    <View ref={containerRef} style={{ flex: 1 }} onLayout={onLayout}>
      <WebView
        source={isReady ? { uri: 'https://your-website.com' } : { html: '' }}
        javaScriptEnabled={true}
        thirdPartyCookiesEnabled={true}
        mediaPlaybackRequiresUserAction={false}
        allowsInlineMediaPlayback={true}
      />
    </View>
  )
}
```

***

## AdropMetrics

사용자 속성 및 이벤트를 관리하는 클래스입니다.

### setProperty

```typescript theme={null}
static setProperty(key: string, value: any): void
```

사용자 속성을 설정합니다.

**Parameters:**

* `key` (string): 속성 키
* `value` (any): 속성 값

**Example:**

```typescript theme={null}
import { AdropMetrics, AdropProperties, AdropGender } from 'adrop-ads-react-native'

AdropMetrics.setProperty(AdropProperties.AGE, 25)
AdropMetrics.setProperty(AdropProperties.GENDER, AdropGender.MALE)
AdropMetrics.setProperty(AdropProperties.BIRTH, '1998-01-01')
```

### sendEvent

```typescript theme={null}
static sendEvent(name: string, params?: Record<string, any>): void
```

사용자 행동 이벤트를 전송합니다. 다중 아이템 이벤트를 위한 중첩 `items` 배열을 지원합니다.

**Parameters:**

* `name` (string): 이벤트 이름 (1\~64자)
* `params` (Record\<string, any>, optional): 이벤트 파라미터

**Example:**

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

// 단순 이벤트
AdropMetrics.sendEvent('app_open')

// 파라미터가 있는 이벤트
AdropMetrics.sendEvent('view_item', {
  item_id: 'SKU-123',
  item_name: 'Widget',
  price: 29900,
})

// 다중 아이템 이벤트
AdropMetrics.sendEvent('purchase', {
  tx_id: 'TXN-001',
  currency: 'KRW',
  items: [
    { item_id: 'SKU-001', item_name: '상품A', price: 29900, quantity: 1 },
    { item_id: 'SKU-002', item_name: '상품B', price: 15000, quantity: 2 },
  ],
})
```

### logEvent (deprecated)

```typescript theme={null}
/** @deprecated sendEvent를 사용하세요 */
static logEvent(name: string, params?: Record<string, any>): void
```

커스텀 이벤트를 로깅합니다. 내부적으로 `sendEvent`를 호출합니다.

**Parameters:**

* `name` (string): 이벤트 이름
* `params` (object, optional): 이벤트 파라미터

### properties

```typescript theme={null}
static properties(): Promise<Record<string, any>>
```

설정된 모든 속성을 가져옵니다.

**Returns:**

* Promise\<Record\<string, any>>: 속성 객체

**Example:**

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

const props = await AdropMetrics.properties()
console.log(props)
```

***

## AdropProperties

사용자 속성 키를 정의하는 enum입니다.

```typescript theme={null}
enum AdropProperties {
  AGE = 'AGE',
  BIRTH = 'BIRTH',
  GENDER = 'GDR',
}
```

**Values:**

* `AGE`: 나이
* `BIRTH`: 생년월일
* `GENDER`: 성별

***

## AdropGender

성별을 정의하는 enum입니다.

```typescript theme={null}
enum AdropGender {
  MALE = 'M',
  FEMALE = 'F',
  OTHER = 'O',
  UNKNOWN = 'U',
}
```

**Values:**

* `MALE`: 남성
* `FEMALE`: 여성
* `OTHER`: 기타
* `UNKNOWN`: 알 수 없음

***

## AdropConsent

사용자 동의(GDPR, CCPA 등)를 관리하는 클래스입니다.

### requestConsentInfoUpdate

```typescript theme={null}
static requestConsentInfoUpdate(): Promise<AdropConsentResult>
```

동의 정보를 업데이트하고 필요 시 동의 팝업을 표시합니다.

**Returns:**

* `Promise<AdropConsentResult>`: 동의 결과

**Example:**

```typescript theme={null}
import { AdropConsent } from 'adrop-ads-react-native'

const result = await AdropConsent.requestConsentInfoUpdate()
console.log('Status:', result.status)
console.log('Can request ads:', result.canRequestAds)
console.log('Can show personalized ads:', result.canShowPersonalizedAds)
```

### getConsentStatus

```typescript theme={null}
static getConsentStatus(): Promise<AdropConsentStatus>
```

현재 동의 상태를 가져옵니다.

**Returns:**

* `Promise<AdropConsentStatus>`: 현재 동의 상태

**Example:**

```typescript theme={null}
const status = await AdropConsent.getConsentStatus()
```

### canRequestAds

```typescript theme={null}
static canRequestAds(): Promise<boolean>
```

현재 동의 상태에 따라 광고를 요청할 수 있는지 확인합니다.

**Returns:**

* `Promise<boolean>`: 광고 요청 가능 여부

**Example:**

```typescript theme={null}
const canRequest = await AdropConsent.canRequestAds()
if (canRequest) {
  // 광고 로드
}
```

### reset

```typescript theme={null}
static reset(): void
```

동의 설정을 초기화합니다. 테스트 및 디버깅 목적으로 사용합니다.

**Example:**

```typescript theme={null}
AdropConsent.reset()
```

### setDebugSettings

```typescript theme={null}
static setDebugSettings(geography: AdropConsentDebugGeography): void
```

동의 플로우 테스트를 위한 디버그 지역을 설정합니다. DEBUG 빌드에서만 동작합니다.

**Parameters:**

* `geography` (AdropConsentDebugGeography): 시뮬레이션할 지역

**Example:**

```typescript theme={null}
import { AdropConsent, AdropConsentDebugGeography } from 'adrop-ads-react-native'

AdropConsent.setDebugSettings(AdropConsentDebugGeography.EEA)
```

***

## AdropConsentStatus

사용자 동의 상태를 나타내는 enum입니다.

```typescript theme={null}
enum AdropConsentStatus {
  UNKNOWN = 0,
  REQUIRED = 1,
  NOT_REQUIRED = 2,
  OBTAINED = 3,
}
```

**Values:**

* `UNKNOWN`: 아직 결정되지 않음
* `REQUIRED`: 동의 필요 (팝업 표시 필요)
* `NOT_REQUIRED`: 동의 불필요 (해당하지 않는 지역)
* `OBTAINED`: 동의 획득 완료

***

## AdropConsentResult

동의 정보 업데이트 결과를 나타내는 인터페이스입니다.

```typescript theme={null}
interface AdropConsentResult {
  status: AdropConsentStatus
  canRequestAds: boolean
  canShowPersonalizedAds: boolean
  error?: string
}
```

**Properties:**

* `status` (AdropConsentStatus): 동의 상태
* `canRequestAds` (boolean): 광고 요청 가능 여부
* `canShowPersonalizedAds` (boolean): 개인화 광고 표시 가능 여부
* `error` (string, optional): 에러 메시지 (있는 경우)

***

## AdropConsentDebugGeography

동의 테스트에서 디버그 지역을 지정하는 enum입니다.

```typescript theme={null}
enum AdropConsentDebugGeography {
  DISABLED = 0,
  EEA = 1,
  NOT_EEA = 2, // deprecated - OTHER를 사용하세요
  REGULATED_US_STATE = 3,
  OTHER = 4,
}
```

**Values:**

* `DISABLED`: 디버그 설정 없음 (실제 위치 사용)
* `EEA`: 유럽 경제 지역 (GDPR 적용)
* `NOT_EEA`: *(deprecated - `OTHER`를 사용하세요)*
* `REGULATED_US_STATE`: 규제 대상 미국 주 (캘리포니아 등, CCPA 적용)
* `OTHER`: 규제 대상이 아닌 지역

***

## Deprecated APIs

다음 API는 deprecated이며 향후 버전에서 제거됩니다. 권장 대안으로 마이그레이션하세요.

### AdropAd.destinationUrl

<Warning>
  `destinationUrl`은 deprecated입니다. `destinationURL`을 사용하세요.
</Warning>

```typescript theme={null}
// 변경 전 (deprecated)
const url = ad.destinationUrl

// 변경 후
const url = ad.destinationURL
```

### AdropPopupAd.createIds()

<Warning>
  `createIds()`는 deprecated입니다. `creativeId`를 사용하세요.
</Warning>

```typescript theme={null}
// 변경 전 (deprecated)
const ids = popupAd.createIds()

// 변경 후
const id = popupAd.creativeId
```

### AdropNativeAd.requestId

<Warning>
  `AdropNativeAd.requestId`는 deprecated이며 항상 빈 문자열을 반환합니다. 이 속성은 향후 버전에서 제거됩니다.
</Warning>

```typescript theme={null}
// 변경 전 (deprecated)
const reqId = nativeAd.requestId // 항상 '' 반환

// 변경 후 - requestId 사용을 제거
```

### AdropMetrics.logEvent()

<Warning>
  `logEvent()`는 deprecated입니다. `sendEvent()`를 사용하세요.
</Warning>

```typescript theme={null}
// 변경 전 (deprecated)
AdropMetrics.logEvent('purchase', { item_id: 'SKU-001' })

// 변경 후
AdropMetrics.sendEvent('purchase', { item_id: 'SKU-001' })
```