iOS에서의 보상형 동영상 광고 연동

아이언소스의 보상형 동영상 광고 유닛은 광고 영상을 모두 시청한 사용자들에게 가치있는 앱 내의 가상 컨텐츠를 보상하는 매력적인 광고 경험을 제공합니다. 이러한 사용자 주도 방식의 광고 유닛이 게임 앱에서 가장 돋보이지만, 그 외에도 모든 앱의 사용 경험을 한층 더 끌어올릴 수 있습니다.

시작하기 전에
아이언소스 SDK와 추가 광고 네트워크 아답터들이 올바르게 대상 앱에 연동되었는지 확인해주세요. 연동과정에 대한 설명은 여기에 있습니다.

1단계. 보상형 동영상 광고 대리자(Delegate) 구현하기

아이언소스 SDK는 사용자 보상이 언제 이루어져야하는지 알 수 있도록 여러가지 이벤트를 송출하여 광고 제공가능 여부 및 완료 여부 정보를 전달합니다.

SDK에서 대리자(Delegate)로 송출되는 발생 가능한 이벤트들은 아래와 같습니다:


+ (void)setLevelPlayRewardedVideoDelegate:(nullable id<LevelPlayRewardedVideoDelegate>)delegate;
#pragma mark - LevelPlayRewardedVideoDelegate
/**
 Called after a rewarded video has changed its availability to true.
 @param adInfo The info of the ad.
 Replaces the delegate rewardedVideoHasChangedAvailability:(true)available 
 */
- (void)hasAdAvailableWithAdInfo:(ISAdInfo *)adInfo{
}
/**
 Called after a rewarded video has changed its availability to false.
 Replaces the delegate rewardedVideoHasChangedAvailability:(false)available 
 */
- (void)hasNoAvailableAd{
}
/**
 Called after a rewarded video has been viewed completely and the user is eligible for a reward.
 @param placementInfo An object that contains the placement's reward name and amount.
 @param adInfo The info of the ad.
 */
- (void)didReceiveRewardForPlacement:(ISPlacementInfo *)placementInfo withAdInfo:(ISAdInfo *)adInfo {
}
/**
 Called after a rewarded video has attempted to show but failed.
 @param error The reason for the error
 @param adInfo The info of the ad.
 */
- (void)didFailToShowWithError:(NSError *)error andAdInfo:(ISAdInfo *)adInfo {
}
/**
 Called after a rewarded video has been opened.
 @param adInfo The info of the ad.
 */
- (void)didOpenWithAdInfo:(ISAdInfo *)adInfo {
}
/**
 Called after a rewarded video has been dismissed.
 @param adInfo The info of the ad.
 */
- (void)didCloseWithAdInfo:(ISAdInfo *)adInfo {
}
/**
 Called after a rewarded video has been clicked. 
 This callback is not supported by all networks, and we recommend using it 
 only if it's supported by all networks you included in your build
 @param adInfo The info of the ad.
 */
- (void)didClick:(ISPlacementInfo *)placementInfo withAdInfo:(ISAdInfo *)adInfo {
}

IronSource.setLevelPlayRewardedVideoDelegate(delegate: LevelPlayRewardedVideoDelegate?)

// MARK: - LevelPlayRewardedVideoDelegate

/**
 Called after a rewarded video has changed its availability to true.
 @param adInfo The info of the ad.
 Replaces the delegate rewardedVideoHasChangedAvailability(available: bool=true)
 */
func hasAvailableAd(with adInfo: ISAdInfo!) {
}

/**
 Called after a rewarded video has changed its availability to false.
 Replaces the delegate rewardedVideoHasChangedAvailability:(available: bool=false)
 */
func hasNoAvailableAd() {
}

/**
 Called after a rewarded video has been viewed completely and the user is eligible for a reward.
 @param placementInfo An object that contains the placement's reward name and amount.
 @param adInfo The info of the ad.
 */
func didReceiveReward(forPlacement placementInfo: ISPlacementInfo!, with adInfo: ISAdInfo!) {
}

