Документация KVS

Flash / HTML5 видео плеер Kernel Team v5.x

Содержание

1. Общая информация

Видео плеер Kernel Team разработан с учетом основных требований монетизации ресурса. Плеер поддерживает возможность использования огромного количества рекламы в различных местах и при различных событиях, например: pre-roll, post-roll реклама, реклама на паузе или остановке видео, рекламная ссылка в контролбаре плеера, логотип со ссылкой и т.д.

Плеер работает в двух режимах: обычный режим и "embed" режим. Обычный режим предназначен для использования плеера на "родном" сайте. Режим "embed" включается в том случае, если ваш плеер загружается c другого ресурса. В этом режиме конфигурация рекламы плеера не может быть перекрыта извне, таким образом, если кто-то показывает embed код с вашим видео на другом сайте, ваша реклама не может быть перекрыта или удалена. Более того, настройка плеера в "embed" режиме осуществляется вами в одном месте, таким образом, если вы захотите изменить настройки рекламы - эти настройки мгновенно отразятся на всех сайтах, которые используют ваш embed код.

Видео плеер Kernel Team может использоваться бесплатно без каких-либо ограничений.

2. Установка плеера

Для установки плеера вам необходимо выполнить следующие шаги:

  • Распакуйте архив с файлами плеера в директорию /%DOMAIN_ROOT%/kt_player. Если вы хотите установить плеер в другую директорию, убедитесь, что вы заменили директорию в .htaccess файле плеера.
  • В файле /%DOMAIN_ROOT%/kt_player/.htaccess замените токен %DOMAIN% на название вашего домена.
  • Скопируйте файл crossdomain.xml в корень вашего домена. Если вы планируете использовать видео или изображения, которые хостятся на других доменах (и сабдоменах), вам необходимо скопировать этот файл на все другие домены (сабдомены), с которых плеер будет что-то использовать.

Важно! Любые SWF файлы, которые используются в плеере через API должны быть реализованы на ActionScript3.

3. Включение плеера в HTML код страницы сайта

Плеер вставляется через JavaScript код, используя скрипт kt_player.js. Код вставки плеера на страницу выглядит следующим образом (предполагая, что вы скопировали плеер в директорию /kt_player):

<!-- подключаем JavaScript -->
<script type="text/javascript" src="/kt_player/kt_player.js"></script>

<!-- задаем пустой контейнер для плеера, id="kt_player" идентифицирует его -->
<div id="kt_player" style="visibility: hidden">
    <a href="http://adobe.com/go/getflashplayer">This page requires Adobe Flash Player</a>
</div>

<!-- используем код вставки плеера -->
<script type="text/javascript">
    // указываем список всех переменных инициализации (для примера указаны только 2)
    var flashvars = {
        video_url: 'http://domain.com/kt_player/demo/demo_video.mp4',
        preview_url: 'http://domain.com/kt_player/demo/demo_preview.jpg'
    };

    // указываем параметры HTML объекта плеера
    var params = {allowfullscreen: 'true', allowscriptaccess: 'always'};

    // вызываем функцию вставки плеера
    // 'kt_player' - идентификатор контейнера для плеера
    // '/kt_player/kt_player.swf' - путь к файлу плеера
    // '600' - ширина плеера
    // '400' - высота плеера
    // flashvars - список всех переменных инициализации, созданный выше
    // params - список всех параметров HTML объекта плеера, созданный выше
    var player_obj = kt_player('kt_player', '/kt_player/kt_player.swf', '600', '400', flashvars, params);

    // используйте player_obj для обработки событий (см. секцию по JavaScript API)
</script>

В результате отработки JavaScript функции плеер вставится в div контейнер с id="kt_player". В большинстве случаев вам необходимо только изменить набор переменных, которые задаются в объекте flashvars и размеры плеера (600х400).

4. Flash vs HTML5 mode

Видео плеер Kernel Team поддерживает базовый HTML5 режим для проигрывания ваших видео на мобильных устройствах. Плеер использует следующий алгоритм для определения, в каком режиме показывать видео:

Режим Описание Условия
Flash По умолчанию. Работает для большинства десктопных устройств. Браузер должен поддерживать Flash.
HTML5 видео Отображается встроенный в браузер HTML5 плеер. Данный режим поддерживает только JavaScript рекламу (через JS API плеера). Работает на большинстве мобильных устройств. (a) Браузер не поддерживает Flash.
(b) Видео имеет MP4 контейнер (h264 кодек).
(c) Браузер поддерживает проигрывание MP4 формата.
Встроенный режим видео Отображается простая ссылка на MP4 файл. Работает на большинстве мобильных устройств. (a) Браузер не поддерживает Flash.
(b) Видео имеет MP4 контейнер (h264 кодек).
(c) Браузер не поддерживает проигрывание MP4 формата.

