Unity Ads iOS SDK API 레퍼런스

UnityAds.h 라이브러리를 사용하여 보상형 또는 비보상형 비디오 광고, 인터스티셜 광고, 배너 광고와 같은 기본적인 광고 콘텐츠를 구현합니다.

#import "UnityAds.h"

이 문서에는 다음과 같은 API 기술 자료가 포함되어 있습니다.

클래스

열거형

델리게이트

클래스

UnityAds

#import <UnityAds/UnityAds.h>

이 네임스페이스를 사용하여 보상형 또는 비보상형 비디오 광고, 인터스티셜 광고, 배너 광고와 같은 기본적인 광고 콘텐츠를 구현합니다.

initialize

+ (void) initialize: (NSString *)gameId
    testMode: (BOOL)testMode
    initializationDelegate: (nullable id<UnityAdsInitializationDelegate>)initializationDelegate;
}

지정된 게임 ID, 테스트 모드 상태, 초기화 델리게이트로 Unity Ads 서비스를 초기화합니다.

파라미터

설명

gameId

Unity Ads Monetization 대시보드에서 확인할 수 있는 프로젝트의 플랫폼별 Unity 게임 ID입니다.

testMode

테스트 모드를 사용하면 라이브 광고를 사용하지 않고 연동을 테스트할 수 있습니다. 테스트 모드에서 true를 사용하여 초기화합니다.

initializationDelegate

필요에 따라 UnityAdsInitializationDelegate 콜백과 함께 SDK를 활성화합니다(버전 3.7.0 이상).

load

+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate {   
	[UADSLoadModule.sharedInstance loadForPlacementID: placementId
											  options: options
    									 loadDelegate: loadDelegate];
}

지정된 광고 유닛의 광고 콘텐츠를 로드합니다. show를 호출한 후 load를 호출해야 합니다.

파라미터

설명

placementId

광고 콘텐츠를 로드할 광고 유닛의 ID입니다.

options

광고 로드 동작을 변경할 수 있는 다양한 옵션입니다.

loadDelegate

필요에 따라 UnityAdsLoadDelegate 콜백과 함께 광고 콘텐츠를 로드합니다(버전 3.7.0 이상).

isReady

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

+ (BOOL)isReady: (NSString *)adUnitId {
    return [UnityServices isSupported] && [UnityServices isInitialized] && [UADSPlacement isReady: adUnitId];
}

지정된 광고 유닛에 광고가 표시될 준비가 되었으면 YES를 반환합니다. enablePerPlacementLoad를 활성화하여 SDK를 초기화하는 경우 load를 호출한 후 show를 호출해야 합니다.

파라미터

설명

adUnitId

쿼리할 광고 유닛의 ID입니다.

참고: 광고 유닛 ID를 지정하지 않고 isReady를 호출하는 경우 해당 메서드는 Unity 기본 플레이스먼트의 결과를 반환합니다.

.

show

+ (void)show: (UIViewController *)viewController placementId: (NSString *)placementId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate {
    	[self show: viewController
          adUnitId: placementId
    	   options: [UADSShowOptions new]
   	  showDelegate: showDelegate];
}

지정된 광고 유닛에 로드된 광고 콘텐츠를 표시합니다.

파라미터

설명

placementId

표시할 광고 유닛의 ID입니다.

options

광고 표시 동작을 변경할 수 있는 다양한 옵션입니다.

showDelegate

필요에 따라 UnityAdsShowDelegate 콜백과 함께 콘텐츠를 표시합니다(버전 3.7.0 이상).

참고: 광고 유닛 ID를 지정하지 않고 show를 호출하는 경우 해당 메서드는 Unity 기본 플레이스먼트에 로드된 콘텐츠를 표시합니다. SDK 버전 4.0 이상에서는 광고 유닛 ID를 포함하여 이 메서드를 호출해야 합니다.

addDelegate

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate {
    [UADSProperties addDelegate: delegate];
}

Unity Ads 콜백을 수신할 리스너 델리게이트를 추가합니다. 버전 3.1.0 이상에서는 여러 리스너를 등록할 수 있습니다. 이는 특히 Mediation 고객에게 도움이 됩니다.

파라미터

설명

delegate

Unity Ads 콜백의 리스너입니다.

removeDelegate

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

+ (void)removeDelegate: (id<UnityAdsDelegate>)delegate {
    [UADSProperties removeDelegate: delegate];
}

