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 и v3.0.

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

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

Android SDK

iOS SDK

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

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

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

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

<script src="mraid.js"></script>

С учетом того, что эта строка не должна быть в начале/конце 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-команду и готово обрабатывать новую.

Была ли статья полезна?

Особенности Interstitial и Rewarded

OM SDK