Важно! HTML5 / Встроенный режимы могут использоваться только с MP4 файлами. Все современные мобильные устройства поддерживают проигрывание MP4 файлов.

5. Переменные инициализации плеера

Переменные инициализации плеера (FlashVars) используются для установки контента, рекламы и других опций плеера. Таблица, приведенная ниже, перечисляет все переменные инициализации, которые поддерживаются плеером:

Название переменной Описание
scaling Позволяет указать алгоритм масштабирования видео. Если переменная не задана, то видео будет масштабироваться плеером с сохранением пропорций и добавлением черных вертикальных или горизонтальных полос. Если задано значение fill, то видео будет полностью заполнять область плеера игнорируя пропорции (т.е. изображение будет либо расширяться, либо сужаться). При указании значения crop видео будет полностью заполнять область плеера, однако в отличие от предыдущего значения пропорции будут сохраняться, но видео будет обрезано либо по высоте (снизу и сверху), либо по ширине (справа и слева).
license_code Код лицензии (необязателен).
video_url Ссылка на FLV / MP4 видео файл.
preview_frame Кадр из видео (в секундах), который отображается плеером до начала проигрывания видео.
preview_url Ссылка на изображение, которое отображается плеером до начала проигрывания видео (как правило это превью видео).
flv_stream Должен быть установлен в значение false, если сервер не поддерживает стриминг.
autoplay Если переменная используется со значением true, то видео начнет проигрываться автоматически. Если переменная не используется, то пользователь должен будет вручную запустить проигрывание видео.
logo_src Ссылка на изображение вашего логотипа (jpg, png), которое будет показываться плеером поверх видео.
logo_position Координаты расположения логотипа (задаются в квадратных скобках через запятую - [x,y]). Начало отсчета - левый верхний угол плеера.
logo_url URL выхода при клике на логотип.
video_click_url URL выхода при клике мышкой на область воспроизведения видео. Если не задан (по умолчанию), то при клике на область видео плеер будет переводиться в режим паузы.
bt Кол-во времени ролика в секундах, которое будет буферизироваться до начала показа. По умолчанию используется значение в 5 секунд.
skin Поддерживает 2 типа скина: 1 - темный (по умолчанию), 2 - светлый.
hide_controlbar Настраивает поведение панели управления: 0 - всегда показывать (по умолчанию), 1 - прятать автоматически если пользователь неактивен, 2 - не показывать никогда.
mlogo Рекламный текст, который будет отображаться справа на контролбаре.
mlogo_link URL выхода при клике на текст, заданный переменной mlogo.
embed Включает отображение embed кода внутри плеера, если установлено значение 1. По умолчанию embed код не отображается. Сам HTML код должен быть предоставлен плееру через JavaScript API (описано ниже).
permalink_url URL на страницу с данным видео на вашем сайте. Если задан, то плеер будет отображать выплывающую иконку, позволяющую скопировать данный URL.
urls_in_same_window Глобальная переменная, которая заставляет плеер открывать все ссылки в этом же окне браузера. Для включения установите значение 1.
prtext Используется для периодического отображения небольшого текста в случайных углах плеера. Это можно использовать для защиты стримового контента от экранных грабберов (например, отображать IP пользователя).
prtime Интервал в секундах через который будет отображаться текст, указанный в переменной prtext.
related Ссылка на SWF файл, который отображает похожие видео. По умолчанию с плеером поставляется файл related.swf и его исходный код related.fla.
related_data Ссылка на xml файл конфигурации похожих видео. Файл перечисляет названия, скриншоты и ссылки на похожие видео (пример такого файла поставляется с плеером: related.xml).
timeline_screens_url Ссылка на xml файл конфигурации отображения таймлайновых скриншотов. Файл перечисляет ссылки на скриншоты, которые соответствуют ключевым кадрам видео (пример такого файла поставляется с плеером: key.xml).
timeline_screens_interval Интервал показа таймлайновых скриншотов.
video_url_text Название стартового потока видео. Будет отображаться только при использовании переменной video_alt_url (см. ниже).
video_alt_url
video_alt_url_text
video_alt_url_redirect
Данный набор переменных используется для включения выпадающего списка нескольких потоков видео (например, 480p, 720p HD). Если переменная video_alt_url включена, то в контролбаре плеера появится выпадающий список с 2 элементами: (1) первый элемент проигрывает видео, которое задано переменной video_url и имеет название, которое задано переменной video_url_text; (2) второй элемент имеет название video_alt_url_text и при его выборе либо отображает видео, заданное переменной video_alt_url, либо перенаправляет пользователя на страницу, заданную этой же переменной video_alt_url, если video_alt_url_redirect равен 1. Пример использования будет дан ниже.
video_alt_url2
video_alt_url2_text
video_alt_url2_redirect
Используется аналогично предыдущему набору переменных для отображения третьего элемента в выпадающем списке потоков видео.
video_alt_url3
video_alt_url3_text
video_alt_url3_redirect
Используется аналогично предыдущему набору переменных для отображения четвертого элемента в выпадающем списке потоков видео.
video_alt_url4
video_alt_url4_text
video_alt_url4_redirect
Используется аналогично предыдущему набору переменных для отображения пятого элемента в выпадающем списке потоков видео.
adv_pre_src Ссылка на файл pre-roll рекламы (видео - flv, swf, либо изображение - jpg, png).
adv_pre_duration Длительность показа pre-roll рекламы в секундах (применяется только для изображений).
adv_pre_url Ссылка, по которой уйдет пользователь, кликнув на pre-roll рекламу.
adv_post_src Ссылка на файл post-roll рекламы (видео - flv, swf, либо изображение - jpg, png).
adv_post_duration Длительность показа post-roll рекламы в секундах (применяется только для изображений).
adv_post_url Ссылка, по которой уйдет пользователь, кликнув на post-roll рекламу.
adv_pause_src Ссылка на файл рекламы во время паузы (изображение - jpg, png).
adv_pause_url Ссылка, по которой уйдет пользователь, кликнув на рекламу во время паузы.
adv_stop_src Ссылка на файл рекламы во время остановки (изображение - jpg, png).
adv_stop_url Ссылка, по которой уйдет пользователь, кликнув на рекламу во время остановки.
sec Задает ограничение в секундах на длительность показа видео. Таким образом, независимо от реальной длительности видео пользователь всегда сможет посмотреть только первые N секунд ( число которых как раз и задается этой переменной). Важно! Данная переменная работает корректно только при отсутствии стриминга (см. переменную flv_stream).

