# Android용 보상형 광고 광고 유닛 API 마이그레이션

> SDK를 초기화하고 광고 유닛 ID로 보상형 광고 광고 오브젝트 생성하고 광고 이벤트의 리스너를 구현하여 레벨플레이 보상형 광고 광고 유닛 API 마이그레이션합니다.

이 가이드에서는 광고 유닛 ID를 워터폴 식별자 사용하여 SDK 버전 9.0.0부터 레벨플레이 API를 연동하여 보상형 광고 광고를 로드하고 표시하는 방법을 설명합니다.

> **Important:**
>
> 현재 사용 중인 통합 방법 대신 이 문서에 소개된 API를 사용합니다(아이언소스 init, 아이언소스 로드 보상형 광고, 보상형 광고 리스너). **API Comparison** 섹션 API 대체 항목을 확인할 수 있습니다.
>
> [고급 설정](/grow/levelplay/sdk/unity/additional-settings.md.md) 및 [규정 설정](/grow/levelplay/sdk/unity/regulation-advanced-settings.md.md)은 변경되지 않았으며 레벨플레이 SDK 초기화 전 또는 후에 지원됩니다.

## 레벨플레이 플랫폼에서 광고 유닛 ID 찾기

보상형 광고 광고를 로드하고 표시하려면 레벨플레이 Mediation 플랫폼에서 사용할 수 있는 광고 유닛 ID를 사용해야 합니다.

1. 레벨플레이 계정에서 **설정** > **광고 단위**로 이동합니다.
2. 보상형 광고 유닛 ID를 복사하여 코드에 통합합니다.

## 레벨플레이 SDK 초기화##initializing-the-levelplay-sdk

레벨플레이 SDK를 초기화하려면 다음 단계를 따르십시오.

1. 초기화 성공 또는 실패에 대한 콜백을 구현합니다.
2. 해당하는 경우 appKey와 사용자 ID를 사용하여 레벨플레이 init API 호출.

1) **Java**

   ```java
   LevelPlayInitRequest initRequest = new LevelPlayInitRequest.Builder(appKey)
     .withUserId("UserID")
     .build();
   LevelPlayInitListener initListener = new LevelPlayInitListener() {
     @Override
     public void onInitFailed(@NonNull LevelPlayInitError error) {}
     @Override
     public void onInitSuccess(LevelPlayConfiguration configuration) {}
   };
   LevelPlay.init(context, initRequest, initListener);
   ```

2) **Kotlin**

   ```kotlin
   val initRequest = LevelPlayInitRequest.Builder("AppKey")
     .withUserId("UserId")
     .build()
   LevelPlay.init(context, initRequest, object : LevelPlayInitListener {
     오버라이드 fun onInitSuccess(설정: LevelPlayConfiguration) {}
     override fun onInitFailed(error: LevelPlayInitError) {}
   })
   ```

### 레벨플레이 Init 리스너##levelplay-init-listeners

**onInitSuccess**: 초기화가 성공적으로 완료되면 트리거됩니다. 이 표시를 수신하면 광고를 생성하고 로드할 수 있습니다.

**onInitFailed**: 설정이 성공적으로 검색되지 않았으며 광고를 로드할 수 없습니다. 나중에 레벨플레이 SDK를 초기화하는 것이 좋습니다(인터넷 연결이 가능하거나 오류 원인이 해결된 경우).

| 이니트 | 레거시                      | 광고 단위(신규)      |
| :-- | :----------------------- | :------------- |
| API | IronSource.init          | LevelPlay.init |
| 콜백  | onInitializationComplete | onInitSuccess  |
|     | –                        | onInitFailed   |

## **보상형 광고 오브젝트 생성**##**create-rewarded-ad-object**

보상형 광고 오브젝트의 생성은 **onInitSuccess** 콜백을 수신한 후에 수행해야 합니다.

