Модификация AdmanHTML для ОК

Библиотека представляет из себя набор из js-скрипта, а также флешки (vpaid-js-interface.swf) и html (vpaid-js-interface.html), предназначенных для воспроизведения VPAID swf- и js-баннеров.

Скрипт может встраиваться на страницу напрямую или загружаться как модуль requirejs.

Инициализация AdmanHTML

var adm = new AdmanHTML();
adm.onReady(function(e){
    adm.start(); // запускает preroll
});
adm.init(/*initObject*/);

Ниже представлено описание объекта, передаваемого при инициализации библиотеки:

initObject = {
    slotId: SLOT_ID, /* слот */
    params: PARAMS_OBJ, /* объект GET- параметров, которые будут переданы в запрос слота */
    wrapper: WRAPPER_DOM_ELEMENT, /* DOM-элемент - контейнер для отрисовки рекламы  */
    videoEl: VIDEO_DOM_ELEMENT, /* DOM-элемент видео. Позволяет запускать рекламные видеоролики в основном video плеера */
    audioEl: AUDIO_OBJECT, /* Объект Audio. Заранее созданный экземпляр Audio или основной объект плеера. Позволяет избежать блокировки автоплей в фоновых вкладках */
    videoQuality: QUALITY_INT_OR_STRING, /* параметр, указывающий качество видео - число или строка - высота видеоролика */
    browser: BROWSER_OBJ, /* служебный объект */
    midrollPoints: POINTS_ARRAY, /*  массив позиций в секундах, на которых должны быть показаны midroll баннеры */
}
 
BROWSER_OBJ = {
    adBlock: BOOLEAN, /* флаг блокировки рекламы */
    mobile: BOOLEAN, /* мобильное устройство */
};
 
Пример:
var browser = {
    adBlock: false,
    mobile: false
};

Статистика

В настоящий момент поддерживается следующая статистика (параметр type в разделах statistics и serviceStatistics):

Для баннеров:

1. click. Осуществляется переход по ссылке (параметр url)
2. playbackStarted. Дергается счетчик по указанному урлу (параметр url), если начался показ рекламы
3. playbackPaused. Дергается счетчик по указанному урлу (параметр url), если воспроизведение приостановлено
4. playbackResumed. Дергается счетчик по указанному урлу (параметр url), если воспроизведение возобновлено
5. ~~playbackStopped. Дергается счетчик по указанному урлу (параметр url), если воспроизведение остановлено~~
6. playbackCompleted. Дергается счетчик по указанному урлу (параметр url), если баннер полностью показан
7. playheadReachedValue. Дергается счетчик по указанному урлу (параметр url), если реклама показывалась пользователю больше указанного значения (параметр thresholdValue в секундах или параметр thresholdPValue в процентах)
8. closedByUser. Дергается счетчик по указанному урлу (параметр url), если реклама была закрыта пользователем
9. volumeOn. Дергается счетчик по указанному урлу (параметр url), если был включен звук
10. volumeOff. Дергается счетчик по указанному урлу (параметр url), если звук был выключен
11. fullscreenOn. Дергается счетчик по указанному урлу (параметр url), если приложение перешло в полноэкранный режим
12. fullscreenOff. Дергается счетчик по указанному урлу (параметр url), если приложение вышло из полноэкранного режима

Для секций:

1. sectionStarted. Дергается при запуске секции
2. sectionShown. Дергается при завершении секции.
3. sectionEmpty. Дергается, если запущенная секция пустая.

События плагина. Коммуникация вверх к конечному приложению.

Ниже перечислены методы, принимающие коллбэк-функцию, которой передается объект с параметрами.

onReady — вызывается при окончании инициализации (json загружен, реклама готова) onError — вызывается при всех видах ошибок onStarted — вызывается когда плеер запускает воспроизведение (один раз) onCompleted — вызывается когда плеер заканчивает воспроизведение ролика onPaused — вызывается на паузы onResumed — вызывается на продолжении после паузы ~~onStopped — вызывается, когда прерывается воспроизведение ролика~~ onSkipped — вызывается, когда то же действие инициируется пользователем - пропуск одного баннера onClosed — вызывается, когда пользователь закрыл секцию по кнопке "Закрыть" на баннере (для overlay) - пропуск всей секции onClicked — вызывается по клику на ролик onTimeRemained — вызывается все время во время воспроизведения, передается свойство remained со значением оставшегося времени в секундах adMidrollPoint — отправляется при наступлении позиции, для которой есть midroll реклама. Параметр - массив [{point: point}] — позиция в секундах или [{pointP: pointP}] - позиция в процентах.

Список вызываемых методов

• init — инициализация

• start — стартуем показ рекламы после инициализации

• stop — остановить воспроизведение, нужен для технических целей. Для пользовательского действия есть метод skip()

• skip — пропустить рекламу (user action)

• pause — приостановить воспроизведение

• resume — продолжить воспроизведение, если оно было остановлено

• setPosition — уведомляет библиотеку о текущей позиции видеоролика с передачей общей длительности ролика. Параметры передаются в секундах. Используется при необходимости запускать midroll

• setVolume — установка громкости рекламы (в кач-ве параметра 0...1)

• setFullscreen — то же что fullscreenOn/fullscreenOff, только на входе true/false

• fullscreenOn — пишет статистику по открытию fullscren-режима

• fullscreenOff — пишет статистику по закрытию fullscreen-режима

• destroy — метод для деинициализации (аналогичен stop), удаляющий все DOM объекты и их слушатели.

• getSlot — возвращает текущий SLOT_ID

