Unity Ads SDK API 레퍼런스

Unity Ads SDK 공개 API 레퍼런스에 액세스하여 C#에서 Unity 프로젝트의 광고 동작을 연동하고 제어하는 데 사용할 수 있는 클래스, 메서드, 프로퍼티를 확인합니다.

읽는 시간 3분

최근 업데이트: 6달 전

Advertisements

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


using UnityEngine.Advertisements;

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

클래스

```
Advertisement
```
```
Banner
```
```
BannerLoadOptions
```
```
BannerOptions
```
```
ShowOptions
```

열거형

```
ShowResult
```
```
UnityAdsInitializationError
```
```
UnityAdsLoadError
```
```
UnityAdsShowError
```
```
UnityAdsShowCompletionState
```
```
BannerPosition
```

인터페이스

```
IUnityAdsInitializationListener
```
```
IUnityAdsLoadListener
```
```
IUnityAdsShowListener
```

클래스

Initialize


public static void Initialize(string gameId, bool testMode, IUnityAdsInitializationListener initializationListener)

지정된 게임 ID, 테스트 모드 상태, 광고 단위 로드 설정으로 Unity Ads 서비스를 초기화합니다.

파라미터	설명
`gameId`	개발자 대시보드에서 확인할 수 있는 프로젝트의 플랫폼별 Unity 게임 ID입니다.
`testMode`	테스트 모드를 사용하면 라이브 광고를 사용하지 않고 연동을 테스트할 수 있습니다. 테스트 모드에서 `true` 를 사용하여 초기화합니다.
`initializationListener`	필요에 따라 `IUnityAdsInitializationListener` 콜백과 함께 SDK를 활성화합니다(버전 3.7.0 이상).

Load


public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)

지정된 광고 단위의 광고 콘텐츠를 로드합니다.

파라미터	설명
`adUnitId`	광고 콘텐츠를 로드할 광고 단위의 ID입니다.
`loadListener`	필요에 따라 `IUnityAdsLoadListener` 콜백과 함께 광고 콘텐츠를 로드합니다(버전 3.7.0 이상).

IsReady

중요

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


static bool IsReady (string adUnitId)

지정된 광고 단위에 광고가 표시될 준비가 되었으면

true

를 반환합니다.

enablePerPlacementLoad

를 활성화하여 SDK를 초기화하는 경우

Load

를 호출한 후

Show

를 호출해야 합니다.

파라미터	설명
`adUnitId`	쿼리할 광고 단위의 ID입니다.

Show


public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)

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

파라미터	설명
`adUnitId`	표시할 광고 단위의 ID입니다.
`showOptions`	`resultCallback` 을 포함하여 광고 동작을 변경할 수 있는 다양한 옵션입니다.
`showListener`	필요에 따라 `IUnityAdsShowListener` 콜백과 함께 콘텐츠를 표시합니다(버전 3.7.0 이상).

참고

광고 단위 ID를 지정하지 않고

Show

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

AddListener

중요

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


public static void AddListener(IUnityAdsListener listener)

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

파라미터	설명
`listener`	Unity Ads 콜백의 리스너입니다.

RemoveListener

중요

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


public static void RemoveListener(IUnityAdsListener listener)

사용 중인

IUnityAdsListener

를 제거합니다.

파라미터	설명
`listener`	Unity Ads 콜백의 리스너입니다.

GetPlacementState

중요

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


public static PlacementState GetPlacementState(string adUnitId)

지정된 광고 단위의 상태를 반환합니다.

파라미터	설명
`adUnitId`	쿼리할 광고 단위의 ID입니다.

isInitialized


public static bool isInitialized

SDK가 초기화되었다면

true

를, 그렇지 않으면

false

를 반환합니다.

isSupported


public static bool isSupported

SDK가 현재 플랫폼에서 지원되는 경우에는

true

를, 그렇지 않은 경우에는

false

를 반환합니다.

debugMode


public static bool debugMode

SDK가 디버그 모드에 있으면

true

를, 그렇지 않으면