Рассмотрим небольшой пример использования альтернативных потоков видео. Предположим, что нужно отобразить 3 элемента в выпадающем списке потоков:

  • 360p - показывает видео с разрешением в 360 пикселей по высоте.
  • 480p - показывает видео с разрешением в 420 пикселей по высоте.
  • 720p HD - делает редирект на страницу регистрации (оплаты), т.к. видео в HD качестве доступно только зарегистрированным пользователям сайта.

Переменные инициализации, которые нужно указывать для рассматриваемого варианта:

  • video_url = http://domain.com/videos/my_video_360.mp4 (будет выбран и показываться по умолчанию)
  • video_url_text = 360p
  • video_alt_url = http://domain.com/videos/my_video_480.mp4 (будет показываться при переключении на этот поток)
  • video_alt_url_text = 480p
  • video_alt_url2 = http://domain.com/signup.php (будет сделан редирект при переключении на этот поток)
  • video_alt_url2_text = 720p HD
  • video_alt_url2_redirect = 1

Важно! Плеер может использовать файлы (изображения / видео) с других доменов и субдоменов только в том случае, если в корне этих доменов и субдоменов находится файл crossdomain.xml с разрешением использования контента для вашего домена. Этот файл поставляется вместе с плеером и должен быть разнесен на все домены и субдомены, контент с которых вы хотите использовать.

При работе в "embed" режиме все переменные инициализации задаются через файл embed.xml, который находится в той же директории, где и сам плеер.

6. JavaScript API плеера

JavaScript API используется для указанию плееру embed кода, который должен отображаться внутри плеера (если переменная инициализации embed = 1). Для того, чтобы указать плееру embed код, вам необходимо добавить следующую JavaScript функцию на странице с плеером:

function getEmbed() {
    return '%EMBED_CODE_GOES_HERE%';
}

В данной функции необходимо заменить токен %EMBED_CODE_GOES_HERE% на embed код, который вы хотите вывести в плеере. Существует несколько вариаций embed кодов:

  • Классический embed код - поддерживает только Flash плеер и не позволяет использовать JavaScript API плеера: <object id="kt_player" name="kt_player" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0" width="600" height="400">
        <param name="allowscriptaccess" value="always"/>
        <param name="allowFullScreen" value="true"/>
        <param name="movie" value="http://%YOUR_DOMAIN_HERE%/kt_player/kt_player.swf"/>
        <param name="flashvars" value="video_url=%VIDEO_URL%&amp;preview_url=%PREVIEW_IMAGE_URL%"/>
        <embed src="http://%YOUR_DOMAIN_HERE%/kt_player/kt_player.swf?video_url=%VIDEO_URL%&amp;preview_url=%PREVIEW_IMAGE_URL%" width="600" height="400" allowfullscreen="true" allowscriptaccess="always" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer"/>
    </object>
  • Iframe embed код - предоставляется в виде iframe, который ссылается на страницу вашего сайта, на которой находится плеер. В отличие от классического кода поддерживает все режимы отображения плеера, а также позволяет использовать JavaScript API в полной мере. Использование этого embed кода подразумевает, что на вашем сайте реализован функционал, который по переданному идентификатору видео (%VIDEO_ID%) будет отображать страницу с плеером для этого видео. <iframe width="600" height="400" src="http://%YOUR_DOMAIN_HERE%/embed/%VIDEO_ID%" frameborder="0" allowfullscreen webkitallowfullscreen mozallowfullscreen oallowfullscreen msallowfullscreen></iframe>

