└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Руководство по разработке витрин на основе API Rutube 2 | 3 | Витрины Rutube - способ организации и представления видео-контента, используемый на портале [rutube.ru](https://rutube.ru). Одним из примеров контента, представленного с помощью витрин, может служить главная страница портала. Используя API партнеры Rutube имеют возможность разработать подобный тип представления видео-роликов на своей площадке. 4 | 5 | ## Техническая реализация 6 | 7 | Технически, витрины состоят из вкладок, каждая из которых может содержать один или несколько источников карточек, например, один или несколько тегов или несколько телешоу. Каждый источник, являясь отдельной сущностью внутри платформы Rutube, требует отдельного запроса к API для получения контента (списка видео-роликов). Количество источников на одной вкладке не ограничено, также нет ограничений по смешиванию типов. Например, на одной вкладке могут быть представлены теги, телешоу и ролики пользователей. Карточки для каждого источника подгружаются постранично и могут смешиваться любым способом перед отрисовкой на странице. 8 | 9 | Набор вкладок и источников для каждой витрины задается редакторами Rutube. 10 | 11 | Кроме того, каждая вкладка имеет поле для задания внешней ссылки, и если оно не пустое, есть возможность при переходе на вкладку не показывать карточки, а делать переадресацию на указанный адрес. 12 | 13 | Работа витрин построена на основе нескольких API, запрашиваемых в определенной последовательности. 14 | 15 | Ответы API могут быть получены в форматах JSON, JSONP и XML. 16 | 17 | Примеры запросов: 18 | 19 | ``` 20 | https://rutube.ru/api/feeds/tnt?format=json 21 | https://rutube.ru/api/feeds/tnt?format=jsonp&callback=foobar 22 | https://rutube.ru/api/feeds/tnt?format=xml 23 | ``` 24 | 25 | А также в удобном для чтения виде: 26 | 27 | ``` 28 | https://rutube.ru/api/feeds/tnt?format=api 29 | ``` 30 | 31 | ## API витрины 32 | 33 | Работа с витриной начинается с обращения к ее API. С помощью ответа этого API выстраивается меню вкладок и становятся доступны адреса источников, из которых в дальнейшем будут получены карточки. 34 | 35 | Шаблон запроса API витрины: 36 | 37 | ``` 38 | https://rutube.ru/api/feeds/slug 39 | ``` 40 | 41 | где `slug` - уникальный идентификатор витрины. 42 | 43 | Пример запроса: 44 | 45 | ``` 46 | https://rutube.ru/api/feeds/tnt 47 | ``` 48 | 49 | Основные поля, содержащиеся в ответе: 50 | 51 | `id` - [ _number_ ] id витрины; 52 | 53 | `slug` - [ _string_ ] идентификатор витрины; 54 | 55 | `name` - [ _string_ ] название витрины; 56 | 57 | `meta_description` - [ _string_ ] описание витрины; 58 | 59 | `page_url` - [ _string_ ] адрес витрины на rutube.ru; 60 | 61 | `tabs` - [ _array_ ] массив вкладок витрины. 62 | 63 | Ключевым полем является `tabs`, в котором перечислены вкладки витрины. 64 | 65 | Поля, которые содержат элементы в массиве `tabs`: 66 | 67 | `id` - [ _number_ ] id вкладки; 68 | 69 | `name` - [ _string_ ] название вкладки; 70 | 71 | `sort` - [ _string_ ] сортировка карточек; 72 | 73 | `order_number` - [ _number_ ] порядковый номер вкладки; 74 | 75 | `slug` - [ _string_ || _null_ ] уникальное название вкладки (для hash- или history-навигации); 76 | 77 | `resources` - [ _array_ ] массив источников карточек; 78 | 79 | `link` - [ _string_ || _null_ ] внешняя ссылка (опционально). 80 | 81 | Располагая массивом `tabs` из ответа API витрины, можно построить меню. 82 | 83 | Каждый из элементов `tabs`, в свою очередь, содержит массив `resources` с перечислением источников карточек. 84 | 85 | Поля элементов в массиве `resources`: 86 | 87 | `id` - [ _number_ ] id источника; 88 | 89 | `object_id` - [ _string_ ] служебный id источника внутри платформы Rutube; 90 | 91 | `content_type` - [ _object_ ] объект с информацией об источнике; 92 | 93 | `url` - [ _string_ ] адрес для получения карточек. 94 | 95 | Поле `url` является адресом, по которому необходимо запрашивать список роликов источника. 96 | 97 | _Совет! Рекомендуется рассматривать запросы к источникам одной вкладки как deferred-объекты. Это обеспечит равномерность работы интерфейса при загрузке и отрисовке карточек._ 98 | 99 | Возможные типы источников (объект `content_type`): 100 | 101 | `tv` - ТВ-шоу; 102 | 103 | `tvlastepisode` - последний эпизод конкретного ТВ-шоу; 104 | 105 | `person` - персона, например, эстрадный исполнитель. Не путать с пользователем Rutube; 106 | 107 | `tag` - тег; 108 | 109 | `cardgroup` - группа карточек (ссылки на другие источники). На [rutube.ru](http://rutube.ru/) выглядит как карточка с кнопкой “Подписаться” и возможностью перехода на страницу этого источника); 110 | 111 | `userchannel` - пользователь Rutube; 112 | 113 | `promogroup`, `promofeed` - источники, содержащие промо-элементы (не ролики). 114 | 115 | ## API источников 116 | 117 | При запросе источника карточек в ответ приходят следующие поля: 118 | 119 | `next` - [ _string_ || _null_ ] адрес для запроса следующей страницы; 120 | 121 | `previous` - [ _string_ || _null_ ] адрес для запроса предыдущей страницы; 122 | 123 | `page` - [ _number_ ] номер запрошенной страницы с карточками; 124 | 125 | `has_next` - [ _boolean_ ] наличие следующей страницы; 126 | 127 | `results` - [ _array_ ] массив карточек. 128 | 129 | Значение массива `results` и есть список видео-роликов источника. 130 | 131 | Также стоит обратить внимание на поле `thumbnail_url` - картинка-превью. С помощью параметра `size` можно выбрать размер изображения, например: 132 | 133 | ``` 134 | https://pic.rutube.ru/video/d4/52/d452e0d567ce6ca5035d712279d3b9bb.jpg?size=m 135 | ``` 136 | 137 | Доступно три размера: `l`arge, `m`edium, `s`mall. 138 | 139 | ## Сортировка карточек 140 | 141 | В витринах имеются гибкие возможности для задания сортировки карточек, и, соответственно, возможности для отображения карточек на странице в определенном порядке. Например, ролики сериала могут быть показаны от большей серии к меньшей, или наоборот. 142 | 143 | Возможности сортировки можно разделить на две составляющие: задание сортировки конкретным источникам на вкладке, и сортировка результатов, полученных из нескольких источников перед отображением на странице. 144 | 145 | #### Задание сортировки источнику 146 | 147 | Каждый тип источника может принимать определенные значения сортировки. 148 | 149 | | Тип источника | Название параметра | Возможные значения | 150 | |---------------|--------------------|--------------------| 151 | | tv | sort | `series_a`, `series_d`, `created_a`, `created_d`, `publication_a`, `publication_d` | 152 | | tvlastepisode | | | 153 | | person | | | 154 | | tag | sort | `tagged_a`, `tagged_d`, `created_a`, `created_d`, `publication_a`, `publication_d` | 155 | | cardgroup | | | 156 | | userchannel | ordering | `publication_ts`, `created_ts`, `views`, `id`. Можно также задавать обратные значения этих параметров, например, `-created_ts`, а также комбинировать их через запятую, например, `-created_ts,-id`. | 157 | 158 | Эти значения необходимо подставлять к `url` при запросе источника. Например, для источника типа ТВ-шоу: 159 | 160 | ``` 161 | https://rutube.ru/api/metainfo/tv/28/video?sort=series_d 162 | ``` 163 | 164 | #### Сортировка результатов перед выводом на страницу 165 | 166 | Сортировка результатов, полученных из нескольких источников может быть реализована на усмотрение разработчика. Однако, есть возможность принять во внимание мнение редакции по поводу того, как лучше всего сортировать карточки на конкретной вкладке. Эта рекомендация присутствует всегда и указана в поле `sort` для каждой вкладки (в массиве `tabs` в ответе API витрины). 167 | 168 | Возможные значения поля `sort`: 169 | 170 | `created_date` - смешать ролики и вывести их по дате в порядке убывания; 171 | 172 | `original` - смешать ролики и вывести их по возрастанию индекса в массиве ответа; 173 | 174 | `random` - смешать ролики и вывести в случайном порядке. 175 | 176 | ## Дополнительные параметры для источников 177 | 178 | Помимо сортировки, источники могут принимать несколько других параметров. 179 | 180 | `origin__type` - фильтр роликов конкретной платформы. Возможные значения: 181 | 182 | `rtb` - ролики Rutube, исключая live-трансляции; 183 | 184 | `rst` - live-трансляции Rutube; 185 | 186 | `ytb` - ролики Youtube; 187 | 188 | `vim` - ролики Vimeo; 189 | 190 | `now` - ролики NOW.RU. 191 | 192 | На Rutube могут присутствовать ролики других платформ, и для гарантированной отдачи роликов именно Rutube желательно подставлять этот параметр при каждом запросе источника, например: 193 | 194 | ``` 195 | https://rutube.ru/api/metainfo/tv/28/video?origin__type=rtb,rst 196 | ``` 197 | 198 | `season`, `episode` - комбинируемые параметры, которые могут принимать источники типа ТВ-шоу, например: 199 | 200 | ``` 201 | https://rutube.ru/api/metainfo/tv/28/video?season=1&episode=2 202 | ``` 203 | 204 | В результате этого запроса будет получена вторая серия первого сезона сериала “Интерны”. 205 | --------------------------------------------------------------------------------