# React Native의 보상형 광고 통합

> SDK를 초기화하고 광고 유닛을 생성하고 이벤트 리스너를 설정.

> **Note:**
>
> 이 기술 자료는 SDK 8.7.0 이상에 해당합니다.

## 필수 조건##prerequisites

* 앱에 React 네이티브 플러그인 올바르게 연동했는지 확인합니다. 통합은 [여기](/grow/levelplay/sdk/react/plugin-integration.md) 설명되어 있습니다.
* 레벨플레이 초기화 API 사용하여 SDK를 초기화해야 합니다.
* 레벨플레이 대시보드에서 AdUnitID를 찾습니다.

## 보상형 광고 생성 및 이벤트 등록##create-rewarded-and-register-to-events

**onInitSuccess** 콜백을 수신한 후 레벨플레이 플랫폼(레벨플레이 SDK 단계 초기화)에 정의된 대로 관련 광고 유닛 ID를 사용하여 광고 유닛을 생성할 수 있습니다.

생성된 보상형 광고 광고 유닛의 보상형 광고 리스너를 설정하여 광고 게재를 알립니다.

```js
import {
    LevelPlayRewardedAd,
    type LevelPlayRewardedAdListener,
    type LevelPlayAdInfo,
    type LevelPlayAdError,
    type LevelPlayReward
} from 'Mediation

const [rewardedAd, setRewardedAd] = useState<LevelPlayRewardedAd>(new LevelPlayRewardedAd('YOUR_AD_UNIT_ID'))
useEffect(() => {
    const 리스너: LevelPlayRewardedAdListener = {
        onAdLoaded: (adInfo: LevelPlayAdInfo) => {
            // Provided when the ad is successfully loaded
        },
        onAdLoadFailed: (error: LevelPlayAdError) => {
            // Provided when the ad fails to load. 광고 유닛 정보가 포함됩니다.
        },
        onAdInfoChanged(adInfo: LevelPlayAdInfo) => {
            // Provided when the ad info is updated. 다른 광고가 로드되었을 때 사용 가능하며 더 높은 CPM/Rate를 포함합니다.
        },
        onAdDisplayed: (adInfo: LevelPlayAdInfo) => {
            // Provided when the ad is displayed
        },
        onAdDisplayFailed(오류: LevelPlayAdError, adInfo: LevelPlayAdInfo) => {
            // Provided when the ad fails to be displayed
        },
        onAdClicked: (adInfo: LevelPlayAdInfo) => {
            // Provided when the user clicks on the ad
        },
        onAdClosed: (adInfo: LevelPlayAdInfo) => {
            // Provided when the ad is closed
        },
        onAdRewarded: (보상: LevelPlayReward, adInfo: LevelPlayAdInfo) => {
            // Provided when the ad is rewarded. 광고 유닛 정보와 보상 정보가 포함됩니다.
        }
    };
    rewardedAd.setListener(listener);
}, [rewardedAd]);
```

### 레벨플레이 보상형 광고 광고 콜백##levelplay-rewarded-ad-callbacks

**onAdLoaded** – 광고가 성공적으로 로드되면 제공됩니다.

**onAdLoadFailed** – 광고 로드 실패 시 제공됩니다. 광고 유닛 정보가 포함됩니다.

**onAdDisplayed** – 광고가 표시될 때 제공됩니다. 이는 노출과 동일합니다.

**onAdDisplayFailed**(선택 사항) – 광고가 표시되지 않을 때 제공됨

**onAdRewarded** – 광고가 보상형 광고일 때 제공됩니다. 광고 유닛 정보와 보상 정보가 포함됩니다.

**onAdClicked**(선택 사항) – 사용자가 광고를 클릭할 때 제공

**onAdClosed** – 광고를 닫을 때 제공됨

**onAdInfoChanged** (선택 사항) – 광고 정보가 업데이트될 때 제공됩니다. 다른 광고가 로드되었을 때 사용 가능하며 더 높은 CPM/Rate를 포함합니다.

## 보상형 광고 세부 정보 가져오기##get-rewarded-ad-details

