# Unity Ads Android SDK API 레퍼런스

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

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

**클래스**

* [`UnityAds`](#unityads)
* [`UnityAdsLoadOptions`](#unityadsloadoptions)
* [`BannerView`](#bannerview)
* [`UnityBannerSize`](#unitybannersize)

**열거형**

* [`PlacementState`](#placementstate)
* [`FinishState`](#finishstate)
* [`UnityAdsInitializationError`](#unityadsinitializationerror)
* [`UnityAdsLoadError`](#unityadsloaderror)
* [`UnityAdsShowError`](#unityadsshowerror)
* [`UnityAdsShowCompletionState`](#unityadsshowcompletionstate)
* [`UnityAdsError`](#unityadserror)

**인터페이스**

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

## 클래스##classes

### UnityAds##unityads

이 네임스페이스를 사용하여 보상형 또는 비보상형 비디오 광고, 인터스티셜 광고, 배너 광고와 같은 [인터스티셜 광고 콘텐츠를 구현](/grow/ads/android-sdk/interstitial-ads.md)합니다.

#### initialize##initialize

```java
initialize(final Activity context, final String gameId, final boolean testMode, final IUnityAdsInitializationListener initializationListener)
```

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

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

#### load##load

```java
public static void load(final String adUnitId, final UnityAdsLoadOptions loadOptions, final IUnityAdsLoadListener listener)
```

지정된 광고 단위의 광고 콘텐츠를 로드합니다. [`show`](#show)를 호출한 후 `load`를 호출해야 합니다.

| **파라미터**      | **설명**                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------- |
| `adUnitId`    | 광고 콘텐츠를 로드할 광고 단위의 식별자입니다.                                                                  |
| `loadOptions` | 광고 동작을 변경할 수 있는 다양한 옵션입니다.                                                                  |
| `listener`    | 필요에 따라 \[`IUnityAdsLoadListener`(#iunityadsloadlistener) 콜백과 함께 광고 콘텐츠를 로드합니다(버전 3.7.0 이상). |

#### show##show

```java
public static void show(final Activity activity, final String adUnitId, final UnityAdsShowOptions options, final IUnityAdsShowListener showListener)
```

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

| 파라미터           | 설명                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------- |
| `activity`     | 현재 Android [`Activity`](https://developer.android.com/reference/android/app/Activity)입니다. |
| `adUnitId`     | 표시할 광고 단위의 식별자입니다.                                                                        |
| `options`      | 광고 동작을 수정하는 [옵션](#unityadsloadoptions) 모음입니다.                                             |
| `showListener` | 필요에 따라 \[`IUnityAdsShowListener`(#iunityadsshowlistener) 콜백과 함께 콘텐츠를 표시합니다(버전 3.7.0 이상).  |

#### addListener##addlistener

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

```java
public static void addListener(IUnityAdsListener listener)
```

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

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

#### removeListener##removelistener

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

```java
public static void removeListener(IUnityAdsListener listener)
```

사용 중인 `IUnityAdsListener`를 제거합니다.

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

#### getVersion##getversion

```java
public static String getVersion()
```

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

#### getPlacementState##getplacementstate

```java
public static PlacementState getPlacementState(String adUnitId)
```

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

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

#### setDebugMode##setdebugmode

```java
public static void setDebugMode(boolean debugMode)
```

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

#### getDebugMode##getdebugmode

```java
public static boolean getDebugMode()
```

SDK가 디버그 모드일 때 `true`를 반환합니다.

#### isInitialized##isinitialized

```java
public static boolean isInitialized()
```

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

#### isSupported##issupported

```java
public static bool isSupported()
```

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

### UnityAdsLoadOptions##unityadsloadoptions

```java
public class UnityAdsLoadOptions extends UnityAdsBaseOptions
```

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

#### setAdMarkup##setadmarkup

```java
public void setAdMarkup(String adMarkup)
```

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

#### setObjectId##set-ad-markup

```java
public void setObjectId(String objectId)
```

이 메서드는 로드된 광고 오브젝트 ID를 표시할 광고 오브젝트 ID로 설정합니다.

### BannerView##bannerview

```java
public BannerView(Activity activity, String adUnitId, UnityBannerSize size)
```

| **파라미터**   | **설명**                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------- |
| `activity` | 현재 Android [`Activity`](https://developer.android.com/reference/android/app/Activity)입니다. |
| `adUnitId` | 표시할 광고 단위의 식별자입니다.                                                                        |
| `size`     | 배너 오브젝트의 [`size`](#unitybannersize)입니다.                                                   |

#### getPlacementId##getplacementid

```java
public String getPlacementId()
```

배너 광고 단위의 광고 단위 ID를 반환합니다.

#### getSize##getsize

```java
public UnityBannerSize getSize()
```

배너의 [`size`](#unitybannersize)입니다.

#### setListener##setlistener

```java
public void setListener(IListener listener)
```

배너에서 사용 중인 리스너를 설정합니다.

#### getListener##getlistener

```java
public IListener getListener()
```

배너에서 사용 중인 리스너를 가져옵니다.

#### load##bannerload

```java
public void load()
```

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

#### destroy##destroy

```java
public void destroy()

```

배너를 더 이상 사용하지 않을 때, 이를 뷰 계층 구조에서 제거하기 위해 이 메서드를 호출합니다.

### UnityBannerSize##unitybannersize

```java
public UnityBannerSize(int width, int height)
```

이 클래스를 사용하여 [배너 오브젝트](#bannerview)의 높이와 너비를 정의합니다.

#### getWidth##getwidth

```java
public int getWidth()
```

[배너 오브젝트](#bannerview)의 너비(픽셀 단위)를 반환합니다.

#### getHeight##getheight

```java
public int getHeight()
```

[배너 오브젝트](#bannerview)의 높이(픽셀 단위)를 반환합니다.

## 열거형##enums

### PlacementState##placementstate

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

| 값               | 설명                        |
| --------------- | ------------------------- |
| `READY`         | 광고 단위가 광고를 표시할 준비가 되었습니다. |
| `NOT_AVAILABLE` | 광고 단위를 사용할 수 없습니다.        |
| `DISABLED`      | 광고 단위가 비활성화되었습니다.         |
| `WAITING`       | 광고 단위가 준비 대기 중입니다.        |
| `NO_FILL`       | 광고 단위에 표시할 광고가 없습니다.      |

### FinishState##finishstate

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

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

### UnityAdsInitializationError##unityadsinitializationerror

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

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

### UnityAdsShowCompletionState##unityadsshowcompletionstate

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

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

### UnityAdsLoadError##unityadsloaderror

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

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

### UnityAdsShowError##unityadsshowerror

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

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

### UnityAdsError##unityadserror

```java
...
```

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

## 인터페이스##interfaces

### IUnityAdsInitializationListener##iunityadsinitializationlistener

```java
void onInitializationComplete();
void onInitializationFailed(UnityAds.UnityAdsInitializationError error, String message);
```

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

#### onInitializationComplete##oninitializationcomplete

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

#### onInitializationFailed##oninitializationfailed

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

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

### IUnityAdsLoadListener##iunityadsloadlistener

```java
void onUnityAdsAdLoaded(String placementId);
void onUnityAdsFailedToLoad(String placementId, UnityAds.UnityAdsLoadError error, String message);
```

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

#### onUnityAdsAdLoaded##onunityadsadloaded

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

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

#### onUnityAdsFailedToLoad##onunityadsfailedtoload

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

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

### IUnityAdsShowListener##iunityadsshowlistener

```java
void onUnityAdsShowFailure(String placementId, UnityAds.UnityAdsShowError error, String message);
void onUnityAdsShowStart(String placementId);
void onUnityAdsShowClick(String placementId);
UnityAds.UnityAdsShowCompletionState state;
```

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

#### onUnityAdsShowFailure##onunityadsshowfailure

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

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

#### onUnityAdsShowStart##onunityadsshowstart

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

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

#### onUnityAdsShowClick##onunityadsshowclick

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

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

#### onUnityAdsShowComplete##onunityadsshowcomplete

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

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

#### onUnityAdsReady##onunityadsready

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

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

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

#### onUnityAdsDidError##onunityadsdiderror

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

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

| 파라미터                      | 설명                |
| ------------------------- | ----------------- |
| [`error`](#unityadserror) | 광고 실패를 일으킨 오류입니다. |
| `message`                 | 오류 관련 메시지입니다.     |

#### onUnityAdsDidStart##onunityadsdidstart

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

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

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

#### OnUnityAdsDidFinish##onunityadsdidfinish

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

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

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

### IListener##ilistener

```java
String mObjectId = UUID.randomUUID().toString();
void onBannerLoaded(BannerView bannerAdView);
void onBannerShown(BannerView bannerAdView);
void onBannerClick(BannerView bannerAdView);
void onBannerFailedToLoad(BannerView bannerAdView, BannerErrorInfo errorInfo);
void onBannerLeftApplication(BannerView bannerView);
```

#### onBannerLoaded##onbannerloaded

이 콜백은 배너에 광고 로딩이 완료되었을 때 작동합니다. 뷰 파라미터는 뷰 계층 구조에 삽입되어야 하는 배너를 참조합니다.

| 파라미터           | 설명                             |
| -------------- | ------------------------------ |
| `bannerAdView` | 로드된 [배너 오브젝트](#bannerview)입니다. |

#### onBannerClick##onbannerclick

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

| 파라미터           | 설명                             |
| -------------- | ------------------------------ |
| `bannerAdView` | 로드된 [배너 오브젝트](#bannerview)입니다. |

#### onBannerError##onbannererror

이 콜백은 배너 표시 오류가 발생했을 때 작동합니다.

| 파라미터           | 설명                             |
| -------------- | ------------------------------ |
| `bannerAdView` | 로드된 [배너 오브젝트](#bannerview)입니다. |
| `errorInfo`    | 배너 로드 오류에 대한 정보를 포함하는 클래스입니다.  |

#### onBannerLeftApplication##onbannerleftapplication

이 콜백은 배너 링크가 애플리케이션 외부에 있을 때 작동합니다.

| 파라미터           | 설명                             |
| -------------- | ------------------------------ |
| `bannerAdView` | 로드된 [배너 오브젝트](#bannerview)입니다. |