오브젝트 세션 전체에 걸쳐 여러 로드와 표시를 처리할 수 있는 재사용 가능한 인스턴스. 생성되면 동일한 광고 유닛의 광고를 로드하고 표시하는 데 사용해야 합니다.

더 고급 구현을 위해 필요한 경우 여러 보상형 광고 객체를 생성할 수 있습니다.

1. **Java**

   ```java
   // 보상형 광고 만들기
   mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   ```

2. **Kotlin**

   ```kotlin
   // 보상형 광고 만들기
   mRewardedAd = LevelPlayRewardedAd("adUnitId")
   ```

## 보상형 광고 이벤트 등록하기##register-to-rewarded-events

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

* 보상형 광고 광고를 로드하기 전에 리스너를 설정하는 것이 좋습니다.
* 각 보상형 광고 광고에는 고유한 리스너 구현이 있어야 합니다.
* 콜백은 메인 스레드 실행됩니다.

1. **Java**

   ```java
   // 보상형 광고 만들기
   mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   // 리스너 설정
   mRewardedAd.setListener(this);

   // LevelPlayRewardedAdListener methods
   @Override
   public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdLoadFailed(@NonNull LevelPlayAdError error) {}
   @Override
   public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}
   @Override
   public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}
   ```

2. **Kotlin**

   ```kotlin
   // 보상형 광고 만들기
   mRewardedAd = LevelPlayRewardedAd("adUnitId") 
   // 리스너 설정
   mRewardedAd.setListener(this)
   // LevelPlayRewardedAdListener 메서드
   override fun onAdLoaded(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdLoadFailed(오류: LevelPlayAdError) {}
   override fun onAdInfoChanged(adInfo: LevelPlayAdInfo) {}
   override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdDisplayFailed(오류: LevelPlayAdError, adInfo: LevelPlayAdInfo) {}
   override fun onAdClicked(adInfo: LevelPlayAdInfo) {}
   override fun onAdClosed(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdRewarded(보상: LevelPlayReward, adInfo: LevelPlayAdInfo) {}
   ```

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

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

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

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

**onAdDisplayFailed**: 광고가 표시되지 않을 때 제공됩니다.

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

**onAdClicked**(선택 사항): 사용자 광고를 클릭할 때 제공됩니다.

**onAdClosed**: 광고가 닫힐 때 제공됩니다.

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

| 컴포넌트 | 레거시                           | 광고 단위(신규)           |
| ---- | ----------------------------- | ------------------- |
| 청자   | IronSourceRewardedVideoEvents | LevelPlayRewardedAd |
| 콜백   | onAdReady                     | onAdLoaded          |
|      | onAdLoadFailed                | onAdLoadFailed      |
|      | onAdOpened                    | onAdDisplayed       |
|      | onAdClosed                    | onAdClosed          |
|      | onAdShowFailed                | onAdDisplayFailed   |
|      | onAdRewarded                  | onAdRewarded        |
|      | onAdClicked                   | onAdClicked         |
|      | onAdShowSucceeded             | n/a (사용 중단 예정)      |
|      | n/a                           | onAdInfoChanged     |

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

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

1. **Java**

   ```java
   // 광고를 로드하거나 다시 로드합니다.
   mRewardedAd.loadAd();
   ```

2. **Kotlin**

   ```kotlin
   // 광고를 로드하거나 다시 로드합니다.
   mRewardedAd.loadAd()
   ```

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

**showAd** API를 사용하여 **onAdLoaded** 콜백을 수신한 후 보상형 광고를 표시할 수 있습니다.
[플레이스먼트를](/grow/levelplay/platform/settings/placements.md) 사용하는 경우 아래와 같이 API의 일부로 이름을 공유합니다.

1. **Java**

   ```java
   // 플레이스먼트 없이 광고 표시 
   mRewardedAd.showAd(this);
   // 플레이스먼트가 있는 광고 표시 
   mRewardedAd.showAd(this, placementName);
   ```