getReward API 사용하여 레벨플레이 대시보드에서 설정한 보상 데이터에 액세스, 접근. 다른 Mediation API와 달리 이 호출은 초기화 후 SDK에 로컬에 저장된 데이터를 반환하는 독립성 호출. 이렇게 하면 광고를 시작하기 전에 사용자에게 잠재적인 보상을 알리는 동적 데이터 기반 UI를 빌드 수 있으므로 앱에서 보상 값을 하드코딩할 필요가 없습니다.

### 필수 조건##prerequisites

getReward API 구현하기 전에 프로젝트가 다음 기술 요구 사항을 충족하는지 확인합니다.

* **SDK Initialization**: initSDK를 호출 onInitializationSuccess 콜백 기다려 보상 데이터가 캐싱되었는지 확인합니다.
* **광고 오브젝트 인스턴스**: API 호출하기 전에 유효한 광고 유닛 ID로 보상형 광고 광고 오브젝트 인스턴스화.
* **Minimum SDK Version**: 레벨플레이 SDK 버전 8.1.0 이상(네이티브 또는 Unity 패키지)을 사용합니다.

### 베스트 프랙티스##best-practices

안정적이고 예측 가능한 통합을 보장하려면 다음 권장 사항을 따르십시오.

* 초기화 성공 시 **호출**: getReward를 호출 가장 적합한 시점은 초기화 성공 리스너 내부입니다. 이렇게 하면 사용자 화면에 진입할 때마다 UI가 준비됩니다.
* **빈 상태 확인**: UI를 업데이트하기 전에 항상 이 양을 0 이상으로 확인해야 합니다. 이렇게 하면 초기화 중에 네트워크 오류가 발생하는 경우 원활한 사용자 경험 보장할 수 있습니다.
* **플레이스먼트 정밀도**: getReward("placementName")에 사용된 문자열이 레벨플레이 대시보드에 정의된 이름과 정확히 일치하는지 확인합니다.

### API 구조, 구조체##api-structure

getReward 메서드를 사용하면 레벨플레이 대시보드에서 동기화된 보상 데이터에 액세스, 접근 수 있습니다. 이 메서드를 사용하여 로컬 SDK 캐시 특정 플레이스먼트 값 또는 전역 광고 유닛 기본값을 쿼리 수 있습니다.

#### getReward##getreward

특정 플레이스먼트 또는 기본 광고 유닛의 보상 이름과 금액을 가져옵니다. 사용할 다른 파라미터는 없습니다.

| 파라미터          | 설명                                                            |
| ------------- | ------------------------------------------------------------- |
| placementName | 레벨플레이 대시보드에 정의된 플레이스먼트의 고유 식별자. 광고 유닛의 기본 보상을 가져오는 `null` 전달. |

이름(String)과 금액(int)이 포함된 LevelPlayReward 오브젝트 반환합니다.

### 초안 수립##initial-setup

getReward API 레벨플레이 SDK의 핵심 컴포넌트 기능하며 다음 로직에 따라 동작하여 데이터를 지연 없이 사용할 수 있습니다.

* **통합 기능**: 보상 데이터는 초기 SDK 설정 중에 가져오기 때문에 API 호출 순간적이며 네트워크 요청이 필요하지 않습니다.
* **에디터 설정**: 앱이 레벨플레이 SDK와 연동되면 API 즉시 사용할 수 있습니다. 이 기능을 테스트하려면 추가 에셋이나 플러그인이 필요하지 않습니다.

### 보상 선택 로직 이해##understand-reward-selection-logic

API 특정 계층 구조 구조에 따라 LevelPlayReward 오브젝트 반환합니다. 이 로직을 이해하면 특정 보상이 표시되는 이유를 문제 해결 데 도움이 됩니다.