/**
 Called after a rewarded video has attempted to show but failed.
 @param error The reason for the error
 @param adInfo The info of the ad.
 */    
func didFailToShowWithError(_ error: Error!, andAdInfo adInfo: ISAdInfo!) {
}

/**
 Called after a rewarded video has been opened.
 @param adInfo The info of the ad.
 */    
func didOpen(with adInfo: ISAdInfo!) {
}
        
/**
 Called after a rewarded video has been dismissed.
 @param adInfo The info of the ad.
 */ 
func didClose(with adInfo: ISAdInfo!) {
}

/**
 Called after a rewarded video has been clicked. 
 This callback is not supported by all networks, and we recommend using it 
 only if it's supported by all networks you included in your build
 @param adInfo The info of the ad.
 */    
func didClick(_ placementInfo: ISPlacementInfo!, with adInfo: ISAdInfo!) {
}

대리자(Delegate)의 전체 구현은 여기에서 확인하실 수 있습니다.

에러 코드

아이언소스는 SDK는 연동 과정 또는 서비스 제공 중 발생할 수 있는 에러들에 대해서 어떤 에러인지 확인할 수 있도록 에러 코드 메커니즘을 제공합니다. a href=”https://developers.is.com/ironsource-mobile/ios/advanced-settings-2/#step-4″ target=”_blank” rel=”noopener noreferrer”>여기를 참고 부탁 드립니다.

콜백

위의 리스너의 콜백들은 메인스레드 이외의 스레드에서 실행될 수도 있습니다. 아이언소스 SDK의 콜백 결과에 영향받는 UI 상호작용이나 업데이트들은 모두 메인스레드로 넘겨진 후 실행되어야 합니다.

네트워크 연결 상태 감지

아이언소스 SDK의 Network Change Status 기능을 통해 사용자 기기의 인터넷 연결 상태를 확인 및 관찰할 수 있습니다. 본 기능을 활성화하면 아이언소스 SDK는 네트워크 변경사항에 따라 보상형 동영상 광고 준비상태가 변경됩니다. 예를들어, 기기가 인터넷에 연결되지 않은 경우 보상형 동영상 광고 준비상태는 FALSE로 변경됩니다. 본 기능은 기본값으로 비활성화 되어 있습니다. 만약 네트워크 연결상태 변경을 수신하려면, 아이언소스 SDK 초기화 이전에 아래 구문을 통해 활성화 해 주세요:

[IronSource shouldTrackReachability:YES];
IronSource.shouldTrackReachability(true)

2단계. 사용자에게 보상형 동영상 광고 송출

광고 준비 상태

보상형 동영상 광고 대리자(Delegate) 및 대리자의 함수를 정확하게 구현하여 보상형 동영상 광고 준비 상태를 아래의 hasAdAvailableWithAdInfo 대리자 함수를 통해서 받을 수 있습니다. 이후, 아래의 대리자 함수를 통해 광고 준비 상태 변경 사항에 대해 전달받게 됩니다:

/**
*Called after a rewarded video has changed its availability to true
*@param adInfo The info of the ad.
*/
-(void)hasAdAvailableWithAdInfo:(ISAdInfo *)adInfo {
     //Change the in-app 'Traffic Driver' state according to availability.
}
/**
 Called after a rewarded video has changed its availability to true
 @param adInfo The info of the ad.
 */
public func hasAdAvailable(with adInfo: ISAdInfo) {
      //Change the in-app 'Traffic Driver' state according to availability.
}

또는 아래의 함수를 호출하여 직접 보상형 동영상 광고 준비 여부를 확인합니다:

[IronSource hasRewardedVideo];
IronSource.hasRewardedVideo()
Note: 아이언소스 SDK 는 전체 세션 동안 광고 준비 상태 유지를 위해서 보상형 광고 영상을 자동으로 캐싱합니다.

광고 플레이스먼트