사용 중인 UnityAdsDelegate 리스너를 제거합니다.

파라미터

설명

delegate

Unity Ads 콜백의 리스너입니다.

setDebugMode

+ (BOOL)getDebugMode {
    return [UnityServices getDebugMode];
}

SDK에서 로깅 출력량을 제어합니다. 더 강력한 로깅을 지원하려면 YES로 설정합니다.

getDebugMode

+ (void)getDebugMode: (BOOL)enableDebugMode {
    [UnityServices setDebugMode: enableDebugMode];
}

SDK가 디버그 모드에 있으면 YES를, 그렇지 않으면 NO를 반환합니다.

getVersion

+ (NSString *)getVersion {
    return [UnityServices getVersion];
}

Unity Ads SDK의 현재 버전을 반환합니다.

isInitialized

+ (BOOL)isInitialized {
    return [USRVSdkProperties isInitialized];
}

SDK가 성공적으로 초기화되었으면 YES를, 그렇지 않으면 NO를 반환합니다.

UADSLoadOptions

#import <UnityAds/UADSBaseOptions.h>

@interface UADSLoadOptions : UADSBaseOptions

@property (nonatomic, readwrite) NSString *adMarkup;

@end

이 클래스에는 load 메서드에 포함할 수 있는 메타데이터 옵션이 있습니다. 타사 Mediation의 헤더 입찰을 사용하는 고객은 Unity 네트워크의 입찰자가 광고 입찰에서 낙찰받는 경우에 대비하여 이 옵션을 사용해야 합니다.

setAdMarkup

- (void)setAdMarkup: (NSString *)adMarkup

이 메서드에서는 입찰자 서비스에서 반환된 광고 마크업을 사용합니다. Unity 광고 네트워크의 입찰자가 헤더 입찰 옥션에서 낙찰받는 경우, Unity Ads SDK는 Mediation 익스체인지에서 광고 마크업을 수신합니다. 이 광고 마크업 문자열에는 Unity에서 광고를 로드하고 표시하는 데 필요한 정보가 포함되어 있습니다.

UADSBannerView

@interface UADSBannerView : UIView

이 클래스를 사용하여 배너 광고를 구현합니다. Unity Ads 버전 3.3 이상에서는 단일 광고 유닛에서 더 많은 복수 배너 인스턴스를 지원합니다.

initWithPlacementId

-(instancetype)initWithPlacementId:(NSString *)placementId size:(CGSize)size;

광고 유닛 ID와 배너 크기를 사용하여 배너 뷰를 구현합니다. initWithPlacementId를 호출하여 오브젝트를 초기화한 다음 load를 호출하여 광고 콘텐츠를 로드합니다. 배너 오브젝트는 해당 UADSBannerViewDelegate 리스너를 통해 라이프사이클 이벤트에 액세스합니다.

파라미터

설명

placementId

배너의 광고 유닛 ID입니다.

size

배너 오브젝트의 크기입니다. 지원되는 최소 크기는 320x50픽셀입니다.

참고: UADSBannerView를 사용하면 배너 호출 시 새로고침 없이 한 번에 콘텐츠를 로드하려고 시도합니다. 배너가 보여줄 광고 없음(no fill) 상태를 반환하면 이를 제거하고 새로 만들어 다시 시도하면 됩니다. Mediation을 사용하는 고객은 이 메서드를 사용하는 것이 좋습니다.

load

- (void)load;

배너에 광고를 요청하는 기본 메서드입니다.

열거형

UnityAdsPlacementState

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)

광고 유닛의 열거형 상태입니다.

설명

kUnityAdsPlacementStateReady

광고 유닛이 광고를 표시할 준비가 되었습니다.

kUnityAdsPlacementStateNotAvailable

광고 유닛을 사용할 수 없습니다.

kUnityAdsPlacementStateDisabled

광고 유닛이 비활성화되었습니다.

kUnityAdsPlacementStateWaiting

광고 유닛이 준비 대기 중입니다.

kUnityAdsPlacementStateNoFill

광고 유닛에 표시할 광고가 없습니다.

UnityAdsFinishState

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

typedef NS_ENUM(NSInteger, UnityAdsFinishState)

사용자와 광고의 상호 작용에 대한 열거형 상태입니다. 광고 시청이 완료되면 SDK가 이 값을 unityAdsDidFinish 콜백 메서드로 전달합니다.

