# 플레이어블 및 인터랙티브 광고

> Unity Exchange를 통해 인터랙티브 플레이어블 광고를 게재합니다.

플레이어블 광고는 Unity Exchange에서 두 번째로 인기 있는 광고 유형입니다. 모든 Unity 인벤토리는 모바일 인앱 프로젝트이므로 대부분의 인벤토리는 플레이어블 광고를 지원합니다.

## MRAID##mraid

모바일 리치 미디어 광고 인터페이스 정의(MRAID)는 모바일 앱에서 실행되는 모바일 리치 미디어 광고의 공통 API입니다. MRAID를 사용하면 광고 개발자가 일반적인 코드를 사용하여 MRAID를 준수하는 시스템에서 작동하는 인터랙티브 광고를 디자인할 수 있습니다. MRAID는 광고가 표시되는 앱 광고가 상호작용하는 방식을 제어합니다.

## 식별 및 초기화##identification-and-initialization

광고가 Unity MRAID 인터페이스 호환되는지 확인하려면 다음 단계를 따르십시오.

* MRAID 함수를 참조하기 전에 광고 코드에 가능한 한 일찍 MRAID 스크립트 태그(`<script src="mraid.js"></script>`)를 포함하여 MRAID 규정 준수로 식별합니다.
* [`addEventListener`](#addeventlistener) 함수를 사용하여 MRAID 상태가 "loading"에서 "ready"로 변경되는 시점을 감지합니다.
* 광고를 표시하기 전에 `getState` 메서드를 사용하여 "준비" 상태를 확인합니다. 이렇게 하면 광고가 등록되기 전에 준비된 이벤트가 발생하는 등 타이밍 문제를 방지할 수 있습니다.

```js
 function showMyAd() {
   // Ad content
}

if (mraid.getState() === ‘loading') {
   mraid.addEventListener(‘ready', showMyAd);
} else {
   showMyAd();
}
```

액세스, 접근하여 초기화 전에 필요한 추가 정보를 확인하려면 `MRAID_ENV` 오브젝트를 선택합니다. 이 변수 창 오브젝트 연결되며 다음 속성을 포함합니다.

| **속성**            | **유형** | **예제**                      | **설명**                                               |
| ----------------- | ------ | --------------------------- | ---------------------------------------------------- |
| `version`         | 문자열    | `"3.0"`                     | 구현된 MRAID 인터페이스 버전입니다.                               |
| `sdk`             | 문자열    | `"The Unity Ads SDK"`       | Webview를 실행하는 SDK의 이름입니다.                            |
| `sdkVersion`      | 문자열    | `"4.0"`                     | Webview를 실행하는 SDK 버전입니다.                             |
| `appId`           | 문자열    | `"com.unity3d.ads.example"` | 광고를 실행하는 앱의 패키지 이름 또는 애플리케이션 ID입니다.                  |
| `limitAdTracking` | 부울     | `true`                      | `true`는 제한 광고 트래킹이 활성화되어 있고, `false`는 활성화되어 있지 않습니다. |
| `coppa`           | 부울     | `true`                      | `true`는 앱이 어린이를 대상으로 하고, `false`는 그렇지 않음을 나타냅니다.     |

> **Note:**
>
> Unity는 `ifa` 속성을 지원하지 않습니다.

MRAID 기능을 식별하고 초기화하는 방법에 대한 자세한 내용은 [IAB 문서](https://www.iab.com/wp-content/uploads/2015/08/IAB_MRAID_v2_FINAL.pdf)를 참조하십시오.

## 이벤트##events

광고는 다음 이벤트를 수신하려면 이벤트 리스너를 등록해야 합니다. 자세한 내용은 [`addEventListener`](#addeventlistener) 및 [`removeEventListener`](#removeeventlistener) 방법을 참고하십시오.

### error##error

이 이벤트 호스트 광고에서 호출한 함수 실행할 수 없을 때마다 트리거됩니다.

`error(message: string, action: string): void`

| **파라미터**  | **유형** | **설명**                          |
| --------- | ------ | ------------------------------- |
| `message` | 문자열    | 오류에 대한 설명입니다.                   |
| `action`  | 문자열    | 오류가 발생했을 때 호출된 MRAID 행동의 이름입니다. |

### ready##ready

이 이벤트 초기화가 완료되면 트리거됩니다.

`ready()`

### sizeChange##sizechange

이 이벤트 광고 컨테이너 크기가 변경될 때마다 트리거됩니다(예: 기기 방향, 방향 설정 변화에 대한 응답).

`sizeChange(width: number, height: number)`

| **파라미터** | **유형** | **설명**        |
| -------- | ------ | ------------- |
| `width`  | 숫자     | 새로운 뷰의 너비입니다. |
| `height` | number | 새로운 시야의 높이.   |

### stateChange##statechange

이 이벤트 광고 컨테이너의 상태가 변경될 때마다 트리거됩니다.

`stateChange(state: string)`

| **파라미터** | **유형** | **설명**                                                  |
| -------- | ------ | ------------------------------------------------------- |
| `state`  | 문자열    | 표시. 이것은 `"loading"`, `"default"` 또는 `"hidden"`일 수 있습니다. |

### exposureChange##exposurechange

이 이벤트 광고 노출이 변경될 때마다 트리거됩니다. 예를 들면 다음과 같습니다.

* 광고가 표시됩니다.
* 광고가 종료됩니다.
* 애플리케이션 전경 또는 배경이 있습니다.
* 광고 컨테이너의 노출이 변경됩니다(예: 사용자 개인정보 보호 설정을 엽니다).

`exposureChange(exposedPercentage: number, visibleRectangle: Rectangle | null, occlusionRectangles: Rectangle[] | null)`

| **파라미터**              | **유형**         | **설명**                                                                           |
| --------------------- | -------------- | -------------------------------------------------------------------------------- |
| `exposedPercentage`   | 숫자             | 화면에 표시되는 광고의 비율(`0.0`와 `100.0` 사이)입니다.                                           |
| `visibleRectangle`    | `Rectangle`    | 보이는 부분으로, `{x, y, width, height}`로 포맷한 부분입니다. 아무것도 보이지 않는 경우 `null`를 반환합니다.      |
| `occlusionRectangles` | `Rectangle` 배열 | 또는 전체 직사각형이 보이는 경우 `null`입니다. 배열의 각 오클루전 사각형은 `{x, y, width, height}`로 포맷된 것입니다. |

### audioVolumeChange##audiovolumechange

이 이벤트 기기 영역 변경될 때마다 트리거됩니다.

`audioVolumeChange(volumePercentage: number): void`

| **파라미터**           | **유형** | **설명**                                    |
| ------------------ | ------ | ----------------------------------------- |
| `volumePercentage` | 숫자     | 기기(`0.0`와 `100.0` 사이)에 설정된 최대 영역의 백분율입니다. |

### viewableChange(사용 중단 예정)##viewable-change

> **Important:**
>
> 이 이벤트 MRAID 3.0에서 지원이 사용 중단 예정. 하지만 Unity 이전 버전과의 호환성 유지하기 위해 계속 지원합니다.

이 이벤트 광고의 조회 가능성이 변경될 때마다 트리거됩니다. 예를 들면 다음과 같습니다.

* 광고가 표시됩니다.
* 광고가 종료됩니다.
* 애플리케이션 전경 또는 배경이 있습니다.

`viewableChange(viewable: boolean): void`

| **파라미터**   | **유형** | **설명**                                                    |
| ---------- | ------ | --------------------------------------------------------- |
| `viewable` | 부울     | `true`는 광고 컨테이너가 화면에 표시되었음을 나타내고, `false`는 그렇지 않음을 나타냅니다. |

## 지원되는 메서드##supported-methods

Unity 다음 MRAID 메서드를 지원합니다.

* [addEventListener](#addeventlistener)
* [close](#close)
* [getCurrentAppOrientation](#getcurrentapporientation)
* [getCurrentPosition](#getcurrentposition)
* [getDefaultPosition](#getdefaultposition)
* [getMaxSize](#getmaxsize)
* [getplacementtype](#getplacementtype)
* [getScreenSize](#getscreensize)
* [getState](#getstate)
* [getVersion](#getversion)
* [isViewable](#isviewable)
* [open](#open)
* [removeEventListener](#removeeventlistener)
* [supports](#supports)
* [unload](#unload)

### addEventListener##addeventlistener

이 메서드를 사용하여 특정 이벤트 특정 핸들러 함수 구독. 특정 이벤트 여러 리스너를 구독할 수 있으며, 하나의 리스너는 여러 이벤트를 처리할 수 있습니다.

`addEventListener(event: string, listener: function): void`

| **파라미터**   | **유형** | **설명**                                          |
| ---------- | ------ | ----------------------------------------------- |
| `event`    | 문자열    | 수신할 이벤트 이름입니다. 전체 목록은 [이벤트](#events) 섹션 참조하십시오. |
| `listener` | object | 이벤트가 트리거될 때 실행할 함수입니다.                          |

> **Note:**
>
> 더 이상 사용되지 않을 때 이벤트 리스너를 제거합니다. 자세한 내용은 [removeEventListener](#removeeventlistener) 메서드에 대한 기술 자료를 참고하십시오.

### close##close

이 메서드를 사용하여 광고 컨테이너의 상태를 다운그레이드합니다. Unity는 현재 `expand` 및 `resize` 메서드를 모두 지원하지 않으므로 이 메서드는 광고를 기본 상태에서 숨겨진 상태로만 변경할 수 있습니다.

`close():void`

> **Note:**
>
> 이 메서드는 `stateChange` 이벤트를 트리거합니다.

### getCurrentAppOrientation##getcurrentapporientation

이 메서드를 사용하여 기기 앱의 현재 방향, 방향 설정 쿼리.

`getCurrentAppOrientation(): { orientation: string, locked: boolean }`

#### 값 반환##return-values

| **값**         | **설명**                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `orientation` | 을 설명하는 문자열입니다. 이것은 `"landscape"` 또는 `"portrait"`일 수 있습니다.                                                                                  |
| `locked`      | 현재 포지션에서 방향, 방향 설정 잠겼는지 여부를 나타내는 부울이며, true는 방향, 방향 설정 잠겼음을 나타냅니다.방향, 방향 설정이 잠그면 setOrientationProperties의 forceOrientation 속성은 지원되지 않습니다. |

### getCurrentPosition##getcurrentposition

이 메서드를 사용하여 밀도 독립성 픽셀로 측정된 광고 뷰의 현재 포지션과 크기를 반환합니다.

`getCurrentPosition():JavaScriptObject`

#### 값 반환##return-values

`{x: number, y: number, width: number, height: number}`

| **값**    | **설명**                                               |
| -------- | ---------------------------------------------------- |
| `x`      | `getMaxSize()`에 의해 정의된 직사각형의 왼쪽 가장자리에서 오프셋된 픽셀 수입니다. |
| `y`      | `getMaxSize()`에 의해 정의된 직사각형 상단에서 오프셋된 픽셀 수입니다.       |
| `width`  | 컨테이너의 현재 너비(픽셀 단위)입니다.                               |
| `height` | 박스의 현재 높이(픽셀 단위)입니다.                                 |

### getDefaultPosition##getdefaultposition

이 메서드를 사용하여 호출 뷰의 상태와 관계없이 밀도 독립성 픽셀로 측정된 기본 광고 뷰의 포지션과 크기를 반환합니다.

`getDefaultPosition():JavaScriptObject`

#### 값 반환##return-values

`{x: number, y: number, width: number, height: number}`

| **값**    | **설명**                                               |
| -------- | ---------------------------------------------------- |
| `x`      | `getMaxSize()`에 의해 정의된 직사각형의 왼쪽 가장자리에서 오프셋된 픽셀 수입니다. |
| `y`      | `getMaxSize()`에 의해 정의된 직사각형 상단에서 오프셋된 픽셀 수입니다.       |
| `width`  | 컨테이너의 현재 너비(픽셀 단위)입니다.                               |
| `height` | 박스의 현재 높이(픽셀 단위)입니다.                                 |

### getMaxSize##getmaxsize

Unity는 `expand` 및 `resize` 메서드를 지원하지 않으므로 이 메서드는 항상 광고 컨테이너의 최대 크기(밀도 독립성 픽셀 너비 및 높이)를 반환합니다. 전체 화면 인터스티셜 광고 반환값은 항상 전체 화면 크기입니다.

`getMaxSize():JavaScriptObject`

#### 값 반환##return-values

`{width: number, height: number}`

| **값**    | **설명**                 |
| -------- | ---------------------- |
| `width`  | 컨테이너의 현재 너비(픽셀 단위)입니다. |
| `height` | 박스의 현재 높이(픽셀 단위)입니다.   |

### getplacementtype##getplacementtype

이 메서드는 소재 동작 영향을 줄 수 있는 플레이스먼트 유형을 반환합니다.

`getplacementtype():string`

#### 값 반환##return-values

| **값**            | **설명**              |
| ---------------- | ------------------- |
| `"inline"`       | 인라인 광고 배치를 나타냅니다.   |
| `"interstitial"` | 인터스티셜 광고 배치를 나타냅니다. |

### getScreenSize##getscreensize

이 메서드는 광고가 실행되는 기기 현재 방향, 방향 설정 밀도 독립성 픽셀로 나타내는 실제 픽셀 너비와 높이를 반환합니다.

`getScreenSize():JavaScriptObject`

#### 값 반환##return-values

`{width: number, height: number}`

| **값**    | **설명**                  |
| -------- | ----------------------- |
| `width`  | 화면 크기의 최대 너비(픽셀 단위)입니다. |
| `height` | 화면 크기의 최대 높이(픽셀 단위)입니다. |

### getState##getstate

이 메서드는 광고 컨테이너의 현재 상태를 반환합니다. Unity는 `expand` 및 `resize` 메서드를 지원하지 않으므로 광고 상태는 `"expanded"` 또는 `"resized"` 값을 반환하지 않습니다.

`getState(): string`

#### 값 반환##return-values

| **값**       | **설명**                     |
| ----------- | -------------------------- |
| `"default"` | 광고 컨테이너가 기본 표시 상태임을 나타냅니다. |
| `"hidden"`  | 광고 컨테이너가 숨겨져 있음을 나타냅니다.    |
| `"loading"` | 광고 컨테이너가 로드 중임을 나타냅니다.     |

### getVersion##getversion

이 메서드는 Unity 지원하는 MRAID 인터페이스 버전을 반환하여 입찰자가 표시하기 전에 기본 기능을 확인할 수 있도록 합니다.

`getVersion():string`

#### 값 반환##return-values

| **값** | **설명**                       |
| ----- | ---------------------------- |
| `3.0` | MRAID 인터페이스가 버전 3.0임을 나타냅니다. |

### isViewable(사용 중단 예정)##isviewable

> **Important:**
>
> 이 이벤트 지원이 사용 중단 예정. 하지만 Unity 이전 버전과의 호환성 유지하기 위해 계속 지원합니다.

이 메서드는 광고 컨테이너가 현재 화면에 있는지 여부를 반환합니다.

`isViewable():boolean`

**반환값**

| **값**   | **설명**                   |
| ------- | ------------------------ |
| `true`  | 컨테이너는 화면에 표시되고 볼 수 있습니다. |
| `false` | 컨테이너는 화면이 꺼져서 볼 수 없습니다.  |

> **Note:**
>
> 이 메서드는 `viewableChange` 이벤트를 트리거합니다.

### open##open

이 메서드는 애플리케이션 내장된 브라우저 창을 표시하며 외부 URL을 로드합니다. 내장된 브라우저 허용하지 않는 기기 플랫폼에서 이 메서드는 외부 URL로 네이티브 브라우저 호출합니다.

`open(url:string):void`

#### 파라미터##parameters

| **파라미터** | **유형** | **설명**            |
| -------- | ------ | ----------------- |
| `url`    | 문자열    | 외부 웹 페이지의 URL입니다. |

### removeEventListener##removeeventlistener

이 메서드를 사용하여 특정 이벤트 대한 특정 핸들러 메서드 구독을 취소합니다. 오류를 방지하기 위해 이벤트 리스너를 더 이상 사용하지 않을 때 항상 제거해야 합니다.

`removeEventListner(event: string, listener: fuction: void)`

#### 파라미터##parameters

| **파라미터**   | **유형** | **설명**                                                                                                                 |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `event`    | 문자열    | 리스너가 구독한 이벤트 이름으로, 여기에는 다음이 포함될 수 있습니다.- `"error"`
- `"ready"`
- `"sizeChange"`
- `"stateChange"`
- `"viewableChange"` |
| `listener` | 함수     | 입니다.                                                                                                                   |

### supports##supports

이 메서드는 요청 기기 특정 기능을 지원하는지 여부를 반환합니다.

`supports(feature:string):boolean`

#### 파라미터##parameters

| **파라미터** | **유형** | **설명**                                                                            |
| -------- | ------ | --------------------------------------------------------------------------------- |
| `event`  | 문자열    | 쿼리 기능의 이름:- `"calendar"`
- `"inlineVideo"`
- `"sms"`
- `"storePicture"`
- `"tel"` |

**반환값**

| **값**   | **설명**                 |
| ------- | ---------------------- |
| `true`  | 기기가 쿼리된 기능을 지원합니다.     |
| `false` | 기기가 쿼리된 기능을 지원하지 않습니다. |

### unload##unload

이 메서드는 사용자 광고를 더 이상 표시하지 않도록 호스트 알립니다. 광고가 올바르게 렌더 수 없는 오류나 런타임 예외가 발생하면 이 메서드를 사용합니다.

`unload(): void`

## 지원되지 않는 메서드##unsupported-methods

Unity 다음 메서드를 지원하지 않습니다.

* `createCalendarEvent`
* `expand`
* `getExpandProperties`
* `getLocation`
* `getResizeProperties`
* `initVpaid`
* `playVideo`
* `resize`
* `setExpandProperties`
* `setResizeProperties`
* `storePicture`
* `useCustomClose`

## 문제 해결##troubleshooting

다음 예제와 같은 `Uncaught TypeError`가 표시되면 MRAID 인터페이스를 사용할 수 없거나 광고 소재가 `<MRAID>` 스크립트 태그를 포함하지 못하므로 인터페이스가 연결되지 않았음을 나타냅니다.

### 예제##example

`Uncaught TypeError: Cannot read property 'getVersion' of undefined.`

이 오류는 `<MRAID>` 스크립트 태그를 포함하지 않고도 `getVersion` 메서드를 호출하려고 하면 발생합니다. 이 문제를 해결하려면 MRAID 함수를 참조하기 전에 코드의 앞에 있는 스크립트 태그를 추가합니다.