---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.3
alternate:
  - https://yandex.com/dev/rtb/doc/ru/ssp/mraid.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/rtb/doc/ru/llms.txt

# MRAID

MRAID (Mobile Rich Media Ad Interface Definitions) нужен для обмена данными между SDK и HTML-баннером. На стороне SDK реализуется специальный мост (bridge), который умеет отправлять события в баннер, а также обрабатывать команды, которые приходят из баннера. В HTML-баннер должен быть встроен mraid.js — скрипт, который предоставляет методы для общения c bridge SDK. В OpenRTB их поддержка передается в массиве `api`, например `imp.banner.api = [3, 5, 7]`.

Возможности MRAID:
- Expand — баннер 320x50 по клику может раскрыться на весь экран.
- Close — креатив сам отрисовывает крестик и может послать команду закрыть рекламу.
- Store Picture — предложить пользователю сохранить картинку в галерею.
- Create Calendar Event — добавить событие в календарь телефона, например старт распродажи.

Стандарты [v2.0](https://www.iab.com/wp-content/uploads/2015/08/IAB_MRAID_v2_FINAL.pdf) и [v3.0](https://www.iab.com/wp-content/uploads/2017/07/MRAID_3.0_FINAL.pdf).

### Архитектура MRAID в SDK

MRAID реализован в SDK как система компонентов, обеспечивающих взаимодействие между HTML-баннерами и нативным кодом приложения:

{% list tabs %}

- Android SDK

  `SdkBannerHtmlAd` — основной класс для работы с HTML-баннерами
  `SdkFullscreenHtmlAd` — класс для полноэкранных HTML-объявлений
  `MraidCompatibilityDetector` — детектор совместимости с MRAID
  `HtmlWebViewAdapter` — адаптер для WebView с поддержкой MRAID

- iOS SDK

  `MACMraidWebView` — основной WebView компонент для MRAID
  `MACMraidController` — контроллер для управления состоянием MRAID
  `MACMraidBridge` — мост для взаимодействия с JavaScript
  `MACMraidScriptInjector` — инжектор mraid.js скрипта

{% endlist %}

### Интеграция mraid.js

HTML-баннер, который поддерживает MRAID (MRAID-совместимый), должен содержать в себе следующую строку:
```

```

С учетом того, что эта строка не должна быть в начале/конце HTML, и могут присутствовать дополнительные атрибуты в теле `script`, проверка совместимости баннера с MRAID проверяется с помощью регулярного выражения:

```
// iOS
private let mraidInjectScriptRegExp = "(<script)(.*)(src=\"mraid\\.js\")(.*)(<\\/script>)"
```

```
// Android
private val MRAID_JS_REG_EXP_PATTERN = Pattern.compile("(<script)(.*)(src=\"mraid\\.js\")(.*)(<\\/script>)")
```

### API методы mraid.js

Ниже перечислены методы, реализованные в mraid.js (версия 0.15).

#### Принимаемые запросы

#|
|| `getVersion()` | Возвращает версию MRAID. На данный момент 2.0 ||
|| `isViewable()` | Показывает, виден ли баннер. По умолчанию `false`. ||
|| `getState()` | Возвращает одно из состояний — `loading`, `default`, `expanded`, `resized`, `hidden`. По умолчанию `loading`. ||
|| `addEventListener(event, listener)` | Добавляет наблюдателя за определенным событием — `ready`, `error`, `stateChange`, `viewableChange`, `sizeChange`, `exposureChange`. ||
|| `removeEventListener(event, listener)` | Удаляет наблюдателя события. ||
|| `fireChangeEvent(properties)` | Метод для выставления свойств `visibility`, `state`, `supports`, `exposure`. ||
|| `setState(stateArg)` | Устанавливает состояние. ||
|| `setDefaultPosition(position)` | Устанавливает позицию (фрейм) баннера в webView по умолчанию. ||
|| `getDefaultPosition()` | Возвращает позицию баннера в webView. По умолчанию не определено. ||
|| `setCurrentPosition(position)` | Устанавливает текущую позицию (фрейма) баннера в webView. ||
|| `getCurrentPosition()` | Возвращает текущую позицию баннера в webView. По умолчанию не определено. ||
|| `notifyReadyEvent()` | Переводит баннер в состояние `ready`, наподобие функции `main()` для баннера. ||
|| `notifyErrorEvent(message, action)` | Сообщает баннеру о произошедшей ошибке. ||
|| `nativeCallComplete()` | Сообщает баннеру о том, что SDK обработало команду и может обработать следующую. ||
|| `supports(feature)` | Возвращает булевый флаг, поддержана ли возможность из `supports` (`sms`, `tel`, `calendar`, `storePicture`, `inlineVideo`). ||
|#

#### Вызываемые команды в SDK

#|
|| `useCustomClose(shouldUseCustomClose)` | Если `shouldUseCustomClose=true/false`, то прячет или показывает нативный крестик баннера. Крестик по умолчанию показывается, если не было вызова этой команды. 
Команда действует только на Interstitial баннеры. ||
|| `open(url)` | Открывает URL, который пришел в команде. Обрабатывается как клик по ссылке. ||
|| `close()` | Закрывает баннер, если баннер Interstitial, в противном случае ничего не делает. ||
|| `executeNativeCall(args)` | Вызывает команду в SDK. ||
|#

#### Дополнительные команды MRAID

Помимо стандартных команд, SDK поддерживает дополнительные команды для расширенной функциональности:

#|
|| `advideocomplete` | Уведомляет SDK о завершении воспроизведения видео в объявлении. ||
|| `adRendered` | Сообщает SDK о том, что объявление полностью отрендерено (используется для оптимизации загрузки). ||
|| `impressionTrackingStart` | Запускает отслеживание показов объявления. ||
|| `impressionTrackingSuccess` | Подтверждает успешное отслеживание показа. ||
|| `rewardedAdComplete` | Уведомляет о завершении Rewarded объявления. ||
|#

### События от SDK к mraid.js

На стороне SDK в mraid.js посылаются следующие события:

#|
|| `notifyReadyEvent()` | Сообщает mraid.js о том, что SDK выполнил инициализацию баннера и готов к его показу. Вызывается сразу по окончании загрузки баннера в webView. ||
|| `fireChangeEvent(property)` | Изменяет одно свойство в mraid.js. Поддержаные свойства: `visibility`, `supports`, `state`. ||
|| `fireChangeEvent(properties)` | Изменяет сразу несколько свойств из списка поддерживаемых. ||
|| `nativeCallComplete()` | Сообщает mraid.js о том, что SDK обработало mraid-команду и готово обрабатывать новую. ||
|#