# Android용 보상형 광고 통합

> LevelPlayRewardedAdListener를 구현하고, 광고 유효성 초기화하고 확인하고, 광고를 플레이스먼트로 표시하고, 완료 시 사용자에게 보상을 제공하고, 레벨플레이 통합 도우미를 사용하여 설정을 확인하여 레벨플레이의 보상형 광고 광고 유닛을 통합할 수 있습니다.

Unity 레벨플레이 보상형 광고 전체 화면 광고 유닛으로, 일반적으로 앱 라이프사이클 동안 자연스럽게 전환 시점에 게재됩니다. 

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

## 필수 조건##prerequisites

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

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

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

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

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

1. **Java**

   ```java
   LevelPlayRewardedAd mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   ```

2. **Kotlin**

   ```kotlin
   val mRewardedAd = LevelPlayRewardedAd("adUnitId")
   ```

## 보상형 광고 리스너 설정##set-rewarded-listener

코드에 **LevelPlayRewardedAdListener를 구현**하여 광고 전송에 대해 알 수 있습니다. 

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

1. **Java**

   ```java
   // 보상형 광고 오브젝트 생성
   LevelPlayRewardedAd mRewardedAd = new LevelPlayRewardedAd("adUnitId");
   mRewardedAd.setListener(new LevelPlayRewardedAdListener() {
   @Override
   public void onAdLoaded(LevelPlayAdInfo levelPlayAdInfo) {
      // 광고가 성공적으로 로드되었습니다.
   }
   @Override
   공용 void onAdLoadFailed(LevelPlayAdError levelPlayAdError) {
      // 광고 로드 실패 
   }
   @Override
   public void onAdDisplayed(LevelPlayAdInfo levelPlayAdInfo) {
      // 광고가 표시되고 화면에 표시되었습니다.
   }

   @Override 
   public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {
      // Ad reward received 
   }
   @Override
   public void onAdDisplayFailed(LevelPlayAdError levelPlayAdError, LevelPlayAdInfo levelPlayAdInfo) {
      // Ad fails to be displayed
      // Optional
   }
   @Override
   public void onAdClicked(LevelPlayAdInfo levelPlayAdInfo) {
      // Ad was clicked
      // Optional
   }
   @Override
   public void onAdClosed(LevelPlayAdInfo levelPlayAdInfo) {
      // Ad was closed
      // Optional
   }
   @Override
   public void onAdInfoChanged(LevelPlayAdInfo levelPlayAdInfo) {
      // Called after the ad info is updated. 다른 보상형 광고 광고가 로드되었을 때 사용 가능하며 CPM/Rate가 더 높습니다.
      // Optional
   }
   });
   ```

2. **Kotlin**

   ```kotlin
   // 보상형 광고 오브젝트 생성 
   val mRewardedAd = LevelPlayRewardedAd("adUnitId")
   mRewardedAd.setListener(object : LevelPlayRewardedAdListener {
   override fun onAdLoaded(levelPlayAdInfo: LevelPlayAdInfo) {
      // 광고가 성공적으로 로드되었습니다.
   }
   override fun onAdLoadFailed(levelPlayAdError: LevelPlayAdError) {
      // 광고 로드 실패
   }
   override fun onAdDisplayed(levelPlayAdInfo: LevelPlayAdInfo) {
      // 광고가 표시되고 화면에 표시되었습니다.
   }

   오버라이드 fun onAdRewarded(보상: LevelPlayReward, adInfo: LevelPlayAdInfo) {
      // Ad reward received 
   }
   오버라이드 fun onAdDisplayFailed(levelPlayAdError: LevelPlayAdError, levelPlayAdInfo: LevelPlayAdInfo) {
      // Ad fails to be displayed
      // Optional
   }
   override fun onAdClicked(levelPlayAdInfo: LevelPlayAdInfo) {
      // Ad was clicked
      // Optional
   }
   override fun onAdClosed(levelPlayAdInfo: LevelPlayAdInfo) {
      // Ad was closed
      // Optional
   }
   override fun onAdInfoChanged(levelPlayAdInfo: LevelPlayAdInfo) {
      // Called after the ad info is updated. 다른 보상형 광고 광고가 로드되었을 때 사용 가능하며 CPM/Rate가 더 높습니다.
      // Optional
   }
   })	 
   ```