false

를 반환합니다. 디버그 모드는 SDK에서 로깅 수준을 제어합니다.

version


public static string version

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

isShowing


public static bool isShowing

광고가 현재 표시되고 있는 경우

true

를, 그렇지 않으면

false

를 반환합니다.

이 클래스를 사용하여 배너 광고를 구현합니다.


public static void Load(string adUnitId, BannerLoadOptions options)

지정된 배너 광고 단위의 광고 콘텐츠를 로드합니다.

enablePerPlacementLoad

를 활성화하여 SDK를 초기화하는 경우

Load

를 호출한 후

Show

를 호출해야 합니다.

파라미터	설명
`adUnitId`	로드할 배너 광고 단위의 ID입니다.
`options`	배너를 로드할 때 SDK에 이벤트를 알리는 다양한 옵션입니다.


public static void Show(string adUnitId, BannerOptions options)

지정된 배너 광고 단위의 광고 콘텐츠를 표시합니다.

Load

를 호출한 후

Show

를 호출해야 합니다.

파라미터	설명
`adUnitId`	로드할 배너 광고 단위의 ID입니다.
`options`	배너를 표시할 때 SDK에 이벤트를 알리는 다양한 옵션입니다.


public static void Hide(bool destroy = false)

배너 광고를 파기하지 않고 숨길 수 있습니다.

SetPosition


public void SetPosition (BannerPosition bannerPosition)

디바이스에서 배너 광고의 위치를 설정합니다.

파라미터	설명
`bannerPosition`	배너 광고의 앵커로 사용할 위치입니다.


public static bool isLoaded

표시할 배너 광고가 로드된 경우

true

를, 그렇지 않으면

false

를 반환합니다.

ShowOptions

광고 단위에 콘텐츠를 표시할 때 SDK에 이벤트를 알리는 옵션을 구현합니다. 광고가 완료되면

ShowOptions.resultCallback

을 사용하여

ShowResult

열거형을 Show로 다시 전달합니다.

resultCallback


public ShowResult resultCallback { get; set; }

이 콜백은 광고 결과를 수신합니다.

중요

Obsolete:

IUnityAdsListener

를 구현하고 대신

Advertisement.AddListener

를 호출합니다.

gamerSid


public string gamerSid { get; set; }

게임의 특정 사용자에 대한 ID를 지정합니다.

BannerLoadOptions

이 옵션을 구현하면 배너 광고 로딩 시 SDK에 이벤트를 알립니다.

loadCallback


public LoadCallback loadCallback { get; set; }

이 콜백은 배너 광고 단위가 성공적으로 콘텐츠를 로드하여 표시할 준비가 되었을 때 작동합니다.

errorCallback


public ErrorCallback errorCallback { get; set; }

이 콜백은 배너 광고 단위가 콘텐츠를 로드하지 못했을 때 작동합니다.

BannerOptions

이 옵션을 구현하면 배너 광고를 표시할 때 SDK에 이벤트를 알립니다.

bannerCallback


public BannerCallback bannerCallback { get; set; }

이 콜백은 배너가 사용자에게 보일 때 작동합니다.

hideCallback


public BannerCallback hideCallback { get; set; }

이 콜백은 배너가 사용자로부터 숨겨진 상태일 때 작동합니다.

clickCallback


public BannerCallback clickCallback { get; set; }

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

열거형

PlacementState

중요

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

광고 단위의 열거형 상태입니다.

값	설명
`Ready`	광고 단위가 광고를 표시할 준비가 되었습니다.
`NotAvailable`	광고 단위를 사용할 수 없습니다.
`Disabled`	광고 단위가 비활성화되었습니다.
`Waiting`	광고 단위가 준비 대기 중입니다.
`NoFill`	광고 단위에 표시할 광고가 없습니다.

ShowResult

사용자와 광고의 상호 작용에 대한 열거형 상태입니다. 광고 시청이 완료되면 SDK가 이 값을

OnUnityAdsDidFinish

콜백 메서드로 전달합니다.