Важно! Если вы не объявляете функцию getEmbed() и не возвращаете плееру embed код - то плеер сгенерит его самостоятельно исходя из переменных инициализации, которые переданы ему самому. В этом случае размеры плеера в embed коде будут установлены такие же, как и при отображении плеера у вас на странице. Вы можете использовать функцию getEmbed() для выдачи embed кода с другими данными, например, размерами.

Плеер поддерживает JavaScript колбэки на многие события. Вы можете использовать эти колбэки по своему усмотрению:

var player_obj = kt_player('kt_player', '/kt_player/kt_player.swf', '600', '400', flashvars, params);
player_obj.listen('ktVideoStarted', function() {alert('Video started');});
player_obj.listen('ktVideoPaused', function() {alert('Video paused');});
player_obj.listen('ktVideoStopped', function() {alert('Video stopped');});
player_obj.listen('ktVideoScrolled', function(time) {alert('Video scrolled to ' + time + ' seconds');});
player_obj.listen('ktVideoProgress', function(time) {alert('Video played to ' + time + ' seconds');});
player_obj.listen('ktVideoFinished', function() {alert('Video finished');});
player_obj.listen('ktFullScreenActivated', function() {alert('Player goes to full screen mode');});
player_obj.listen('ktFullScreenDeactivated', function() {alert('Player goes to normal mode');});
player_obj.listen('ktPreRollStarted', function() {alert('Configured pre-roll ad started');});
player_obj.listen('ktPreRollFinished', function() {alert('Configured pre-roll ad finished');});
player_obj.listen('ktPostRollStarted', function() {alert('Configured post-roll ad started');});
player_obj.listen('ktPostRollFinished', function() {alert('Configured post-roll ad finished');});

player_obj.listen('ktVideoFormatChanging', function(format) {
    alert('Video format is attempted to be changed to: ' + format);
    // этот обработчик может использоваться для показа пользователю HTML содержимого при попытке переключить формат
    // функция должна вернуть 'true' (как строку), если вы хотите чтобы плеер отменил действие по умолчанию
});

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

function kt_player_loaded(player_obj) {
    // настройка перехвата событий
    player_obj.listen(...);
}

Во время инициализации плеер изменяет CSS стили его DIV-контейнера, чтобы можно было легко показывать внутри контейнера HTML слои поверх плеера (например, рекламу, всплывающие баннеры, доп. меню). Таким образом, можно добавлять слои с абсолютным позиционированием в DOM структуру контейнера.

стиль контейнера {
    width: 600px;
    height: 400px;
    position: relative;
    overflow: hidden;
}

Дополнительное API по управлению плеером:

// получить DIV-элемент контейнера
player_obj.container();

// запустить проигрывание
player_obj.play();

// приостановить проигрывание
player_obj.pause();

7. Список файлов для плеера

Данный список перечисляет все файлы, которые поставляются вместе с плеером и их предназначение:

Имя файла Описание
.htaccess Содержит правила mod_rewrite, согласно которым все запросы на плеер с других доменов переключают плеер в "embed" режим.
btn_play.jpg Кнопка начала проигрывания, которая показывается в центре плеера в HTML5 / встроенном режиме.
embed.php Файл редиректа на плеер в "embed" режиме. Работает совместно с .htaccess.
embed.xml Файл настройки переменных инициализации плеера в "embed" режиме. Заполняя его, вы настраиваете поведение вашего плеера для посетителей других доменов.
example.html Пример подключения плеера на страницу.
expressInstall.swf Файл инсталляции Flash плеера, предоставленный Adobe.
kt_player.js JavaScript файл для подключения плеера на страницу.
kt_player.swf Файл плеера.
demo/crossdomain.xml Этот файл нужно копировать в корень всех доменов (и субдоменов), с которых плеер загружает какие-либо данные.
demo/key.xml Пример файла настройки отображения таймлайновых скриншотов (путь на сам файл должен указываться плееру в переменной инициализации timeline_screens_url).
demo/keyX.jpg Примеры таймлайновых скриншотов.
demo/related.fla Исходный код / шаблон модуля отображения похожих видео.
demo/related.swf Модуль отображения похожих видео (путь на модуль должен указываться плееру в переменной инициализации related).