### 레벨플레이 광고 정보##levelplay-ad-info

**LevelPlayAdInfo** 파라미터에는 로드된 광고에 대한 정보가 포함되어 있습니다.

## 보상형 광고 세부 정보 가져오기##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

```java
public LevelPlayReward getReward(String placementName)
```

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

| 파라미터          | 설명                                                            |
| ------------- | ------------------------------------------------------------- |
| 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가 정확한지 확인합니다.
* **대소문자 구분**: 코드의 플레이스먼트 이름 문자열이 레벨플레이 대시보드와 정확히 일치하는지 확인합니다. 일치하지 않는 문자열은 광고 유닛 폴백 트리거합니다.

### 보상 데이터 검색 예시##retrieve-reward-data-examples

다음 예제는 Android용 보상 API 호출 방법을 보여 줍니다.

1. **Kotlin**

   ```kotlin
   /** 
    * 광고와 관련된 보상을 가져옵니다. 
    * 이 메서드를 사용하여 광고 유닛 또는 플레이스먼트에 설정된 보상을 가져옵니다. The 
    * 유효한 플레이스먼트 이름이 있는 경우 플레이스먼트별 보상이 광고 유닛 보상보다 우선합니다. 
    * 제공됩니다. 
    * @param placement 보상을 가져오거나 `null` 광고 유닛의 보상을 사용하기 위한 플레이스먼트 이름입니다. 
    * @return [LevelPlayReward] 오브젝트. 실패 시 빈 보상을 반환합니다(`name: ""` 및 `amount: 0`). 
    */ 
   @JvmOverloads 
   fun getReward(placement: 문자열? = null): LevelPlayReward { 
       val reward = mRewardedAd.getReward(placement)
       Log.d("레벨플레이", "금액: ${reward.amount}, 이름: ${reward.name}")
       반환 보상
   }
   ```

2. **Java**

   ```java
   LevelPlayReward reward = mRewardedAd.getReward("bonus_level");
   if (reward.getAmount() > 0) {
       // 보상 로직 제공
   }
   ```

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

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

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

보상형 광고를 로드하려면 **loadAd를** 사용합니다.

1. **Java**

   ```java
   mRewardedAd.loadAd();
   ```

2. **Kotlin**

   ```kotlin
   mRewardedAd.loadAd()	 
   ```

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

**LevelPlayRewardedAdListener** API를 사용하여 **onAdLoaded** 콜백을 수신한 후 보상형 광고를 표시합니다.

* 공유하는 데 필요한 **활동**입니다. 
* 플레이스먼트를 사용하는 경우 아래의 플레이스먼트 섹션에 표시된 대로 **showAd** API에서 플레이스먼트 이름을 전달합니다.
* 광고가 사용자 성공적으로 표시되면 로딩 단계를 반복하여 다른 광고를 로드할 수 있습니다. 

1. **Java**

   ```java
   public void showRewardedAd() {
   // 광고가 준비되었는지 확인합니다.
   if (mRewardedAd.isAdReady()) {
      // 광고 표시 
      mRewardedAd.showAd(this);
   }
   }	
   ```

2. **Kotlin**

   ```kotlin
   fun showRewardedAd() {
   // 광고가 준비되었는지 확인합니다.
   if (mRewardedAd.isAdReady()) {
      // 광고 표시
      mRewardedAd.showAd(this)
   }
   }	 
   ```

### 광고가 준비되었는지 확인##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)
   }
   ```

### Placements##placements

레벨플레이 대시보드에서 보상형 광고의 [플레이스먼트](/grow/levelplay/platform/settings/placements.md) 속도와 한도를 지원합니다. 

보상형 광고에 대한 플레이스먼트가 설정된 경우, 특정 플레이스먼트에 광고를 게재하려면 **showAd** 메서드를 호출합니다.

1. **Java**

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

2. **Kotlin**

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

### 동적 UserId##dynamic-userid

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

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

1. **Java**

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

2. **Kotlin**

   ```kotlin
   LevelPlay.setDynamicUserId("userId")
   ```

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) {}
   }
   ```

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

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

[Android 데모 애플리케이션 다운로드](https://github.com/ironsource-mobile/Mediation-Demo-Apps)

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

## 다음 단계##next-steps

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

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