아이언소스 광고 플레이스먼트 도구를 사용하여, 보상형 동영상 광고 경험을 최적화하고 커스터마이즈 할 수 있습니다. 이 도구를 사용해서 보상에 따라 다양한 광고 게재 위치에서 사용자에게 보상형 영상을 제공할 수 있습니다. 아래의 함수를 사용하여 광고를 송출할 플레이스먼트를 지정할 수 있습니다. 자세한 정보는, 광고 플레이스먼트 문서에서 찾아 보실 수 있습니다.

각 광고 플레이스먼트와 연결된 특정 보상에 대한 상세 정보를 확인하려면, 아래와 같이 호출해 주세요:

ISPlacementInfo *placementInfo = [IronSource rewardedVideoPlacementInfo:(NSString *)placementName];
if(placementInfo != NULL)
{
	 NSString *rewardName = [placementInfo rewardName];
	 NSNumber *rewardAmount = [placementInfo rewardAmount];
}
let placementInfo = IronSource.rewardedVideoPlacementInfo(placementName: String)
if placementInfo != nil {
	 let rewardName = placementInfo.placementName
	 let rewardAmount = placementInfo.rewardAmount
}
Note: 플레이스먼트 명칭을 위 예제와 같이 파라미터로 사용 시 반드시 레벨플레이 플랫폼 상에서 정의된대로 사용해 주세요.

광고 횟수 제한 및 빈도 제한

아이언소스 광고 플레이스먼트 기능에서는 선택된 플레이스먼트 별로 횟수 제한 및 빈도 제한을 설정할 수 있습니다. 횟수 / 빈도 제한을 사용하여 정의된 시간 간격 내의 광고 송출 횟수를 제한함으로써 유저 경험을 개선할 수 있습니다. 횟수 / 빈도 제한에 대해서는 여기를 참고해 주세요.

Note: 플레이스먼트에 횟수 제한이 있을 경우에 유저에게 광고 시청을 권하는 트래픽 드라이버 (보상형 동영상 시청 버튼) 출력을 방지하기 위해서는, 먼저 아래의 함수를 호출하여 해당 플레이스먼트의 광고 재생이 횟수 제한에 다다랐는지를 확인해야 합니다.
[IronSource isRewardedVideoCappedForPlacement:@"Placement"];
IronSource.isRewardedVideoCapped(forPlacement: String)

광고 준비 여부에 대한 요청에 TRUE 응답을 받아도 해당 광고가 게재되는 플레이스먼트의 광고 게재 횟수 제한에 다다른 경우, 광고는 송출되지 않습니다.

보상형 동영상 광고 송출

광고 네트워크에서 보상형 동영상 광고가 제공 가능하게 되면, 사용자에게 동영상을 보여줄 수 있습니다. 광고를 송출하기 전에, 사용자들에게 최상의 환경을 제공하려면 반드시 오디오 등을 포함한 모든 게임 동작을 일시정지 해주세요.

[IronSource showRewardedVideoWithViewController:(UIViewController *)viewController placement:(nullable NSString *)placementName];
IronSource.showRewardedVideo(with: UIViewController, placement: String?)
Note: placementName 파라미터가 null인 경우, SDK는 아이언소스 플랫폼에 설정된 기본 플레이스먼트 설정값을 가져옵니다.

동적 사용자 ID

동적 사용자 ID는 AdRewarded 콜백 통신을 확인하는 용도의 파라미터이며, 세션 중간에 변경될 수 있습니다. 해당 파라미터를 서버 간 콜백 중에 수신하려면, showRewardedVideo 함수 호출 이전에 아래와 같이 동적 ID가 설정되어야 합니다. 설정하게 되면 콜백 URL에서 상세 보상 정보와 함께 dynamicUserId 파라미터를 수신하게 됩니다.

[IronSource setDynamicUserId:@"DynamicUserId"];
IronSource.setDynamicUserId(dynamicUserId: String);

3단계. 사용자에게 보상 전달하기

사용자에게 성공적으로 보상을 전달하려면 반드시 아이언소스 SDK 초기화 이전에 사용자 ID 설정이 되었는지 확인해 주세요.