* **플레이스먼트 레벨**: 호출 유효한 플레이스먼트 이름이 제공되면 SDK는 대시보드에서 해당 플레이스먼트에 대해 설정된 특정 보상을 반환합니다.
* **광고 유닛 레벨**: 플레이스먼트 이름이 null 찾을 수 없는 경우, SDK는 광고 유닛에 정의된 기본 보상으로 폴백합니다.
* **폴백 상태**: 초기화가 완료되기 전에 API 호출되면 빈 문자열 이름과 금액이 0인 보상 오브젝트 반환합니다.

### UI 동적 업데이트##update-your-ui-dynamically

getReward API를 사용하여 정적 버튼을 고도의 행동 호출로 변환합니다(동사), 트랜스폼(명사). 예를 들어 일반 "Watch Video" 버튼 대신 "Watch to earn 50 Gold"를 표시할 수 있습니다.

* **확인 금액**: UI 컴포넌트를 업데이트하기 전에 항상 reward.amount > 0을 확인해야 합니다.
* **이벤트 기반 업데이트**: 초기화 성공 리스너 내에서 API 호출 사용자 화면에 진입할 때 UI가 정확한지 확인합니다.
* **대소문자 구분**: 코드의 플레이스먼트 이름 문자열이 레벨플레이 대시보드와 정확히 일치하는지 확인합니다. 일치하지 않는 문자열은 광고 유닛 폴백 트리거합니다.

### getReward API 구현 문제 해결##troubleshooting-getreward-api-implementation

* **보상 금액은 0을 반환**합니다. 이는 일반적으로 onInitializationSuccess 콜백 전에 API 호출된 경우에 발생합니다. 보상을 쿼리하기 전에 SDK가 완전히 준비되었는지 확인합니다.
* **잘못된 보상 유형 표시**: 여러 플레이스먼트가 있는지 확인합니다. 플레이스먼트 이름의 철자가 잘못되면 SDK는 특정 플레이스먼트 보상 대신 기본 광고 유닛 보상으로 설정됩니다.

## 보상형 광고 로드##load-rewarded-ad

**onInitSuccess** 콜백을 수신하면 보상형 광고를 로드할 수 있습니다. 이는 메서드를 사용하여 수행해야 합니다.

```js
rewardedAd.loadAd();
```

## 보상형 광고 표시##show-rewarded-ad

showAd API를 사용하여 onAdLoaded 콜백 수신한 후 보상형 광고 광고를 표시할 수 있습니다.

[플레이스먼트를](/grow/levelplay/platform/settings/placements.md) 사용하는 경우 아래와 같이 API의 일부로 이름을 공유합니다.

```js
// Show ad without placement
rewardedAd.showAd();
// Show ad with placement
rewardedAd.showAd('YOUR_PLACEMENT');
```

### 광고 확인 준비##check-ad-ready

showFailure를 방지하고 광고를 올바르게 표시할 수 있도록 showAd() API 호출하기 전에 다음 API 사용하는 것이 좋습니다.

**isAdReady** – 광고가 성공적으로 로드되고 광고 유닛이 제한되지 않거나 거짓이 아닌 경우 true로 확인되는 Promise를 반환합니다.

**isPlacementCapped** – 유효한 플레이스먼트가 제한된 경우 true로 확인되는 Promise를 반환하는 정적 메서드입니다. 플레이스먼트가 유효하지 않거나 제한이 없는 경우 false를 반환합니다.

```js
// Check that ad is ready and that the placement is not capped (both APIs are async)
const isReady = await rewardedAd.isAdReady();
const isPlacementCapped = await LevelPlayRewardedAd.isPlacementCapped('YOUR_PLACEMENT');
if (isReady && !isPlacementCapped) {
  await rewardedAd.showAd('YOUR_PLACEMENT');
}
```

광고가 플레이어 성공적으로 표시되면 Load 보상형 광고 Ad 단계를 반복하여 다른 광고를 로드할 수 있습니다. 한 번에 하나의 광고를 로드할 때 새 광고 엔티티 생성할 필요가 없습니다.

### 동적 UserId##dynamic-userid