설명

kUnityAdsFinishStateError

Unity 오류로 인해 광고 시청 완료에 실패한 경우를 나타냅니다.

kUnityAdsFinishStateSkipped

사용자가 광고를 건너뛴 경우를 나타냅니다.

kUnityAdsFinishStateCompleted

광고 재생이 완료되었음을 나타냅니다.

UnityAdsInitializationError

typedef NS_ENUM (NSInteger, UnityAdsInitializationError)

SDK 초기화 실패에 대한 열거형 이유입니다.

설명

kUnityInitializationErrorInternalError

개발 환경 또는 내부 서비스로 인해 발생하는 오류입니다.

kUnityInitializationErrorInvalidArgument

Initialize 메서드의 잘못된 인수로 인해 발생하는 오류입니다.

kUnityInitializationErrorAdBlockerDetected

URL 차단으로 인해 발생하는 오류입니다.

UnityAdsLoadError

typedef NS_ENUM (NSInteger, UnityAdsLoadError)

광고 유닛 로드 실패에 대한 열거형 이유입니다.

설명

kUnityAdsLoadErrorInitializeFailed

SDK가 초기화되지 않아 광고를 로드할 수 없습니다.

kUnityAdsLoadErrorInternal

Unity Ads 서비스 오류로 인해 광고를 로드할 수 없습니다.

kUnityAdsLoadErrorInvalidArgument

load 메서드의 잘못된 인수로 인해 광고를 로드할 수 없습니다.

kUnityAdsLoadErrorNoFill

네트워크에서 제공하는 콘텐츠가 없어 광고를 로드할 수 없습니다.

kUnityAdsLoadErrorTimeout

지정된 기간 내에 광고를 로드할 수 없습니다.

UnityAdsShowCompletionState

typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)

광고 완료에 대한 열거형 이유입니다.

설명

kUnityShowCompletionStateSkipped

사용자가 광고를 건너뛴 경우를 나타냅니다.

kUnityShowCompletionStateCompleted

광고를 끝까지 재생했음을 나타냅니다. 이는 일반적으로 사용자가 광고를 끝까지 시청하여 보상을 받을 수 있음을 나타냅니다.

UnityAdsShowError

typedef NS_ENUM (NSInteger, UnityAdsShowError)

광고 유닛의 표시 실패에 대한 열거형 이유입니다.

설명

kUnityShowErrorNotInitialized

SDK가 초기화되지 않아 광고를 표시할 수 없습니다.

kUnityShowErrorNotReady

광고 유닛이 준비되지 않아 광고를 표시할 수 없습니다.

kUnityShowErrorVideoPlayerError

미디어 플레이어 오류로 인해 광고를 표시할 수 없습니다.

kUnityShowErrorInvalidArgument

show 메서드의 잘못된 인수로 인해 광고를 표시할 수 없습니다.

kUnityShowErrorNoConnection

인터넷 연결 오류로 인해 광고를 표시할 수 없습니다.

kUnityShowErrorAlreadyShowing

광고가 이미 표시되고 있어 광고를 표시할 수 없습니다.

kUnityShowErrorInternalError

Unity Ads 서비스 오류로 인해 광고를 표시할 수 없습니다.

UnityAdsError

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

typedef NS_ENUM (NSInteger, UnityAdsError)

unityAdsDidError 콜백을 통해 발생하는 Unity Ads 오류의 열거형 원인입니다.

설명

kUnityAdsErrorNotInitialized = 0

Unity Ads 서비스가 현재 초기화되지 않은 상태입니다.

kUnityAdsErrorInitializedFailed

초기화 과정에서 발생하는 오류입니다.

kUnityAdsErrorInvalidArgument

잘못된 파라미터로 인해 Unity Ads를 초기화하지 못했습니다.

kUnityAdsErrorVideoPlayerError

동영상 플레이어 문제로 인해 발생하는 오류입니다.

kUnityAdsErrorInitSanityCheckFail

잘못된 개발 환경으로 인해 Unity Ads 서비스를 초기화하지 못했습니다.

kUnityAdsErrorAdBlockerDetected

광고 차단기로 인해 발생하는 오류입니다.

kUnityAdsErrorFileIoError

파일을 읽거나 쓸 수 없어서 발생하는 오류입니다.