• setSlot — устанавливает новый SLOT_ID

• getVersion — возвращает текущую версию библиотеки

• setDebug — устанавливает флажок для отправки всех данных в консоль, на входе true/false

Research

Для сбора статистики просмотров и видимости основного контента плеера выделена специальная секция 'research' и дополнительное API. В секции 'research' должен указываться только один баннер с type='research'.

Использование Research API:

Можно использовать основной экземпляр AdmanHTML.

1. В методе init необходимо передать HTMLElement основного плеера - основной video или любой другой HTMLElement, размеры и координаты которого совпадают с размером и координатами основного плеера:

adm.init({
    playerEl: HTMLElement
});

2. Методы Research API:

• adm.research.setPosition(time, duration) - установка текущей позиции видеоролика. Для видео с неопределенной длительностью (стримы) duration=0. Данный метод необходимо вызывать не реже одного раза в секунду
• adm.research.pause() - вызывается при паузе видеоролика
• adm.research.resume() - вызывается при воспроизведении видеоролика после паузы
• adm.research.complete() - вызывается по завершению видеоролика
• adm.research.setVolume(value: Number) - вызывается при изменении громкости видеоролика
• adm.research.setFullscreen(value: Boolean) - вызывается при изменении fullscreen-режима

Разработка

Перейти в директорию с основной версией AdmanHTML и запустить dev-скрипт :

cd adman-ok
grunt develop

Тестовая страница доступна по URL: http://localhost:9001/demo/index.html

Ручная сборка

1. Собрать старые версии Adman - выполнить в корневой директории репозитория

cd grunt
npm install // если еще нет
grunt bump
grunt

После этого убедиться, что в файле /release/admanhtml.spec обновилась версия пакета:

Version:        2.1.56

2. Собрать актуальную версию AdmanHTML:

• Собрать html-прокси файл для VPAID-баннеров

cd adman-ok
npm install // если еще нет
grunt bump
grunt build-html

• Собрать основную библиотеку:

cd adman-ok
grunt build-js

• Коммит + добавить тег вида v%VERSION% (пример - v2.1.56 - git tag -a v2.1.56 -m 'v2.1.56'). Тег обязателен, на основе тегов в пакете собираются все предыдущие версии AdmanHTML, доступные по ссылкам - https://ad.mail.ru/static/admanhtml/2.1.56/rbadman-html5.min.js

• Запушить в мастер В Gitlab-CI автоматически запустится сборка.

Деплой CI/CD

Общая информация о процессе:

1. По пушу в мастер, если были изменения в папке rbadman-html5/adman-ok/out, выполняет сборку библиотеки:

• cd adman-ok
• npm install
• grunt build-js
• grunt build-html

2. Дорабатывает js-файл из предыдущего пункта: находит кусок текста

"function"==typeof define&&define.amd&&define(function(){"use strict";return AdmanHTML}), и заменяет его на такой:

##SetEnv(Adman/norequire,GET,norequire,integer)####SetVars(AdmanNoRequire=##Adman/norequire##)##<!-- IF !Eq(AdmanNoRequire,1) --->"function"==typeof define&&define.amd&&define(function(){"use strict";return AdmanHTML}),<!-- /IF --->

3. Для заливки js формирует json вида:

{
"name":"Adman js lib version X.X.X",
"creative": "custom4887",
"creative.text": "JS_CONTENT"
}

X.X.X - версия adman из package.json JS_CONTENT - контент получившегося js-файла из предыдущего пункта

4. Заливает его в баннер RB по АПИ (креды те же, что и для заливки на mradx):

curl --location --request POST 'https://rb.mail.ru/api/v2/banner/87950802' \
--header 'Authorization: ApiKey target-mobile-automation:TOKEN' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'data=JSON'

кампания с этим баннером раскачена на 100% юзеров т.е. пуш в мастер тригерит раскатку на всех

5. Для заливки html формирует json вида:

{
"name":"Adman vpaid adapter html version X.X.X",
"creative": "html",
"creative.html": "HTML_CONTENT"
}

X.X.X - версия adman из package.json HTML_CONTENT - контент получившегося html-файла из 1 пункта

6. Заливает его в баннер RB по АПИ (креды те же, что и для заливки на mradx):

curl --location --request POST 'https://rb.mail.ru/api/v2/banner/88887736' \
--header 'Authorization: ApiKey target-mobile-automation:TOKEN' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'data=JSON'

кампания с этим баннером раскачена на 100% юзеров т.е. пуш в мастер тригерит раскатку на всех

7. Выставляет тег-версию
8. Пишет в таску комментарий об обеих заливках (номер таски берет из коммита) (например "Adman js lib and html adapter has been successfully deployed to 100%, version: x.x.x")
9. Заливает js и html в registry проекта 

Описание шагов конвеера gitlab CI:

• build - собирает библиотеку, пушит новыую версию в мастер, ставит тэг, формирует json'ы для дольнейшей заливки на RB. Сохраняет в артифактах: сформированные json'ы, adman-ok/out/rbadman-html5.min.js и adman-ok/out/vpaid-js-interface.htm
• deploy - заливает все в баннер RB по АПИ
• jira - пишет отчет в таску Jira
• registry - Заливает js и html в registry проекта

Все скрипты лежат в папке .ci в корне проекта и написаны на python.

Ручная раскатка на тестовый регион.

В каждом бранче есть возможность запустить шаг раскатки на тестовый регион. Для этого в gitlab в разделе ci/cd выбрать нужный пайплайн, зайти в него и нажать на кнопку play в шаге manual deploy. Раскатится на id 90878148