동적 사용자 ID는 세션 전반에서 변경할 수 있는 AdRewarded 거래를 확인하는 데 사용되는 파라미터. 이 파라미터는 [서버 간](/grow/levelplay/platform/settings/server-to-server-callback.md) 광고 보상형 광고 콜백을 통해 수신되며 showAd를 호출하기 전에 설정해야 합니다.

* 문자열 값은 영숫자 1\~64자로 구성되어야 합니다.
* 보상 세부 정보가 포함된 콜백 URL에 `dynamicUserId` 파라미터가 표시됩니다.

```js
LevelPlay.setDynamicUserId("userId");
```

## 사용자 보상##reward-the-user

레벨플레이 SDK는 사용자가 동영상을 성공적으로 완료할 때마다 **onAdRewarded를** 작동시킵니다.

**onAdRewarded** 및 **onAdClosed**는 비동기입니다.  **onAdRewarded가** **onAdClosed** 이후에 해지되는 경우에도 보상을 제공하도록 리스너를 설정해야 합니다.

```js
onAdRewarded: (보상: LevelPlayReward, adInfo: LevelPlayAdInfo) => {
    // Provided when the ad is rewarded. 광고 유닛 정보와 보상 정보가 포함됩니다.
}

```

## 여러 광고 유닛 보상형 광고 API##multiple-ad-unit-rewarded-apis

|     | **레거시**                        | **광고 단위 이름(새로운)**   |
| --- | ------------------------------ | ------------------- |
| 클래스 | 아이언소스(IronSource)              | LevelPlayRewardedAd |
| API | loadRewardedVideo              | loadAd              |
|     | showRewardedVideo              | showAd              |
|     | isRewardedVideoPlacementCapped | isPlacementCapped   |
|     | isRewardedVideoAvailable       | isAdReady           |
|     | placement.getRewardName        | reward.name         |
|     | placement.getRewardAmount      | reward.amount       |

## 보상형 광고 광고의 전체 구현 예시##full-implementation-example-of-rewarded-ad

```js
import {
    LevelPlayRewardedAd,
    type LevelPlayRewardedAdListener,
    type LevelPlayAdInfo,
    type LevelPlayAdError,
    type LevelPlayReward
} from 'Mediation

const [rewardedAd, setRewardedAd] = useState<LevelPlayRewardedAd>(new LevelPlayRewardedAd('YOUR_AD_UNIT_ID'))
const 리스너: LevelPlayRewardedAdListener = {
    onAdLoaded: (adInfo: LevelPlayAdInfo) => {
        // Implement your logic here, for example showing the ad
        rewardedAd.showAd()
    },
    onAdLoadFailed: (error: LevelPlayAdError) => {
        // Implement your logic here...
    },
    onAdInfoChanged(adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdDisplayed: (adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdDisplayFailed(오류: LevelPlayAdError, adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdClicked: (adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdClosed: (adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdRewarded: (보상: LevelPlayReward, adInfo: LevelPlayAdInfo) => {
        // Implement your logic here...
    }
};
useEffect(() => {
    rewardedAd.setListener(listener)
    rewardedAd.loadAd()
}, []);
// Rest of component ...
// End of component ...
```

## 레벨플레이 Mediation 데모 앱##levelplay-mediation-demo-app

Integration Demo 애플리케이션 보상형 광고 광고 유닛 API를 앱에 통합하는 방법을 보여 줍니다.

[React 네이티브 데모 애플리케이션 다운로드](https://github.com/ironsource-mobile/react-native-SDK/tree/master/example)

[통합 테스트 제품군](/grow/levelplay/sdk/react/integration-test-suite.md)과의 통합 여부 확인

## 다음 단계##next-steps

추가 보상형 광고 광고 네트워크를 연동하거나 추가 광고 형식을 설정 Unity 통합 가이드를 따르십시오.

* [Mediation Networks 추가](/grow/levelplay/sdk/react/mediation-networks.md)
* [배너 광고](/grow/levelplay/sdk/react/banner-integration.md)
* [인터스티셜 광고](/grow/levelplay/sdk/react/interstitial-integration.md)
* [네이티브 광고](/grow/levelplay/sdk/react/native-ads-integration.md)