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

> 광고 유닛을 초기화하고, 델리게이트 설정하고, 광고 이벤트를 처리하여 iOS 앱에 보상형 비디오 광고 유닛을 구현합니다.

이 가이드에서는 광고 유닛 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. 세션에서 초기화할 광고 형식 리스트를 정의합니다. 여기에는 다중 광고 유닛이 아닌 API를 사용하려는 모든 광고 형식이 포함되어야 합니다.
3. 해당하는 경우 appKey, 광고 형식, 사용자 ID를 사용하여 레벨플레이 init API 호출.

1) **Objective-C**

   ```objective-c
   // 앱 키로 요청 빌더를 생성합니다. 사용 가능한 경우 사용자 ID 추가
   LPMInitRequestBuilder *requestBuilder = [[LPMInitRequestBuilder alloc] initWithAppKey:@"appKey"];
   [requestBuilder withUserId:@"UserId"];
   // 초기 요청 빌드
   LPMInitRequest *initRequest = [requestBuilder build];
   // 준비된 요청으로 레벨플레이 초기화
   [레벨플레이 initWithRequest:initRequest 완료:^(LPMConfiguration *_Nullable config, NSError *_Nullable error){
       if(error) {
           // 초기화 시 오류가 발생했습니다. 필요한 조치를 취하거나 재시도
       } else {
           // 초기화가 성공했습니다. 이제 배너 광고를 로드하거나 다른 작업을 수행할 수 있습니다.
       }
   }];
   ```

2) **Swift**

   ```swift
   // 앱 키로 요청 빌더를 생성합니다. 사용 가능한 경우 사용자 ID 추가
   let requestBuilder = LPMInitRequestBuilder(appKey: "appKey")
           .withUserId("UserId")
   // 초기 요청 빌드
   let initRequest = requestBuilder.build()
   // 준비된 요청으로 레벨플레이 초기화 
   LevelPlay.initWith(initRequest) 
   {config, error in
       if let error = error {
           // 초기화 시 오류가 발생했습니다. 필요한 조치를 취하거나 재시도
       } else {
           // 초기화가 성공했습니다. 이제 광고를 로드하거나 다른 작업을 수행할 수 있습니다.
       }
   }
   ```

### 초기화 결과##initialization-result

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

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

| 컴포넌트    | 레거시                       | 광고 단위(신규)                 |
| ------- | ------------------------- | ------------------------- |
| API     | IronSource.initWithAppKey | LevelPlay.initWithRequest |
| init 결과 | onInitializationComplete  | 완료                        |
|         | –                         | error                     |

## 보상형 광고 만들기##create-rewarded-ad

보상형 광고 오브젝트의 생성은 **완료** 결과를 수신한 후에 수행해야 합니다.

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

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

1. **Objective-C**

   ```objective-c
   // 보상형 광고 만들기
   self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];
   ```

2. **Swift**

   ```swift
   // 보상형 광고 만들기
   self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
   ```

## 보상형 광고 델리게이트 구현##implement-rewarded-delegate

보상형 광고 유닛에 대해 **LPMRewardedAdDelegate**를 구현하여 광고 게재에 대해 알립니다.

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

1. **Objective-C**

   ```objective-c
   // 보상형 광고 만들기
   self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"]; 
   // 델리게이트 구현
   self.rewardedAd.delegate = self;
   #pragma 마크 - LPMRewardedAdDelegate 메서드
   - (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}
   - (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo 오류:(NSError *)오류 {}
   - (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo reward:(LPMReward *)reward {}
   ```

2. **Swift**

   ```swift
   // 보상형 광고 만들기
   self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
   // 델리게이트 구현 
   self.rewardedAd.setDelegate(self)
   // MARK: LPMRewardedAdDelegate 메서드
   func didLoadAd(with adInfo: LPMAdInfo) {}
   func didFailToLoadAd(withAdUnitId adUnitId: 문자열, 오류: 오류) {}
   func didChangeAdInfo(_ adInfo: LPMAdInfo) {}
   func didDisplayAd(with adInfo: LPMAdInfo) {}
   func didFailToDisplayAd(with adInfo: LPMAdInfo, 오류: 오류) {}
   func didClickAd(with adInfo: LPMAdInfo) {}
   func didCloseAd(with adInfo: LPMAdInfo) {}
   func didRewardAd(with adInfo: LPMAdInfo, reward: LPMReward) {}
   ```

### 레벨플레이 보상형 광고 광고 이벤트##levelplay-rewarded-ad-events

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

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

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

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

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

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

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

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

| 컴포넌트  | 레거시                         | 광고 단위(신규)             |
| ----- | --------------------------- | --------------------- |
| 델리게이트 | LevelPlayRewardedAdDelegate | LPMRewardedAdDelegate |
| 이벤트   | onAdReady                   | didLoadAd             |
|       | onAdLoadFailed              | didFailToLoadAd       |
|       | onAdOpened                  | didDisplayAd          |
|       | onAdClosed                  | didCloseAd            |
|       | onAdShowFailed              | didFailToDisplayAd    |
|       | onAdRewarded                | didRewardAd           |
|       | onAdClicked                 | didClickAd            |
|       | onAdShowSucceeded           | – (사용 중단 예정)          |
|       | –                           | didChangeAdInfo       |

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

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

1. **Objective-C**

   ```objective-c
   // 광고를 로드하거나 다시 로드합니다.
   [self.rewardedAd loadAd];
   ```

2. **Swift**

   ```swift
   // 광고를 로드하거나 다시 로드합니다.
   self.rewardedAd.loadAd()
   ```

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

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

1. **Objective-C**

   ```objective-c
   // 플레이스먼트 없이 표시 
   [self.rewardedAd showAdWithViewController:self placementName:nil];
   // 플레이스먼트로 표시 
   [self.rewardedAd showAdWithViewController:self placementName:placementName];
   ```

2. **Swift**

   ```swift
   // 플레이스먼트 없이 표시 
   self.rewardedAd.showAd(viewController: self, placementName: nil)
   // 플레이스먼트로 표시 
   self.rewardedAd.showAd(viewController: self, placementName: placementName)
   ```

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

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

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

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

1. **Objective-C**

   ```objective-c
   // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
   if ([self.rewardedAd isAdReady] && ![LPMRewardedAd isPlacementCapped:placementName]) {
       [self.rewardedAd showAdWithViewController:self placementName:placementName];
   }
   ```

2. **Swift**

   ```swift
   // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
   if self.rewardedAd.isAdReady(), !LPMRewardedAd.isPlacementCapped(placementName) {
       self.rewardedAd.showAd(viewController: self, placementName: placementName)
   }
   ```

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

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

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

**didRewardAd**와 **didCloseAd**는 비동기입니다. **didCloseAd** 이후에 **didRewardAd**가 작동하는 경우에도 보상을 부여하도록 리스너를 설정해야 합니다.

1. **Objective-C**

   ```objective-c
   - (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo 보상(LPMReward *) 보상 {
       // 로직을 구현하여 사용자 보상을 부여합니다.
       NSString *name = reward.name; 
       NSInteger *amount = reward.amount;
   }
   ```

2. **Swift**

   ```swift
   func didRewardAd(with adInfo: LPMAdInfo, reward: LPMReward) {
   // 로직을 구현하여 사용자 보상을 부여합니다.
   이름: String = reward.name 
   릿 금액: Int = reward.amount
   }
   ```

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

|     | 레거시                            | 광고 단위(신규)         |
| :-- | :----------------------------- | :---------------- |
| 클래스 | 아이언소스(IronSource)              | LPMRewardedAd     |
| API | loadRewardedVideo              | loadAd            |
|     | showRewardedVideo              | showAd            |
|     | isRewardedVideoPlacementCapped | isPlacementCapped |
|     | isRewardedVideoAvailable       | isAdReady         |
|     | placement.getRewardName        | reward.name       |
|     | placement.getRewardAmount      | reward.amount     |

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

1. **Objective-C**

   ```objective-c
   NS_ASSUME_NONNULL_BEGIN
   @interface RewardedAdViewController () <LPMRewardedAdDelegate>
   @properties(nonatomic, strong) LPMRewardedAd *rewardedAd;
   @end
   @implementation RewardedAdViewController
   - (void)createRewardedAd {
       self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];
       self.rewardedAd.delegate = self;
   }
   - (void)loadRewardedAd {
       // 광고를 로드하거나 다시 로드합니다.
       [self.rewardedAd loadAd];
   }
   - (void)showRewardedAd {
     if ([self.rewardedAd isAdReady]) {
       [self.rewardedAd showAdWithViewController:self placementName:NULL];
     }
   }
   - (void)showRewardedAdWithPlacementName:(NSString *)placementName {
       // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
       if ([self.rewardedAd isAdReady] &amp;&amp; ![LPMRewardedAd isPlacementCapped:placementName]) {
           [self.rewardedAd showAdWithViewController:self 
           placementName:placementName];
     }
   }
   #pragma 마크 - LPMRewardedAdDelegate 메서드
   - (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}
   - (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo 오류:(NSError *)오류 {}
   - (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}
   - (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo reward:(LPMReward *)reward {}
   @end
   NS_ASSUME_NONNULL_END
   ```

2. **Swift**

   ```swift
   클래스 RewardedAdViewController: UIViewController, LPMRewardedAdDelegate {
   var rewardedAd: LPMRewardedAd!
   func createRewardedAd() {
       self.rewardedAd = LPMRewardedAd(adUnitId: "adUnitId")
       self.rewardedAd.setDelegate(self)
   }
   func loadRewardedAd() {
       // 광고를 로드하거나 다시 로드합니다.
       self.rewardedAd.loadAd()
   }
   func showRewardedAd() {
       if self.rewardedAd.isAdReady() {
           self.rewardedAd.showAd(viewController: self, placementName: nil)
       }
   }
   func showRewardedAd(withPlacementName placementName): 문자열) {
       // 광고가 준비되었는지, 플레이스먼트가 제한되지 않았는지 확인합니다. 
       if self.rewardedAd.isAdReady(), !LPMRewardedAd.isPlacementCapped(placementName) {
           self.rewardedAd.showAd(viewController: self, placementName: placementName)
       }
   }

   // MARK: LPMRewardedAdDelegate methods
   func didLoadAd(with adInfo: LPMAdInfo) {}
   func didFailToLoadAd(withAdUnitId adUnitId: 문자열, 오류: 오류) {}
   func didChangeAdInfo(_ adInfo: LPMAdInfo) {}
   func didDisplayAd(with adInfo: LPMAdInfo) {}
   func didFailToDisplayAd(with adInfo: LPMAdInfo, 오류: 오류) {}
   func didClickAd(with adInfo: LPMAdInfo) {}
   func didCloseAd(with adInfo: LPMAdInfo) {}
   func didRewardAd(with adInfo: LPMAdInfo, reward: LPMReward) {}
   }
   ```