값	설명
`Failed`	Unity 서비스 오류로 인해 광고 시청 완료에 실패한 경우를 나타냅니다.
`Skipped`	사용자가 광고를 건너뛴 경우를 나타냅니다.
`Finished`	사용자가 광고 시청을 성공적으로 완료한 경우를 나타냅니다.

UnityAdsInitializationError

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

값	설명
`UNKNOWN`	알 수 없는 이유로 발생하는 오류입니다.
`INTERNAL_ERROR`	개발 환경 또는 내부 서비스로 인해 발생하는 오류입니다.
`INVALID_ARGUMENT`	`Initialize` 메서드의 잘못된 인수로 인해 발생하는 오류입니다.
`AD_BLOCKER_DETECTED`	URL 차단으로 인해 발생하는 오류입니다.

UnityAdsLoadError

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

값	설명
`INITIALIZE_FAILED`	SDK가 초기화되지 않아 광고를 로드할 수 없습니다.
`INTERNAL_ERROR`	Unity Ads 서비스 오류로 인해 광고를 로드할 수 없습니다.
`INVALID_ARGUMENT`	`Load` 메서드의 잘못된 인수로 인해 광고를 로드할 수 없습니다.
`NO_FILL`	네트워크에서 제공하는 콘텐츠가 없어 광고를 로드할 수 없습니다.
`TIMEOUT`	지정된 기간 내에 광고를 로드할 수 없습니다.
`UNKNOWN`	알 수 없는 이유로 광고를 로드할 수 없습니다.

UnityAdsShowCompletionState

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

값	설명
`SKIPPED`	사용자가 광고를 건너뛴 경우를 나타냅니다.
`COMPLETED`	광고를 끝까지 재생했음을 나타냅니다. 이는 일반적으로 사용자가 광고를 끝까지 시청하여 보상을 받을 수 있음을 나타냅니다.
`UNKNOWN`	광고 시청 완료 여부를 알 수 없습니다.

UnityAdsShowError

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

값	설명
`NOT_INITIALIZED`	SDK가 초기화되지 않아 광고를 표시할 수 없습니다.
`NOT_READY`	광고 단위가 준비되지 않아 광고를 표시할 수 없습니다.
`VIDEO_PLAYER_ERROR`	미디어 플레이어 오류로 인해 광고를 표시할 수 없습니다.
`INVALID_ARGUMENT`	`Show` 메서드의 잘못된 인수로 인해 광고를 표시할 수 없습니다.
`NO_CONNECTION`	인터넷 연결 오류로 인해 광고를 표시할 수 없습니다.
`ALREADY_SHOWING`	광고가 이미 표시되고 있어 광고를 표시할 수 없습니다.
`INTERNAL_ERROR`	Unity Ads 서비스 오류로 인해 광고를 표시할 수 없습니다.
`UNKNOWN`	알 수 없는 이유로 광고를 표시할 수 없습니다.

BannerPosition

디바이스 디스플레이상에 배너를 고정할 수 있는 열거형 위치입니다.

값	설명
`TOP_LEFT`	배너를 화면의 왼쪽 상단에 고정합니다.
`TOP_CENTER`	배너를 화면의 가운데 상단에 고정합니다.
`TOP_RIGHT`	배너를 화면의 오른쪽 상단에 고정합니다.
`BOTTOM_LEFT`	배너를 화면의 왼쪽 하단에 고정합니다.
`BOTTOM_CENTER`	배너를 화면의 가운데 하단에 고정합니다.
`BOTTOM_RIGHT`	배너를 화면의 오른쪽 하단에 고정합니다.
`CENTER`	배너를 화면 중앙에 고정합니다.

인터페이스

IUnityAdsInitializationListener


public interface IUnityAdsInitializationListener {  void OnInitializationComplete();  void OnInitializationFailed(UnityAdsInitializationError error, string message);}

이 인터페이스를 구현하여

Initialize

결과를 처리합니다.

OnInitializationComplete

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

OnInitializationFailed

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