kUnityAdsErrorDeviceIdError

잘못된 디바이스 ID로 인해 발생하는 오류입니다.

kUnityAdsErrorShowError

광고 표시를 시도할 때 발생하는 오류입니다.

kUnityAdsErrorInternalError

내부 Unity Ads 서비스 오류가 발생했습니다.

UnityAdsBannerPosition

배너 광고의 앵커로 설정할 수 있는 열거형 포지션입니다.

설명

kUnityAdsBannerPositionTopLeft

배너를 화면의 왼쪽 상단에 고정합니다.

kUnityAdsBannerPositionTopCenter

배너를 화면의 가운데 상단에 고정합니다.

kUnityAdsBannerPositionTopRight

배너를 화면의 오른쪽 상단에 고정합니다.

kUnityAdsBannerPositionBottomLeft

배너를 화면의 왼쪽 하단에 고정합니다.

kUnityAdsBannerPositionBottomCenter

배너를 화면의 가운데 하단에 고정합니다.

kUnityAdsBannerPositionBottomRight

배너를 화면의 오른쪽 하단에 고정합니다.

kUnityAdsBannerPositionCenter

배너를 화면 중앙에 고정합니다.

kUnityAdsBannerPositionNone

배너를 고정하지 않습니다.

델리게이트

UnityAdsInitializationDelegate

@protocol UnityAdsInitializationDelegate <NSObject>
- (void)initializationComplete;
- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;
@end

이 델리게이트를 구현하여 initialize 결과를 처리합니다.

initializationComplete

이 콜백 메서드는 SDK 초기화에 성공했을 때의 로직을 처리합니다.

initializationFailed

이 콜백 메서드는 SDK 초기화에 실패했을 때의 로직을 처리합니다.

파라미터

설명

error

초기화를 못하게 한 UnityAdsInitializationError입니다.

message

오류 관련 메시지입니다.

UnityAdsLoadDelegate

@protocol UnityAdsLoadDelegate <NSObject>
- (void)unityAdsAdLoaded: (NSString *)placementId;
- (void)unityAdsAdFailedToLoad: (NSString *)placementId
                     withError: (UnityAdsLoadError)error
                   withMessage: (NSString *)message;
@end

이 델리게이트를 구현하여 load 결과를 처리합니다.

unityAdsAdLoaded

이 콜백 메서드는 광고 유닛 로드에 성공했을 때의 로직을 처리합니다.

파라미터

설명

placementId

콘텐츠를 로드한 광고 유닛의 ID입니다.

unityAdsAdFailedToLoad

이 콜백 메서드는 광고 유닛 로드에 실패했을 때의 로직을 처리합니다.

파라미터

설명

placementId

콘텐츠를 로드하지 못한 광고 유닛의 ID입니다.

error

로드가 실패한 원인인 UnityAdsLoadError입니다.

message

오류 관련 메시지입니다.

UnityAdsShowDelegate

@protocol UnityAdsShowDelegate <NSObject>
- (void)unityAdsShowComplete: (NSString *)adUnitId withFinishState: (UnityAdsShowCompletionState)state;
- (void)unityAdsShowFailed: (NSString *)adUnitId withError: (UnityAdsShowError)error withMessage: (NSString *)message;
- (void)unityAdsShowStart: (NSString *)adUnitId;
- (void)unityAdsShowClick: (NSString *)adUnitId;
@end

이 델리게이트를 구현하여 show 결과를 처리합니다.

unityAdsShowComplete

이 콜백 메서드는 광고를 완료하는 로직을 처리합니다.

파라미터

설명

adUnitId

콘텐츠를 표시하는 광고 유닛의 ID입니다.

state

광고를 건너뛰었는지 아니면 끝까지 시청했는지를 나타냅니다.

unityAdsShowStart

이 콜백 메서드는 광고 재생을 시작했을 때의 로직을 처리합니다.

파라미터

설명

adUnitId

콘텐츠를 표시하는 광고 유닛의 ID입니다.

unityAdsShowClick

이 콜백 메서드는 사용자의 광고 클릭 로직을 처리합니다.

파라미터

설명

adUnitId

콘텐츠를 표시하는 광고 유닛의 ID입니다.

unityAdsShowFailed

이 콜백 메서드는 광고 유닛의 콘텐츠 표시에 실패했을 때의 로직을 처리합니다.

파라미터

설명

adUnitId

