Integration guide for iOS (Objective C)
이 가이드에서는 Unity로 제작된 게임에서 Unity Ads를 구현하는 기본적인 통합 방법을 소개합니다.
Unity의 수익화 플랫폼은 강력한 수익 툴을 제공합니다. 만약 게임에서 광고 외에 인앱 구매도 사용한다면, Unity의 머신러닝 데이터 모델이 콘텐츠 유형을 매끄럽게 혼합하여 수익화 전략을 최적화할 수 있습니다. Unity로 수익을 최적화하는 방법에 대한 자세한 내용은 개인화 플레이스먼트 참고 문서를 참조하세요.
이 가이드는 다음의 내용을 다룹니다.
- 기본 광고 구현
- 보상형 광고 구현
- 배너 광고 구현
- 구현 사항 테스트
- 고급 수익화 제안 사항
- API 레퍼런스
아직 UDN 계정이 없다면 여기에서 계정을 생성하세요. 이미 계정이 있으시다면 아래 과정을 따라 Unity 프로젝트를 생성하실 수 있습니다.
- Developer Dashboard에 로그인하고 Operate 탭으로 이동합니다.
- 왼쪽 내비게이션에서 Projects(프로젝트)를 선택합니다.
- 오른쪽 상단에 있는 NEW PROJECT 버튼을 클릭합니다.
프로젝트를 선택하여 프로젝트의 게임 ID를 찾은 다음, 내비게이션에서 Monetization > Platforms를 선택합니다. Apple App Store Game ID를 복사합니다. 이는 게임에서 Unity Ads 서비스를 활성화하는 데 필요합니다.
플레이스먼트는 수익화 콘텐츠를 표시하는 게임 내 트리거 이벤트입니다. Developer Dashboard의 Operate 탭에서 프로젝트를 선택한 다음 왼쪽 내비게이션에서 Monetization > Placements를 선택하면 플레이스먼트를 관리할 수 있습니다.
ADD PLACEMENT 버튼을 클릭하면 플레이스먼트 생성 대화창이 나타납니다. 플레이스먼트 이름을 지정하고 유형을 선택하십시오.
- 기본 삽입 광고 또는 홍보 콘텐츠를 표시하려면 Non-rewarded를 선택합니다. Non-rewarded(비보상형) 플레이스먼트의 경우에는 플레이어가 지정된 시간이 지나면 광고를 건너뛸 수 있습니다.
- 플레이어가 광고 보기를 선택하고 보상을 받도록 하려면 Rewarded를 선택합니다. Rewarded(보상형) 플레이스먼트의 경우에는 플레이어가 광고를 건너뛰지 못합니다.
- 전용 배너 광고 플레이스먼트를 생성하려면 Banner를 클릭합니다.
Unity Ads가 활성화된 모든 프로젝트는 ‘video’(비보상형) 및 ‘rewardedVideo’(보상형) 플레이스먼트를 기본값으로 갖습니다. 필요에 따라 이 두 가지 중 하나를 첫 구현에 자유롭게 사용할 수 있으며, 아니면 직접 생성할 수도 있습니다.
여기에서 Unity Ads 프레임워크를 다운로드할 수 있습니다. UnityMonetization API는 SDK 3.0 이상 버전이 필요합니다.
- 프레임워크를 드래그 앤 드롭으로 Unity Project 폴더에 옮기고 복사하십시오.
- ViewController 헤더(.h)에서, Unity Ads를 임포트하고 Unity Ads 델리게이트를 설정하십시오.
#import <UIKit/UIKit.h>
#import <UnityAds/UnityMonetization.h>
@interface ViewController : UIViewController<UnityMonetizationDelegate, UMONShowAdDelegate>
@endSDK를 초기화하려면, 해당 플랫폼의 프로젝트에 있는 게임 ID를 참조해야 합니다. ID는 Developer Dashboard의 Operate 탭에서 프로젝트를 선택한 다음, 왼쪽 내비게이션에서 Monetization > Platforms를 선택하여 찾을 수 있습니다.
ViewController 구현부(.m)에서, setDelegate 메서드를 사용하여 수익화 델리게이트를 설정합니다. 다음으로 initialize 메서드를 호출하여 게임 런타임 수명주기의 초반에, 광고 표시 시점 이전에 SDK를 초기화합니다. 예를 들면 다음과 같습니다.
#import "ViewController.h"
@implementation ViewController
- (void) viewDidLoad {
[super viewDidLoad];
[UnityMonetization initialize : @"1234567" delegate : self testMode : true];
}
@endPlacementContent는 플레이스먼트가 표시할 수 있는 수익화 콘텐츠를 나타내는 오브젝트입니다. 자세한 내용은 콘텐츠 유형 및 개인화 플레이스먼트 참고 문서를 참조하세요.
UMONPlacementContent는 수익화 콘텐츠를 대표하며 플레이스먼트에서 표시할 수 있는 오브젝트입니다. 자세한 내용은 콘텐츠 유형 및 개인화 플레이스먼트를 참조하세요. 표시할 준비가 되었을 때 UnityMonetizationDelegate 델리게이트의 placementContentReady 함수를 사용하여 콘텐츠를 가져오고 show 함수로 콘텐츠를 표시합니다. 예를 들면 다음과 같습니다.
@interface ViewController : UIViewController <UnityMonetizationDelegate, UMONShowAdDelegate>
@property (strong) NSString* activePlacementId;
@end
@implementation ViewController
-(void) viewDidLoad {
[super viewDidLoad];
self.activePlacementId = @"video”;
[UnityMonetization initialize: @"1234567" delegate: self testMode: YES];
}
-(void) showInterstitial {
// Check if PlacementContent is ready:
if ([self.interstitialVideo ready]) {
// Show PlacementContent:
[self.interstitialVideo show: self]
}
}
@end광고를 보는 플레이어를 보상하면 사용자 참여가 증가하고 더욱 높은 수익으로 이어질 수 있습니다. 예를 들어, 게임 내 화폐나 소모품, 추가 생명, 경험치 증가 등의 보상이 있습니다. 보상형 광고를 효과적으로 설계하는 방법에 관한 자세한 내용은 광고 베스트 프랙티스 참고 문서를 참조하세요.
광고를 보는 플레이어를 보상하려면, 기본 구현 섹션에 자세히 설명된 동일한 과정을 수행하십시오. 단, 광고 시청을 완료하는 플레이어를 위한 커스텀 로직으로 보상 콜백 메서드를 사용하여 광고를 표시해야 합니다.
보상형 광고는 반드시 보상형 플레이스먼트를 통해서 표시해야 합니다. Unity Ads가 활성화된 모든 프로젝트는 ‘rewardedVideo’ 플레이스먼트를 기본값으로 갖습니다. 이것을 자유롭게 구현에 이용할 수 있으며, 아니면 직접 생성할 수도 있습니다. 단, 플레이스먼트를 반드시 보상형으로 구성해야 합니다.
show 함수는 델리게이트를 사용하여 광고의 UnityAdsFinishState를 반환합니다. 이 결과는 플레이어가 광고를 끝까지 시청했는지 아니면 건너뛰었는지를 나타냅니다. 이 정보를 이용하여 각 시나리오별로 핸들링 방법에 관해 커스텀 함수를 작성하십시오. 예를 들면 다음과 같습니다.
@interface ViewController : UIViewController <UnityMonetizationDelegate, UMONShowAdDelegate>
@property (strong) NSString* interstitialPlacementId;
@property (strong) NSString* rewardedPlacementId;
@property (strong) UMONPlacementContent* interstitialVideo;
@property (strong) UMONPlacementContent* rewardedVideo;
@end
@implementation ViewController
-(void) viewDidLoad {
[super viewDidLoad];
self.interstitialPlacementId = @"video”;
self.rewardedPlacementId = @"rewardedVideo”;
[UnityMonetization initialize: @"1234567" delegate: self testMode: YES];
}
-(void) showInterstitialVideo {
if ([self.interstitialVideo ready]) {
[self.interstitialVideo show: self withDelegate: self]
}
}
-(void) showRewardedVideo {
if ([self.rewardedVideo ready]) {
[self.rewardedVideo show: self withDelegate: self];
}
}
// Implement the delegate for retrieving PlacementContent:
#pragma mark: UnityMonetizationDelegate
-(void) placementContentReady: (NSString *) placementId placementContent: (UMONPlacementContent *) placementContent {
// Check and set the available PlacementContent:
if ([placementId isEqualToString: self.interstitialPlacementId]) {
self.interstitialVideo = placementContent;
} else if ([placementId isEqualToString: self.rewardedPlacementId]) {
self.rewardedVideo = placementContent;
}
}
-(void) placementContentStateDidChange: (NSString *) placementId placementContent: (UMONPlacementContent *) decision previousState: (UnityMonetizationPlacementContentState) previousState newState: (UnityMonetizationPlacementContentState) newState {
if (newState != kPlacementContentStateReady) {
// Disable showing ads because content isn’t ready anymore
}
}
-(void) unityServicesDidError: (UnityServicesError) error withMessage: (NSString *) message {
NSLog (@"UnityMonetization ERROR: %ld - %@", (long) error, message);
}
// Implement the delegate for handling the ad’s finishState
#pragma mark: UMONShowAdDelegate
-(void) unityAdsDidStart: (NSString *) placementId {
// (Optional) Log or perform some action when the ad starts
NSLog (@"Unity ad started for: %@", placementId);
}
-(void) unityAdsDidFinish: (NSString *) placementId withFinishState: (UnityAdsFinishState) finishState {
// If the ad played in its entirety, and the Placement is rewarded, perform reward logic:
if (finishState == kUnityAdsFinishStateCompleted
&& [placementId isEqualToString:self.rewardedPlacementId]) {
// Reward player for watching the entire video
}
}
@end일반적으로 보상형 광고는 플레이어가 광고 보기를 선택하도록 유도하는 버튼을 이용합니다. 버튼을 포함하도록 상기 예제 스크립트를 수정하는 일은 간단히 추가 변수를 선언하고 버튼이 눌릴 때 showRewardedVideo를 호출하는 함수를 작성하는 방법으로 가능합니다.
@property (strong) UIButton* rewardedVideoButton;
-(void) onRewardedVideoButtonTap {
[self.showRewardedVideo];
}배너 광고는 특정 유형의 전용 배너 플레이스먼트가 필요합니다. 현재 배너는 화면 중앙 하단에 고정되어 표시됩니다.
코드를 ViewController 구현부(.m)에 추가하십시오. 다음 스크립트 샘플은 배너 광고를 표시하는 구현 예제입니다. 참조되는 클래스의 자세한 내용은 UnityAdsBanner API 섹션을 참조하세요.
@interface ViewController: UIViewController <UnityAdsBannerDelegate>
@property (copy, nonatomic) NSString* bannerPlacementId;
@end
@implementation ViewController
-(void) viewDidLoad {
[super viewDidLoad];
[UnityAdsBanner setDelegate: self];
[UnityAds initialize: @"1234567" delegate: nil testMode: YES];
}
// If the Placement is ready, load the banner:
-(void) loadBanner {
if ([UnityAds isReady: self.bannerPlacementId]) {
[UnityAdsBanner loadBanner: self.bannerPlacementId];
}
}
-(void) unloadBanner {
[UnityAdsBanner destroy];
}
-(void) unityAdsBannerDidClick: (NSString *) placementId {
// Define behavior for the player clicking the banner.
}
-(void) unityAdsBannerDidError: (NSString *) message {
// Define behavior for an error occurring within the banner.
// Consider the banner unloaded.
}
-(void) unityAdsBannerDidHide: (NSString *) placementId {
// The banner was hidden due to being removed from the view hierarchy or the window changing
}
-(void) unityAdsBannerDidShow: (NSString *) placementId {
// The banner entered the view hierarchy and is visible to the user
}
// The banner loaded and is available to show:
-(void) unityAdsBannerDidLoad: (NSString *) placementId view: (UIView *) view {
// Store the bannerView for later:
self.bannerView = view;
// Add the banner into your view hierarchy:
[self.view addSubview:self.bannerView];
}
// The banner was destroyed, so references can be removed:
-(void) unityAdsBannerDidUnload: (NSString *) placementId {
self.bannerView = nil;
}
@end게임을 퍼블리시하기 전에 다음의 과정을 따라 테스트 모드를 활성화하십시오.
- 먼저 Developer Dashboard의 Operate 탭에서 프로젝트를 선택합니다.
- 왼쪽 내비게이션에서 Monetization > Platforms를 선택합니다.
- 원하는 플랫폼을 지정하고 SETTINGS 탭을 선택합니다.
- 아래로 스크롤하여 TEST MODE 섹션에서 override client test mode로 토글한 다음 Force test mode ON 라디오 버튼을 선택합니다.
프로젝트를 실행하고 광고가 잘 구현되었는지 테스트합니다.
참고: 광고가 잘 통합되었는지 테스트하기 전에 테스트 모드를 활성화해야만 부정행위로 적발되는 것을 방지할 수 있습니다.
축하합니다. 이제 Unity Ads를 구현하셨습니다! 유니티의 목표는 사용자가 간편한 방법으로 수익을 최대화하는 것입니다. 이 점을 염두에 두고 다음 단계들을 살펴보십시오.
- 게임에서 인앱 구매를 사용한다면 Android용 구매 통합을 사용하여 IAP Promo를 구현하고 인앱 구매를 홍보하세요.
- Ads와 IAP Promo가 준비되었다면 개인화 플레이스먼트를 사용하여 광고와 IAP 전략을 강화하고 전체 게임의 수익 상승을 노려 보세요.
- 여기 베스트 프랙티스 가이드를 통해서 효율적인 광고를 설계하는 원리와 방법을 이해할 수 있습니다.
이 클래스를 사용하여 Unity Services를 초기화합니다.
런타임 시 게임에서 Unity Ads를 초기화합니다. 오류를 방지하려면 초기화는 게임 런타임 수명주기의 초반에, 가능하다면 부팅 시점에 수행하는 것이 좋습니다. 초기화는 광고 표시 시점 이전에 이루어져야 합니다.
+ (void) initialize: (NSString *) gameId
delegate: (nullable id <UnityServicesDelegate>) delegate;
testMode: (BOOL) testMode;그리고 gameID 파라미터는 Developer Dashboard에서 확인할 수 있는 프로젝트의 게임 ID입니다. delegate 파라미터는 UnityAdsDelegate 콜백의 델리게이트입니다. testMode 파라미터는 게임이 테스트 모드 상태인지를 나타냅니다. testMode가 ‘YES’이면, 테스트 광고만 볼 수 있습니다. testMode가 ‘NO’이면, 라이브 광고를 볼 수 있습니다. 게임 출시 전까지는 테스트 모드를 사용하여 부정행위로 적발되는 것을 방지하는 것이 좋습니다.
게임이 테스트 모드 상태인지 확인하거나 설정하는 메서드입니다.
+ (BOOL) getDebugMode;
+ (void) setDebugMode: (BOOL) enableDebugMode;getDebugMode 함수는 게임이 테스트 모드일 때 ‘YES’를 반환합니다. ‘SetDebugMode’ 함수를 통해 ‘YES’를 전달하면 테스트 모드를 활성화할 수 있고, ‘NO’를 전달하면 테스트 모드를 비활성화할 수 있습니다.
현재 장치가 Unity Ads를 지원하는지 확인합니다.
+ (BOOL) isSupported;장치에서 Unity Ads를 지원하는 경우 YES를 반환하고 그렇지 않으면 NO를 반환합니다.
이 Unity Ads SDK의 문자열 버전을 반환합니다.
+ (NSString *) getVersion;Unity Ads가 초기화되었는지 확인합니다. 초기화 문제 디버그 시 유용할 수 있습니다.
+ (BOOL) isInitialized;Unity Ads가 초기화되었다면 YES를, 그렇지 않으면 NO를 반환합니다.
플레이스먼트 상태와 콘텐츠를 처리하는 델리게이트를 구현하는 정적 클래스입니다.
@interface UnityMonetization: NSObject
+ (void) setDelegate: (id <UnityMonetizationDelegate>) delegate;
+ (nullable id <UnityMonetizationDelegate>) getDelegate;
+ (BOOL) isReady: (NSString *) placementId;
+ (nullable UMONPlacementContent *) getPlacementContent: (NSString *) placementId;
@end이 델리게이트를 구현하고 다시 SDK에 전달합니다.
placementContentReady
이 함수는 해당 플레이스먼트에서 UMONPlacementContent 오브젝트를 이용할 수 있으며 표시할 준비가 되었다는 것을 사용자에게 알립니다.
- (void) placementContentReady: (NSString *) placementId placementContent: (UMONPlacementContent *) decision;placementContentStateDidChange
이 함수는 준비된 UMONPlacementContent 오브젝트의 상태가 새로고침으로 인해 변경된 시간을 알립니다.
-(void) placementContentStateDidChange: (NSString *) placementId placementContent: (UMONPlacementContent *) placementContent previousState: (UnityMonetizationPlacementContentState) previousState newState: (UnityMonetizationPlacementContentState) newState;UnityMonetizationDelegate 구현 예제
@interface MyMonetizationDelegate <UnityMonetizationDelegate>
@end
@implementation MyMonetizationDelegate
-(void) placementContentReady:(NSString *)placementId placementContent:(UMONPlacementContent *)placementContent {
if ([placementId isEqualToString:@"video"]) {
self.interstitial = placementContent;
} else if ([placementId isEqualToString:@"rewardedVideo"]) {
self.rewardedVideo = placementContent;
}
}
-(void) placementContentStateDidChange:(NSString *) placementId placementContent: (UMONPlacementContent *) decision previousState: (UnityMonetizationPlacementContentState) previousState newState: (UnityMonetizationPlacementContentState) newState {
if (newState != kPlacementContentStateReady) {
// Disable showing ads because content isn’t ready anymore
}
}
@end플레이스먼트가 표시할 수 있는 수익화 콘텐츠를 나타내는 오브젝트입니다.
이 함수는 콘텐츠가 표시할 준비가 되었을 때 'YES'를, 그렇지 않으면 'NO'를 반환합니다.
이 기능은 표시할 수 있는 UMONPlacementContent의 유형을 반환합니다.
@property (nonatomic, readonly) NSString *type;다음 문자열 값이 유효합니다.
| 문자열 값 | 설명 |
|---|---|
SHOW_AD |
UMONShowAdPlacementContent 클래스 확장자를 사용하는 동영상 광고 콘텐츠를 나타냅니다. |
PROMO_AD |
UMONPromoAdPlacementContent 클래스 확장자를 사용하는 IAP Promo 콘텐츠를 나타냅니다. |
NO_FILL |
지정된 플레이스먼트에 이용할 수 있는 UMONPlacementContent가 없음을 나타냅니다. |
보상형 콘텐츠를 지원하는 기능을 포함하도록 UMONPlacementContent 클래스를 확장합니다.
이 함수는 UMONPlacementContent가 보상되었을 경우 ‘YES’를, 그렇지 않으면 ‘NO’를 반환합니다.
@property (nonatomic) BOOL rewarded;동영상 광고 콘텐츠를 지원하는 기능을 포함하도록 UMONRewardablePlacementContent 클래스를 확장합니다.
이 함수는 이용할 수 있는 UMONShowAdPlacementContent를 표시합니다. UMONShowAdDelegate 인터페이스를 구현하면 이 함수가 각 광고 UnityAdsFinishState에 응답하는 방법을 정의할 수 있습니다.
-(void) show: (UIViewController *) viewController withDelegate: (id <UMONShowAdDelegate>) delegate;이 인터페이스를 구현하면 동영상 광고의 unityAdsDidFinish에 대한 UnityAdsFinishState 콜백 메서드를 제공할 수 있습니다.
이 메서드를 구현하면 광고를 끝까지 시청했는지, 건너뛰었는지, 아니면 오류가 나서 중단되었는지에 대한 핸들링 로직을 제공할 수 있습니다.
-(void) unityAdsDidFinish: (NSString*) placementId withFinishState: (UnityAdsFinishState) finishState;UnityAdsFinishState
종료 시 광고의 최종 상태를 제시하는 enum입니다. 보상 사례를 핸들링하는 데 사용합니다.
| 값 | 설명 |
|---|---|
kUnityAdsFinishStateCompleted |
플레이어가 광고를 끝까지 보았습니다. |
kUnityAdsFinishStateSkipped |
플레이어가 광고를 끝까지 보기 전에 건너뛰었습니다. |
kUnityAdsFinishStateError |
광고를 로드하지 못했습니다. |
unityAdsDidFinish 구현 예제
- (void) unityAdsDidFinish: (NSString *) placementId withFinishState: (UnityAdsFinishState) finishState {
NSLog (@"UnityAds FINISH: %@", placementId);
if (finishState == kUnityAdsFinishStateCompleted && [placementId isEqualToString: @"rewardedVideo"]) {
// Reward the player
((UMONShowAdPlacementContent *) self.rewardedContent).rewarded = YES;
NSLog (@"Reward the player");
}
}UMONShowAdPlacementContent 클래스를 확장하여, IAP Promo 콘텐츠에 대한 기능을 제공합니다. 자세한 내용은 네이티브 Promo 참고 문서를 참조하십시오.
광고 배너를 핸들링하고, 보여주고, 숨길 수 있는 정적 클래스입니다.
배너 광고 콘텐츠를 로드하는 기본 메서드입니다. 필요에 따라 몇 가지 파라미터를 이용하여 이 함수를 조정할 수 있습니다.
| 메서드 | 설명 |
|---|---|
+(void) loadBanner |
Developer Dashboard에 정의된 기본값 플레이스먼트 ID로 배너 광고를 로드합니다. |
+(void) loadBanner: (NSString *) placementId |
특정 플레이스먼트 ID로 배너 광고를 로드합니다. |
예를 들면 다음과 같습니다.
-(void) loadBanner {
if ([UnityAds isReady: self.bannerPlacementId]) {
[UnityAdsBanner loadBanner: self.bannerPlacementId];
}
}배너 광고를 파기하고 view 계층 구조에서 제거한 다음 플레이어에게 숨깁니다.
+(void) destroy;Unity Ads가 배너 콜백을 전송할 수 있도록, 지정된 UnityAdsBannerDelegate를 설정하거나 가져옵니다.
+(nullable id <UnityAdsBannerDelegate>) getDelegate;
+(void)setDelegate: (id <UnityAdsBannerDelegate>) delegate;콜백에 대해 이 델리게이트를 구현하고 [UnityAdsBanner setDelegate]로 전달합니다.
이 콜백은 배너 광고가 로드되고 표시 준비가 되었을 때 작동합니다. 여기에서 view는 view 계층 구조에 배치되는 View입니다. 예를 들면 다음과 같습니다.
-(void) unityAdsBannerDidLoad: (NSString *) placementId view: (UIView *) view {
// Store the bannerView for later:
self.bannerView = view;
// Add the banner into your view hierarchy:
[self.view addSubview:self.bannerView];
}이 콜백은 [UnityBanners destroy] 시 작동하여, 배너가 완전히 파기되었고 레퍼런스를 제거할 수 있음을 알립니다(예: unityAdsBannerDidLoad에 제공된 view 제거).
-(void) unityAdsBannerDidUnload: (NSString *) placementId {
self.bannerView = nil;
}이 콜백은 배너 광고가 view 계층 구조에 들어갔고 플레이어에게 보일 때 작동합니다.
-(void) unityAdsBannerDidShow: (NSString *) placementId;이 콜백은 배너 광고가 view 계층 구조에서 제거되거나 창 변경으로 인해 플레이어에게 숨겨질 때 작동합니다.
-(void) unityAdsBannerDidHide: (NSString *) placementId;이 콜백은 플레이어가 배너 광고를 클릭했을 때 작동합니다.
-(void) unityAdsBannerDidClick: (NSString *) placementId;이 콜백은 UnityAdsBanner에 오류가 발생했을 때 작동합니다. 기본적으로 모든 오류가 기록되지만 이 메서드는 디버깅 시 추가적인 도움을 제공할 수 있습니다. 또한 이 콜백을 사용하여 다른 오류 시나리오의 통계를 수집할 수도 있습니다.
-(void) unityAdsBannerDidError: (NSString *) message;