파라미터	설명
`error`	초기화를 못하게 한 `UnityAdsInitializationError` 입니다.
`message`	오류 관련 메시지입니다.

IUnityAdsLoadListener


public interface IUnityAdsLoadListener {  void OnUnityAdsAdLoaded(string adUnitId);  void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);}

이 인터페이스를 구현하여

Load

결과를 처리합니다.

OnUnityAdsLoaded

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

파라미터	설명
`adUnitId`	콘텐츠를 로드한 광고 단위의 ID입니다.

OnUnityAdsFailedToLoad

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

파라미터	설명
`adUnitId`	로드하지 못한 광고 단위의 ID입니다.
`error`	로드가 실패한 원인인 `UnityAdsLoadError` 입니다. fail.
`message`	오류 관련 메시지입니다.

IUnityAdsShowListener


public interface IUnityAdsShowListener {  void OnUnityAdsShowFailure(string adUnitId, UnityAdsShowError error, string message);  void OnUnityAdsShowStart(string adUnitId);  void OnUnityAdsShowClick(string adUnitId);  void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState);}

이 인터페이스를 구현하여

Show

결과를 처리합니다.

OnUnityAdsShowFailure

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

파라미터	설명
`adUnitId`	표시하지 못한 광고 단위의 ID입니다.
`error`	표시를 못하게 한 `UnityAdsShowError` 입니다.
`message`	오류 관련 메시지입니다.

OnUnityAdsShowStart

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

파라미터	설명
`adUnitId`	콘텐츠를 표시하는 광고 단위의 ID입니다.

OnUnityAdsShowClick

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

파라미터	설명
`adUnitId`	콘텐츠를 표시하는 광고 단위의 ID입니다.

OnUnityAdsShowComplete

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

파라미터	설명
`adUnitId`	콘텐츠를 표시하는 광고 단위의 ID입니다.
`showCompletionState`	광고의 최종 상태(광고를 건너뛰었는지 아니면 끝까지 시청했는지)를 나타냅니다.

IUnityAdsListener

중요

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


public interface IUnityAdsListener{  void OnUnityAdsReady(string adUnitId);  void OnUnityAdsDidError(string message);  void OnUnityAdsDidStart(string adUnitId);  void OnUnityAdsDidFinish(string adUnitId, ShowResult showResult);}

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

OnUnityAdsReady

중요

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

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

파라미터	설명
`adUnitId`	준비된 광고 단위의 ID입니다.

OnUnityAdsDidError

중요

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

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

파라미터	설명
`message`	오류 관련 메시지입니다.

OnUnityAdsDidStart

중요

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

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

파라미터	설명
`adUnitId`	콘텐츠를 표시하는 광고 단위의 ID입니다.

OnUnityAdsDidFinish

중요

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

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

파라미터	설명
`adUnitId`	표시를 완료한 광고 단위의 ID입니다.
`showResult`	광고 표시의 결과로 발생하는 사용자 이벤트입니다.

Unity Ads SDK API 레퍼런스

클래스

Advertisement

Initialize

파라미터

설명

Load

파라미터

설명

IsReady

파라미터

설명

Show

파라미터

설명

AddListener

파라미터

설명

RemoveListener

파라미터

설명

GetPlacementState

파라미터

설명

isInitialized

isSupported

debugMode

version

isShowing

Banner

Load

파라미터

설명

Show

파라미터

설명

Hide

SetPosition

파라미터

설명

isLoaded

ShowOptions

resultCallback

gamerSid

BannerLoadOptions

loadCallback

errorCallback

BannerOptions

bannerCallback

hideCallback

clickCallback

열거형

PlacementState

값

설명

ShowResult

값

설명

UnityAdsInitializationError

값

설명

UnityAdsLoadError

값

설명

UnityAdsShowCompletionState

값

설명

UnityAdsShowError

값

설명

BannerPosition

값

설명

인터페이스

IUnityAdsInitializationListener

OnInitializationComplete

OnInitializationFailed

파라미터

설명

IUnityAdsLoadListener