아이언소스 SDK는 사용자가 성공적으로 보상형 동영상 광고 시청을 완료할 때마다 didReceiveReward 이벤트를 송출합니다. 보상 이벤트 발생 시, 아래의 delegate 함수를 통해 이에 대한 알림을 받습니다.

// Called after a rewarded video has been viewed completely and the user is
// eligible for reward.
// @param placementInfo is an object that contains the placement's reward
// name and amount.
// @param adInfo The info of the ad.
- (void)didReceiveRewardForPlacement:(ISPlacementInfo *)placementInfo withAdInfo:(ISAdInfo *)adInfo {
    NSNumber *rewardAmount = [placementInfo rewardAmount];
    NSString *rewardName = [placementInfo rewardName];
}

/**
 Called after a rewarded video has been viewed completely and the user is eligible for a reward.
 @param placementInfo An object that contains the placement's reward name and amount.
 @param adInfo The info of the ad.
 */
func didReceiveReward(forPlacement placementInfo: ISPlacementInfo!, with adInfo: ISAdInfo!) {
    var rewardAmount: Int = placementInfo.rewardAmount
    var rewardName: String = placementInfo.rewardName
}
Note:  didReceiveReward 이벤트와 didClose 이벤트는 서로 비동기적입니다. 반드시 didReceiveReward 이벤트가 didClose 이벤트 이후에 발생해도 보상을 받을 수 있도록 대리자(delegate)를 설정해 주세요.

Placement 오브젝트에는 레벨플레이 플랫폼에서 정의된 해당 Placement의 보상 명칭보상 수량이 포함됩니다:

Note: 아이언소스 계정의 기본 설정은 앱 내의 클라이언트에서 정의된 didReceiveReward 콜백을 통해 유저의 동영상 시청 완료 / 보상 상황을 통지하도록 되어 있습니다. 추가로, 만약 백엔드 서버에서 해당 사항에 대한 통지를 직접 받도록 하려면 서버간 콜백 기능을 켜시면 됩니다.

서버간 콜백

서버간 콜백 기능을 켜실 경우, 반드시 아이언소스 SDK 초기화 이전에 사용자 ID를 설정하여 사용자들이 보상을 받을 수 있도록 하고, 반드시 사용자가 동일한 영상 시청 완료에 대해서는 단 한번만 보상을 받도록 합니다.

아이언소스 레벨플레이 (미디에이션 SDK)는 클라이언트로의 콜백과 서버간 콜백을 동시에 송출합니다. 다시말해, 한 번의 완료 이벤트마다 두 개의 통지를 받게 됩니다.

서버간 콜백의 이용에 대해서는 여기를 읽어주세요.

완료했습니다!
이제 앱에 보상형 동영상 광고를 송출할 준비가 모두 완료되었습니다.

최초 연동을 위한 팁
처음으로 앱에 아이언소스 SDK를 연동하는 경우라면, 해당 앱은 아이언소스 대시보드 상에서 “테스트 모드”로 기본 설정되어 있습니다. 앱이 테스트 모드에서 동작하면, 아이언소스 SDK는 SDK 처리 과정을 좀 더 명확하게 보여주기 위해 콘솔에 더 많은 로그를 출력합니다. 광고 인벤토리 테스트를 위해서는, 테스트 기기를 설정합니다. 상용 광고 인벤토리를 활성화 하기 전까지는 테스트 캠페인의 광고만 수신하게 되며 이 경우 수익은 발생하지 않습니다. 앱이 상용 광고 인벤토리를 사용할 준비가 되었다면, 반드시 아이언소스 플랫폼의 MONETIZE > SETTINGS > Ad Units 페이지로 진입하셔서 Go Live! 를 선택하셔서 상용 광고를 수신할 수 있도록 합니다.
ironsource-rewarded-video-test-ads

다음엔 뭘 할까요?
아래의 연동 가이드들을 따라서 아이언소스 미디에이션 플랫폼의 보상형 동영상 광고 네트워크를 추가로 연동하시거나, 다른 광고 유닛을 설정해 보세요:
You can read this article in: