# Playable でインタラクティブな広告

> Unity Exchange を通じてインタラクティブな Playable 広告を配信します。

Playable 広告は、Unity Exchange で 2 番目に人気のあるタイプの広告です。Unity インベントリはすべてモバイルのアプリケーション内プロジェクトであるため、そのほとんどが Playable 広告をサポートしています。

## 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`メソッドを使用します。これにより、広告が登録される前に Ready イベントが発生するなどのタイミングの問題を回避できます。

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

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

初期化前に `MRAID_ENV` オブジェクトにアクセスして、必要な情報を確認します。この変数はウィンドウオブジェクトにアタッチされ、以下の属性を含みます。

| **Attribute**     | **型**   | **例**                       | **説明**                                                          |
| ----------------- | ------- | --------------------------- | --------------------------------------------------------------- |
| `version`         | string  | `"3.0"`                     | 実装されている MRAID インターフェースのバージョン。                                   |
| `sdk`             | string  | `"The Unity Ads SDK"`       | WebView を実行する SDK の名前。                                          |
| `sdkVersion`      | string  | `"4.0"`                     | WebView を実行している SDK のバージョン。                                     |
| `appId`           | string  | `"com.unity3d.ads.example"` | 広告を実行しているアプリケーションのパッケージ名またはアプリケーション ID。                         |
| `limitAdTracking` | boolean | `true`                      | `true` は追跡型広告制限がアクティブであることを示し、`false` はアクティブでないことを示します。         |
| `coppa`           | boolean | `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`  | string | エラーの説明。                              |
| `action`   | string | エラーがトリガーされたときに呼び出される MRAID アクションの名前。 |

### ready##ready

このイベントは、初期化期化が完了したときにトリガーされます。

`ready()`

### sizeChange##sizechange

このイベントは、広告コンテナのサイズが変更されるたびにトリガーされます（例えば、デバイスの向きの変更に対する反応）。

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

| **パラメーター** | **型**  | **説明**     |
| ---------- | ------ | ---------- |
| `width`    | number | 新しいビューの幅。  |
| `height`   | number | 新しいビューの高さ。 |

### stateChange##statechange

このイベントは、広告コンテナの状態が変更されるたびにトリガーされます。

`stateChange(state: string)`

| **パラメーター** | **型**  | **説明**                                                       |
| ---------- | ------ | ------------------------------------------------------------ |
| `state`    | string | 広告コンテナの状態の表示。`"loading"`、`"default"`、または `"hidden"` を指定できます。 |

### exposureChange##exposurechange

このイベントは、広告の露出が変更されるたびにトリガーされます。例えば、以下のような場合です。

* 広告が表示されます。
* 広告が閉じます。
* アプリケーションに前景または背景がある。
* 広告コンテナの露出が変更された (例えば、ユーザーがプライバシー設定を開く)。

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

| **パラメーター**            | **型**          | **説明**                                                                                                      |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `exposedPercentage`   | number         | 画面に表示される広告の割合（`0.0`と`100.0`の間）。                                                                             |
| `visibleRectangle`    | `Rectangle`    | 広告コンテナの表示部分。`{x, y, width, height}`形式です。何も表示されていない場合は`null`を返します。                                           |
| `occlusionRectangles` | `Rectangle` 配列 | `visibleRectangle`の非表示部分を示す矩形の配列。矩形全体が表示可能な場合は`null`。配列内の各オクルージョン矩形は、`{x, y, width, height}` としてフォーマットされます。 |

### audioVolumeChange##audiovolumechange

このイベントは、デバイスの音量が変更されるたびに発生します。

`audioVolumeChange(volumePercentage: number): void`

| **パラメーター**         | **型**  | **説明**                                      |
| ------------------ | ------ | ------------------------------------------- |
| `volumePercentage` | number | デバイスに設定された最大音量のパーセンテージ（`0.0` と `100.0` の間）。 |

### viewableChange (非推奨)##viewable-change

> **Important:**
>
> このイベントは MRAID 3.0 では非推奨になりました。ただし、Unity は後方互換性を維持するために引き続きサポートしています。

このイベントは、広告の表示性が変更されるたびにトリガーされます。例えば、以下のような場合です。

* 広告が表示されます。
* 広告が閉じます。
* アプリケーションに前景または背景がある。

`viewableChange(viewable: boolean): void`

| **パラメーター** | **型**   | **説明**                                               |
| ---------- | ------- | ---------------------------------------------------- |
| `viewable` | boolean | 「`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

このメソッドを使用して、特定のハンドラー機能を特定のイベントにサブスクライブします。特定のイベントに複数のリスナーをサブスクライブでき、1 つのリスナーで複数のイベントをハンドルできます。

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

| **パラメーター** | **型**  | **説明**                                                     |
| ---------- | ------ | ---------------------------------------------------------- |
| `event`    | string | リッスンするイベントの名前。すべてのリストについては、[イベント](#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`      | string | 外部ウェブページの URL。 |

### removeEventListener##removeeventlistener

このメソッドを使用して、特定のイベントの特定のハンドラーメソッドを解除します。イベントリスナーが使用されなくなった場合は、エラーを避けるために常に削除する必要があります。

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

#### パラメーター##parameters

| **パラメーター** | **型**    | **説明**                                                                                                             |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `event`    | string   | リスナーがサブスクライブしているイベントの名前。次のものが含まれます。- `"error"`
- `"ready"`
- `"sizeChange"`
- `"stateChange"`
- `"viewableChange"` |
| `listener` | function | 削除する機能。                                                                                                            |

### supports##supports

このメソッドは、要求元デバイスが特定の特徴をサポートしているかどうかを返します。

`supports(feature:string):boolean`

#### パラメーター##parameters

| **パラメーター** | **型**  | **説明**                                                                             |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `event`    | string | クエリする特徴の名前:- `"calendar"`
- `"inlineVideo"`
- `"sms"`
- `"storePicture"`
- `"tel"` |

**戻り値**

| **値**   | **説明**                   |
| ------- | ------------------------ |
| `true`  | デバイスは、照会された特徴をサポートします。   |
| `false` | デバイスは照会された特徴をサポートしていません。 |

### unload##unload

このメソッドは、ユーザーに広告を表示しないようにホストに通知します。このメソッドは、広告が正しく描画されないエラーまたはランタイム例外が発生した場合に使用します。

`unload(): void`

## サポートされていないメソッド##サポートされていないメソッド

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 関数を参照する前に、コードの早い段階でタグす。