2. **Kotlin**

   ```kotlin
   // 플레이스먼트 없이 광고 표시 
   mRewardedAd.showAd(this)
   // 플레이스먼트가 있는 광고 표시 
   mRewardedAd.showAd(this, placementName)
   ```

### 광고가 준비되었는지 확인##check-ad-is-ready

표시 실패를 방지하고 광고가 올바르게 표시되었는지 확인하기 위해 **showAd** API를 호출하기 전에 다음 API를 사용하는 것이 좋습니다.

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

**isPlacementCapped** – 유효한 플레이스먼트가 제한되면 true를 반환합니다. 플레이스먼트가 유효하지 않거나 제한이 없는 경우 이 API false를 반환합니다.

1. **Java**

   ```java
   // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
   if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
       mRewardedAd.showAd(this, placementName);
   }
   ```

2. **Kotlin**

   ```kotlin
   // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
   if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
       mRewardedAd.showAd(this, placementName)
   }
   ```

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

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

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

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

1. **Java**

   ```java
   @Override
   public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {
     // 로직을 구현하여 사용자 보상을 부여합니다.
     String name = reward.getName();
     int amount = reward.getAmount();
   }
   ```

2. **Kotlin**

   ```kotlin
   오버라이드 fun onAdRewarded(보상: LevelPlayReward, adInfo: LevelPlayAdInfo) {
     // 로직을 구현하여 사용자 보상을 부여합니다.
     val name: String = reward.name
     val량: Int = reward.amount
   }
   ```

## 여러 광고 유닛 보상형 광고 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

1. **Java**

   ```java
   공용 클래스 RewardedAdActivity 확장 활동 구현 LevelPlayRewardedAdListener {
     private LevelPlayRewardedAd mRewardedAd;
     void createRewardedAd() {
       mRewardedAd = new LevelPlayRewardedAd("adUnitId");
       mRewardedAd.setListener(this);
     }
     void loadRewardedAd() {
       // 광고를 로드하거나 다시 로드합니다.
       mRewardedAd.loadAd();
     }
     void showRewardedAd() {
       if (mRewardedAd.isAdReady()) {
         mRewardedAd.showAd(this);
       }
     }
     void showRewardedAd(@NonNull String placementName) {
       // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다.
       if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
         mRewardedAd.showAd(this, placementName);
       }
     }
     // LevelPlayRewardedAdListener 메서드
     @Override
     public void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdLoadFailed(@NonNull LevelPlayAdError error) {}
     @Override
     public void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     공용 void onAdDisplayFailed(@NonNull LevelPlayAdError, @NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}
     @Override
     public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}
   }
   ```

2. **Kotlin**

   ```kotlin
   클래스 RewardedAdActivity : Activity(), LevelPlayRewardedAdListener {
   private lateinit var mRewardedAd: LevelPlayRewardedAd
   fun createRewardedAd() {
       mRewardedAd = LevelPlayRewardedAd("adUnitId")
       mRewardedAd.setListener(this)
   }
   fun loadRewardedAd() {
       mRewardedAd.loadAd()
   }
   fun showRewardedAd() {
       if (mRewardedAd.isAdReady()) {
           mRewardedAd.showAd(this)
       }
   }
   fun showRewardedAd(placementName): 문자열) {
       // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
       if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {
           mRewardedAd.showAd(this, placementName)
       }
   }
   // LevelPlayRewardedAdListener 메서드
   override fun onAdLoaded(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdLoadFailed(오류: LevelPlayAdError) {}
   override fun onAdInfoChanged(adInfo: LevelPlayAdInfo) {}
   override fun onAdDisplayed(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdDisplayFailed(오류: LevelPlayAdError, adInfo: LevelPlayAdInfo) {}
   override fun onAdClicked(adInfo: LevelPlayAdInfo) {}
   override fun onAdClosed(adInfo: LevelPlayAdInfo) {}
   오버라이드 fun onAdRewarded(보상: LevelPlayReward, adInfo: LevelPlayAdInfo) {}
   }
   ```