Витрины Rutube - способ организации и представления видео-контента, используемый на портале rutube.ru. Одним из примеров контента, представленного с помощью витрин, может служить главная страница портала. Используя API партнеры Rutube имеют возможность разработать подобный тип представления видео-роликов на своей площадке.
Технически, витрины состоят из вкладок, каждая из которых может содержать один или несколько источников карточек, например, один или несколько тегов или несколько телешоу. Каждый источник, являясь отдельной сущностью внутри платформы Rutube, требует отдельного запроса к API для получения контента (списка видео-роликов). Количество источников на одной вкладке не ограничено, также нет ограничений по смешиванию типов. Например, на одной вкладке могут быть представлены теги, телешоу и ролики пользователей. Карточки для каждого источника подгружаются постранично и могут смешиваться любым способом перед отрисовкой на странице.
Набор вкладок и источников для каждой витрины задается редакторами Rutube.
Кроме того, каждая вкладка имеет поле для задания внешней ссылки, и если оно не пустое, есть возможность при переходе на вкладку не показывать карточки, а делать переадресацию на указанный адрес.
Работа витрин построена на основе нескольких API, запрашиваемых в определенной последовательности.
Ответы API могут быть получены в форматах JSON, JSONP и XML.
Примеры запросов:
https://rutube.ru/api/feeds/tnt?format=json
https://rutube.ru/api/feeds/tnt?format=jsonp&callback=foobar
https://rutube.ru/api/feeds/tnt?format=xml
А также в удобном для чтения виде:
https://rutube.ru/api/feeds/tnt?format=api
Работа с витриной начинается с обращения к ее API. С помощью ответа этого API выстраивается меню вкладок и становятся доступны адреса источников, из которых в дальнейшем будут получены карточки.
Шаблон запроса API витрины:
https://rutube.ru/api/feeds/slug
где slug - уникальный идентификатор витрины.
Пример запроса:
https://rutube.ru/api/feeds/tnt
Основные поля, содержащиеся в ответе:
id - [ number ] id витрины;
slug - [ string ] идентификатор витрины;
name - [ string ] название витрины;
meta_description - [ string ] описание витрины;
page_url - [ string ] адрес витрины на rutube.ru;
tabs - [ array ] массив вкладок витрины.
Ключевым полем является tabs, в котором перечислены вкладки витрины.
Поля, которые содержат элементы в массиве tabs:
id - [ number ] id вкладки;
name - [ string ] название вкладки;
sort - [ string ] сортировка карточек;
order_number - [ number ] порядковый номер вкладки;
slug - [ string || null ] уникальное название вкладки (для hash- или history-навигации);
resources - [ array ] массив источников карточек;
link - [ string || null ] внешняя ссылка (опционально).
Располагая массивом tabs из ответа API витрины, можно построить меню.
Каждый из элементов tabs, в свою очередь, содержит массив resources с перечислением источников карточек.
Поля элементов в массиве resources:
id - [ number ] id источника;
object_id - [ string ] служебный id источника внутри платформы Rutube;
content_type - [ object ] объект с информацией об источнике;
url - [ string ] адрес для получения карточек.
Поле url является адресом, по которому необходимо запрашивать список роликов источника.
Совет! Рекомендуется рассматривать запросы к источникам одной вкладки как deferred-объекты. Это обеспечит равномерность работы интерфейса при загрузке и отрисовке карточек.
Возможные типы источников (объект content_type):
tv - ТВ-шоу;
tvlastepisode - последний эпизод конкретного ТВ-шоу;
person - персона, например, эстрадный исполнитель. Не путать с пользователем Rutube;
tag - тег;
cardgroup - группа карточек (ссылки на другие источники). На rutube.ru выглядит как карточка с кнопкой “Подписаться” и возможностью перехода на страницу этого источника);
userchannel - пользователь Rutube;
promogroup, promofeed - источники, содержащие промо-элементы (не ролики).
При запросе источника карточек в ответ приходят следующие поля:
next - [ string || null ] адрес для запроса следующей страницы;
previous - [ string || null ] адрес для запроса предыдущей страницы;
page - [ number ] номер запрошенной страницы с карточками;
has_next - [ boolean ] наличие следующей страницы;
results - [ array ] массив карточек.
Значение массива results и есть список видео-роликов источника.
Также стоит обратить внимание на поле thumbnail_url - картинка-превью. С помощью параметра size можно выбрать размер изображения, например:
https://pic.rutube.ru/video/d4/52/d452e0d567ce6ca5035d712279d3b9bb.jpg?size=m
Доступно три размера: large, medium, small.
В витринах имеются гибкие возможности для задания сортировки карточек, и, соответственно, возможности для отображения карточек на странице в определенном порядке. Например, ролики сериала могут быть показаны от большей серии к меньшей, или наоборот.
Возможности сортировки можно разделить на две составляющие: задание сортировки конкретным источникам на вкладке, и сортировка результатов, полученных из нескольких источников перед отображением на странице.
Каждый тип источника может принимать определенные значения сортировки.
| Тип источника | Название параметра | Возможные значения |
|---|---|---|
| tv | sort | series_a, series_d, created_a, created_d, publication_a, publication_d |
| tvlastepisode | ||
| person | ||
| tag | sort | tagged_a, tagged_d, created_a, created_d, publication_a, publication_d |
| cardgroup | ||
| userchannel | ordering | publication_ts, created_ts, views, id. Можно также задавать обратные значения этих параметров, например, -created_ts, а также комбинировать их через запятую, например, -created_ts,-id. |
Эти значения необходимо подставлять к url при запросе источника. Например, для источника типа ТВ-шоу:
https://rutube.ru/api/metainfo/tv/28/video?sort=series_d
Сортировка результатов, полученных из нескольких источников может быть реализована на усмотрение разработчика. Однако, есть возможность принять во внимание мнение редакции по поводу того, как лучше всего сортировать карточки на конкретной вкладке. Эта рекомендация присутствует всегда и указана в поле sort для каждой вкладки (в массиве tabs в ответе API витрины).
Возможные значения поля sort:
created_date - смешать ролики и вывести их по дате в порядке убывания;
original - смешать ролики и вывести их по возрастанию индекса в массиве ответа;
random - смешать ролики и вывести в случайном порядке.
Помимо сортировки, источники могут принимать несколько других параметров.
origin__type - фильтр роликов конкретной платформы. Возможные значения:
rtb - ролики Rutube, исключая live-трансляции;
rst - live-трансляции Rutube;
ytb - ролики Youtube;
vim - ролики Vimeo;
now - ролики NOW.RU.
На Rutube могут присутствовать ролики других платформ, и для гарантированной отдачи роликов именно Rutube желательно подставлять этот параметр при каждом запросе источника, например:
https://rutube.ru/api/metainfo/tv/28/video?origin__type=rtb,rst
season, episode - комбинируемые параметры, которые могут принимать источники типа ТВ-шоу, например:
https://rutube.ru/api/metainfo/tv/28/video?season=1&episode=2
В результате этого запроса будет получена вторая серия первого сезона сериала “Интерны”.