콘텐츠를 표시하지 못한 광고 유닛의 ID입니다.

error

표시를 못하게 한 UnityAdsShowError입니다.

message

오류 관련 메시지입니다.

UnityAdsDelegate

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

@protocol UnityAdsDelegate <NSObject>
- (void)unityAdsReady: (NSString *)placementId;
- (void)unityAdsDidError: (UnityAdsError)error withMessage: (NSString *)message;
- (void)unityAdsDidStart: (NSString *)placementId;
- (void)unityAdsDidFinish: (NSString *)placementId
          withFinishState: (UnityAdsFinishState)state;
@end

이 델리게이트를 구현하여 다양한 광고 상태를 처리합니다. 스크립트에서 이를 구현하여 보상형 광고의 로직을 정의합니다.

unityAdsReady

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

지정된 광고 유닛을 통해 표시할 준비 중인 광고 콘텐츠의 로직을 지정합니다.

파라미터

설명

placementId

준비된 광고 유닛의 ID입니다.

unityAdsDidError

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

오류로 인해 표시하는 데 실패한 광고 콘텐츠의 로직을 지정합니다.

파라미터

설명

error

오류를 일으킨 UnityAdsError입니다.

message

오류 관련 메시지입니다.

unityAdsDidStart

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

광고를 표시하도록 트리거하는 플레이어의 로직을 지정합니다.

파라미터

설명

placementId

광고를 표시하는 광고 유닛의 ID입니다.

unityAdsDidFinish

SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 지원 중단 예정인 API 클래스를 참고하십시오.

플레이어가 광고를 끝까지 시청했을 때의 로직을 지정합니다.

파라미터

설명

placementId

표시를 완료한 광고 유닛의 ID입니다.

state

광고 표시의 결과로 발생하는 사용자 이벤트입니다.

UADSBannerDelegate

@protocol UADSBannerViewDelegate <NSObject>
 
@optional
- (void)bannerViewDidLoad: (UADSBannerView *)bannerView;
- (void)bannerViewDidClick: (UADSBannerView *)bannerView;
- (void)bannerViewDidLeaveApplication: (UADSBannerView *)bannerView;
- (void)bannerViewDidError: (UADSBannerView *)bannerView error: (UADSBannerError *)error;
@end

이 델리게이트는 Unity Ads 배너 이벤트로부터 콜백을 제공합니다.

bannerViewDidLoad

이 콜백은 배너가 광고 콘텐츠를 성공적으로 로드했을 때 작동합니다.

bannerViewDidClick

이 콜백은 사용자가 배너 광고를 클릭했을 때 작동합니다.

bannerViewDidLeaveApplication

이 콜백은 사용자가 애플리케이션을 종료하여 배너가 닫혔을 때 작동합니다.

bannerViewDidError

이 콜백은 UnityAdsBanner에 오류가 발생했을 때 작동합니다.

파라미터

설명

error

오류를 일으킨 UADSBannerError입니다.

UADSBannerAdRefreshViewDelegate

참고: 이 델리게이트는 지원 중단 예정이며 Unity Ads SDK의 향후 주요 버전 릴리스에서 제거될 예정입니다.

@protocol UADSBannerAdRefreshViewDelegate <NSObject>
 
@optional
- (void)unityAdsRefreshBannerDidLoad: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidNoFill: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidShow: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidHide: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidClick: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidError: (UADSBannerAdRefreshView *)bannerAdRefreshView message: (NSString *)message;
@end

이 델리게이트는 Unity Ads 배너 새로고침 이벤트로부터 콜백을 제공합니다.

unityAdsRefreshBannerDidLoad

배너가 로드되고 뷰 계층 구조에 배치될 준비가 되었을 때 호출됩니다.

unityAdsRefreshBannerDidNoFill

배너에 사용할 수 있는 광고 콘텐츠가 없을 때 호출됩니다.

unityAdsRefreshBannerDidShow

배너가 사용자에게 표시될 때 호출됩니다.

unityAdsRefreshBannerDidHide

배너가 사용자로부터 숨겨질 때 호출됩니다.

unityAdsRefreshBannerDidClick

사용자가 배너 광고를 클릭했을 때 호출됩니다.

unityAdsRefreshBannerDidError

UnityAdsBanner 오류가 발생하면 호출됩니다.

파라미터

설명

message

오류 관련 메시지입니다.