# Unity Ads SDK API 레퍼런스

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

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

```cs
using UnityEngine.Advertisements;
```

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

**클래스**

* [`Advertisement`](#advertisement)
* [`Banner`](#banner)
* [`BannerLoadOptions`](#bannerloadoptions)
* [`BannerOptions`](#banneroptions)
* [`ShowOptions`](#showoptions)

**열거형**

* [`ShowResult`](#showresult)
* [`UnityAdsInitializationError`](#unityadsinitializationerror)
* [`UnityAdsLoadError`](#unityadsloaderror)
* [`UnityAdsShowError`](#unityadsshowerror)
* [`UnityAdsShowCompletionState`](#unityadsshowcompletionstate)
* [`BannerPosition`](#bannerposition)

**인터페이스**

* [`IUnityAdsInitializationListener`](#iunityadsinitializationlistener)
* [`IUnityAdsLoadListener`](#iunityadsloadlistener)
* [`IUnityAdsShowListener`](#iunityadsshowlistener)

## 클래스##classes

### Advertisement##advertisement

#### Initialize##initialize

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

지정된 [게임 ID](/grow/dashboard/get-started/project/settings.md#game-ids), [테스트 모드](/grow/ads/optimization/test-ads-integration.md) 상태, 광고 단위 로드 설정으로 Unity Ads 서비스를 초기화합니다.

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

#### Load##load

```cs
public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)
```

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

| **파라미터**       | **설명**                                                                                              |
| -------------- | --------------------------------------------------------------------------------------------------- |
| `adUnitId`     | 광고 콘텐츠를 로드할 광고 단위의 식별자입니다.                                                                          |
| `loadListener` | 필요에 따라
[`IUnityAdsLoadListener`](#iunityadsloadlistener) 콜백과 함께 광고 콘텐츠를 로드합니다(버전
3.7.0 이상). |

#### IsReady##isready

> **Important:**
>
> SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 \[사용 중단 예정인 API
> 클래스

```cs
static bool IsReady (string adUnitId)
```

지정된 광고 단위에 광고가 표시될 준비가 되었으면 `true`를 반환합니다. `enablePerPlacementLoad`를 활성화하여 SDK를 초기화하는 경우 [`Load`](#load)를 호출한 후 [`Show`](#show)를 호출해야 합니다.

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

#### Show##show

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

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

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

> **Note:**
>
> 광고 단위 ID를 지정하지 않고 `Show`를 호출하면 메서드는 Unity 기본 플레이스먼트에 로드된 콘텐츠를 표시합니다. SDK 버전 4.0 이상에서는 광고 단위 ID를 지정해야 합니다.

#### AddListener##addlistener

> **Important:**
>
> SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 \[사용 중단 예정인 API
> 클래스

```cs
public static void AddListener(IUnityAdsListener listener)
```

Unity Ads 콜백을 수신할 리스너를 추가합니다. 버전 3.1.0 이상에서는 여러 리스너를 등록할 수 있습니다. 이는 특히 [Mediation](/grow/ads/mediation/unity-ads-in-mediation.md) 고객에게 도움이 됩니다.

| **파라미터**   | **설명**                                      |
| ---------- | ------------------------------------------- |
| `listener` | Unity Ads 콜백의 [리스너](#iunityadslistener)입니다. |

#### RemoveListener##removelistener

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

```cs
public static void RemoveListener(IUnityAdsListener listener)
```

사용 중인 [`IUnityAdsListener`](#iunityadslistener)를 제거합니다.

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

#### GetPlacementState##getplacementstate

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

```cs
public static PlacementState GetPlacementState(string adUnitId)
```

지정된 광고 단위의 [상태](#placementstate)를 반환합니다.

| **파라미터**   | **설명**               |
| ---------- | -------------------- |
| `adUnitId` | 쿼리하려는 광고 단위의 식별자입니다. |

#### isInitialized##isinitialized

```cs
public static bool isInitialized
```

SDK가 초기화되었다면 `true`를, 그렇지 않으면 `false`를 반환합니다.

#### isSupported##issupported

```cs
public static bool isSupported
```

SDK가 현재 플랫폼에서 지원되는 경우에는 `true`를, 그렇지 않은 경우에는 `false`를 반환합니다.

#### debugMode##debugmode

```cs
public static bool debugMode
```

SDK가 디버그 모드에 있으면 `true`를, 그렇지 않으면 `false`를 반환합니다. 디버그 모드는 SDK에서 로깅 수준을 제어합니다.

#### version##version

```cs
public static string version
```

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

#### isShowing##isshowing

```cs
public static bool isShowing
```

광고가 현재 표시되고 있는 경우 `true`를, 그렇지 않으면 `false`를 반환합니다.

### Banner##banner

이 클래스를 사용하여 [배너 광고를 구현](/grow/ads/unity-sdk/banner-ads.md)합니다.

#### Load##banner-load

```cs
public static void Load(string adUnitId, BannerLoadOptions options)
```

지정된 배너 광고 단위의 광고 콘텐츠를 로드합니다. `enablePerPlacementLoad`를 활성화하여 SDK를 초기화하는 경우 `Load`를 호출한 후 [`Show`](#banner-show)를 호출해야 합니다.

| **파라미터**   | **설명**                                                       |
| ---------- | ------------------------------------------------------------ |
| `adUnitId` | 로드할 배너 광고 단위의 식별자입니다.                                        |
| `options`  | 배너를 로드할 때 SDK에 이벤트를 알리는 다양한
[옵션](#bannerloadoptions)입니다. |

#### Show##banner-show

```cs
public static void Show(string adUnitId, BannerOptions options)
```

지정된 배너 광고 단위의 광고 콘텐츠를 표시합니다. [`Load`](#banner-load)를 호출한 후 `Show`를 호출해야 합니다.

| **파라미터**   | **설명**                                               |
| ---------- | ---------------------------------------------------- |
| `adUnitId` | 로드할 배너 광고 단위의 식별자입니다.                                |
| `options`  | 배너를 표시할 때 SDK에 이벤트를 알리는 다양한 [옵션](#banneroptions)입니다. |

#### Hide##banner-hide

```cs
public static void Hide(bool destroy = false)
```

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

#### SetPosition##setposition

```cs
public void SetPosition (BannerPosition bannerPosition)
```

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

| **파라미터**         | **설명**                                   |
| ---------------- | ---------------------------------------- |
| `bannerPosition` | 배너 광고의 앵커로 사용할 [위치](#bannerposition)입니다. |

#### isLoaded##banner-is-loaded

```cs
public static bool isLoaded
```

표시할 배너 광고가 로드된 경우 `true`를, 그렇지 않으면 `false`를 반환합니다.

### ShowOptions##showoptions

광고 단위에 콘텐츠를 표시할 때 SDK에 이벤트를 알리는 옵션을 구현합니다. 광고가 완료되면 `ShowOptions.resultCallback`을 사용하여 [`ShowResult`](#showresult) 열거형을 Show로 다시 전달합니다.

#### resultCallback##resultcallback

```cs
public ShowResult resultCallback { get; set; }
```

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

> **Important:**
>
> **구식**. [`IUnityAdsListener`](#iunityadslistener)(을)를 구현하고 `Advertisement.AddListener`(을)를 대신 호출합니다.

#### gamerSid##gamersid

```cs
public string gamerSid { get; set; }
```

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

### BannerLoadOptions##bannerloadoptions

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

#### loadCallback##loadcallback

```cs
public LoadCallback loadCallback { get; set; }
```

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

#### errorCallback##errorcallback

```cs
public ErrorCallback errorCallback { get; set; }
```

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

### BannerOptions##banneroptions

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

#### bannerCallback##bannercallback

```cs
public BannerCallback bannerCallback { get; set; }
```

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

#### hideCallback##hidecallback

```cs
public BannerCallback hideCallback { get; set; }
```

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

#### clickCallback##clickcallback

```cs
public BannerCallback clickCallback { get; set; }
```

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

## 열거형##enums

### PlacementState##placementstate

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

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

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

### ShowResult##showresult

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

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

### UnityAdsInitializationError##unityadsinitializationerror

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

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

### UnityAdsLoadError##unityadsloaderror

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

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

### UnityAdsShowCompletionState##unityadsshowcompletionstate

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

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

### UnityAdsShowError##unityadsshowerror

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

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

### BannerPosition##bannerposition

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

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

## 인터페이스##interfaces

### IUnityAdsInitializationListener##iunityadsinitializationlistener

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

이 인터페이스를 구현하여 [`Initialize`](#initialize) 결과를 처리합니다.

#### OnInitializationComplete##oninitializationcomplete

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

#### OnInitializationFailed##oninitializationfailed

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

| **파라미터**  | **설명**                                                                       |
| --------- | ---------------------------------------------------------------------------- |
| `error`   | 초기화를 못하게 한 [`UnityAdsInitializationError`](#unityadsinitializationerror)입니다. |
| `message` | 오류 관련 메시지입니다.                                                                |

### IUnityAdsLoadListener##iunityadsloadlistener

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

이 인터페이스를 구현하여 [`Load`](#load) 결과를 처리합니다.

#### OnUnityAdsLoaded##onunityadsloaded

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

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

#### OnUnityAdsFailedToLoad##onunityadsfailedtoload

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

| **파라미터**   | **설명**                                                             |
| ---------- | ------------------------------------------------------------------ |
| `adUnitId` | 로드에 실패한 광고 단위의 식별자입니다.                                             |
| `error`    | 로드가 실패한 원인인 [`UnityAdsLoadError`](#unityadsloaderror)입니다.
입니다. |
| `message`  | 오류 관련 메시지입니다.                                                      |

### IUnityAdsShowListener##iunityadsshowlistener

```cs
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`](#show) 결과를 처리합니다.

#### OnUnityAdsShowFailure##onunityadsshowfailure

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

| **파라미터**   | **설명**                                                       |
| ---------- | ------------------------------------------------------------ |
| `adUnitId` | 표시하지 못한 광고 단위의 식별자입니다.                                       |
| `error`    | 표시를 못하게 한 [`UnityAdsShowError`](#unityadsshowerror)
입니다. |
| `message`  | 오류 관련 메시지입니다.                                                |

#### OnUnityAdsShowStart##onunityadsshowstart

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

| **파라미터**   | **설명**                   |
| ---------- | ------------------------ |
| `adUnitId` | 콘텐츠를 표시하는 광고 단위의 식별자입니다. |

#### OnUnityAdsShowClick##onunityadsshowclick

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

| **파라미터**   | **설명**                   |
| ---------- | ------------------------ |
| `adUnitId` | 콘텐츠를 표시하는 광고 단위의 식별자입니다. |

#### OnUnityAdsShowComplete##onunityadsshowcomplete

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

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

### IUnityAdsListener##iunityadslistener

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

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

이 인터페이스를 구현하여 다양한 광고 상태를 처리합니다. 스크립트에서 이 리스너를 구현하여 [보상형 광고](/grow/ads/unity-sdk/rewarded-ads.md)의 로직을 정의합니다.

#### OnUnityAdsReady##onunityadsready

> **Important:**
>
> SDK 버전 4.0에서 삭제되었습니다. 자세한 내용은 \[사용 중단 예정인 API
> 클래스

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

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

#### OnUnityAdsDidError##onunityadsdiderror

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

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

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

#### OnUnityAdsDidStart##onunityadsdidstart

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

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

| **파라미터**   | **설명**                       |
| ---------- | ---------------------------- |
| `adUnitId` | 콘텐츠를 표시하는 광고 단위의
식별자입니다. |

#### OnUnityAdsDidFinish##onunityadsdidfinish

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

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

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