/
Интеграция оператора с VoD библиотекой

Интеграция оператора с VoD библиотекой

Инструкция по работе с VoD контентом, размещенном на Платформе24

Данная инструкция описывает основные и необходимые действия, которые необходимо произвести оператору партнёру для организации доступа своим пользователям для целей просмотра VoD контента.

Основные этапы

  • Получить у владельцев платформы технический доступ к панели администратора. В дальнейшем он будет использоваться и для доступа к описанию методов API. Также необходимо запросить ID библиотеки

  • Получить у владельцев платформы доступ к файлу с выгрузкой мета-данных контента для последующего импорта.
    ВНИМАНИЕ: Если JSON файл с мета-данными будет открываться в браузере, то из-за особенностей реализации java-script, ID используемые в файле могут отображаться не корректно.

  • В панели администратора получить TOKEN оператора. Полученный TOKEN будет использоваться для подписания всех запросов к API при работе интеграции, кроме запроса стрима. При запросе стрима используется пользовательский токен полученный по device_id.
    ВАЖНО: При повторной генерации токена, ранее выданный токен будет инвалидирован (отключён)

  • Реализовать логику регистрации пользователя в Платформа24

  • Реализовать управление подписками пользователя в Платформа24 (Назначение/Отключение подписки)

  • Реализовать получение потока запрашиваемого контента для пользователя оператора

VoD for external platforms (1).svg

 

Исходник:

Методы вызываемые с BackEnd

Регистрация пользователя

Для полноценного управления услугой/подпиской необходимо создать пользователя в платформе.
Позже созданному пользователю будут назначаться соответствующие подписки.

Общая документация по методу создания пользователя здесь: https://$platform_name$.platform24.tv/v2/doc/provider/redoc#tag/users/operation/users_create

Для создания пользователя необходимо использовать метод

POST /v2/users

Обязательными полями являются username и password

{ "username": "string", // Не может содержать точки в имени пользователя "first_name": "string", "last_name": "string", "provider_uid": "string", "email": "user@example.com", "password": "string", "device_limit": 0, "is_active": true }

Нижеприведенный запрос создаёт пользователя с логином tele_720 и паролем 2472024. При этом устанавливается provider_uid равный 720. 720 это идентификатор пользователя у вас как у оператора (Например номер договора)

curl -X 'POST' \ 'https://$platform_name$.platform24.tv/v2/users?token=21de6432fdc13f2d78f28eebdb46960e' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'X-CSRFTOKEN: 9ewDrRwnm4gDhH7rrEl4Q1o5yd4GnouM9weVEnwXlCwb8QcAeJoHWkqDY7qx21eB' \ -d '{ "username": "tele_720", "provider_uid": "720", "password": "2472024" }'

В результате запроса будут возвращены данные в json формате.
В ответе будет содержаться идентификатор пользователя в платформе (ID), его необходимо сохранить и использовать для дальнейшей работы с пользователем. В данном примере ответа это “10364“

{ "id": 10364, "username": "tele_720", "first_name": "", "last_name": "", "provider_uid": "720", "parental_code": "0000", "parental_status": "notset", "phone": null, "email": null, "timezone": null, "device_limit": 5, "provider": { "id": 4, "name": "Telatel-PlanB", "proxy": null, "landing": { "logo": null, "url": "", "shortname": "Telatel", "login": { "title": "Поздравляем!", "description": "Услуги современного интерактивного телевидения доступны в сети Вашего провайдера! Уточните, пожалуйста, у своего провайдера логин и пароль для доступа к услуге от компании \"$platform_name$\"" }, "support": { "email": "", "phone": "", "url": "" } }, "auto_auth": null, "is_allow_additional_packets_without_base": false, "free_channels_count": 100, "store_sources": [], "language": null, "currency": { "ISO_CODE": "RUB", "UTF_NAME": "₽", "ASCII_NAME": "руб.", "FORMAT": "{amount} {symbol}" }, "phone_mask": null }, "is_provider_free": true, "is_active": true, "is_testuser": false, "is_self_deletion_allowed": false, "is_validated": false, "is_guest": false, "last_login": null, "date_joined": "2023-04-04T10:03:06.257865Z", "subscriptions": [], "parental_dialogue": {} }

Пользователь успешно создан, теперь можно подключить ему подписку.

В случае возникновения ошибки, в ответе будет содержаться описание ошибки

{ "detail": { "username": [ "Пользователь с таким именем уже существует." ] }, "error": { "message": "{'username': [ErrorDetail(string='Пользователь с таким именем уже существует.', code='invalid')]}" }, "status_code": 400, "error_code": "invalid" }

Получение списка доступных пакетов

Список доступных пакетов и их ID можно посмотреть в панели администратора или выполнив запрос к API

GET /v2/packets

curl -X 'GET' \ 'https://$platform_name$.platform24.tv/v2/packets?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \ -H 'accept: application/json'

В ответе вернётся структурный список содержащий все доступные для подключения пакеты.

[ { "id": 9, "name": "Телеателье Plan B", "row_slug": "", "short": "Библиотека Plan B для партнера", "description": "Библиотека Plan B для партнера", "old_price": "0.00", "price": "0.00", "base": true, "is_public": true, "agreement": "", "libraries": [ { "id": 23, "title": "Plan B", "description": "SignalTV", "library_type": "signaltv", "cover": { "light_bg": "http://media.24h.tv/background_images/40/26/4026c4464529468379b479eff6750abe.png", "dark_bg": "http://media.24h.tv/background_images/56/d3/56d3f7cd0696d143c7689567bb23dc5a.png", "color_bg": "http://media.24h.tv/background_images/62/21/6221aaeead0642af39c1ef46902ad8df.png", "bg": "http://media.24h.tv/background_images/8c/4f/8c4fa62226c40094093e344b95e17f09.png" }, "logo": null } ], "available": null, "include": null, "period": "0-1-0", "period_human": { "days": 0, "months": 1, "years": 0 }, "design": { "background_tv": null, "background_mobile": null, "small_background_tv": null, "small_background_mobile": null, "big_background_tv": null, "logo": null, "mini_logo": null, "corner_badge": null, "inline_badge": null, "special_features": null } } ]

Обработав ответ, вы можете понять ID пакета, который надо подключить созданному пользователю.

Подключение пакета пользователю

Зная ID созданного в Платформе пользователя и ID подключаемого пакета можно подключить пакет пользователю. Для этого используется метод

POST /v2/users/{user_id}/subscriptions

В качестве данных надо передать следующее:

  • ID пользователя в Платформе (10364)

  • ID подключаемого пакета

  • Дата и время начала действия подписки

  • Параметр автопродления подписки (renew)

curl -X 'POST' \ 'https://$platform_name$.platform24.tv/v2/users/10364/subscriptions?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'X-CSRFTOKEN: NYFDQ99YklE3PSI0niBM3DbjXrOJe5dxNgnV3F9yjTUBG1N9anEp9WdRnlaATIXm' \ -d '[{ "packet_id": 9, "start_at": "2023-04-04T13:49:12.903Z", "renew": true, "is_paused": false } ]'

В качестве ответа будет JSON структура, из которой нужно сохранить ID подписки и дату окончания, если она вам нужна.

[ { "id": "849505762352128683", "packet": { "id": 9, "name": "", "row_slug": "", "short": "Библиотека Plan B для партнера", "description": "", "old_price": "0.00", "price": null, "base": true, "is_public": true, "agreement": "", "libraries": [ { "id": 23, "title": "Plan B", "description": "SignalTV", "library_type": "signaltv", "cover": { "light_bg": "http://media.24h.tv/background_images/40/26/4026c4464529468379b479eff6750abe.png", "dark_bg": "http://media.24h.tv/background_images/56/d3/56d3f7cd0696d143c7689567bb23dc5a.png", "color_bg": "http://media.24h.tv/background_images/62/21/6221aaeead0642af39c1ef46902ad8df.png", "bg": "http://media.24h.tv/background_images/8c/4f/8c4fa62226c40094093e344b95e17f09.png" }, "logo": null } ], "available": null, "include": null, "period": "0-1-0", "period_human": { "days": 0, "months": 1, "years": 0 }, "design": { "background_tv": null, "background_mobile": null, "small_background_tv": null, "small_background_mobile": null, "big_background_tv": null, "logo": null, "mini_logo": null, "corner_badge": null, "inline_badge": null, "special_features": null } }, "start_at": "2023-04-04T13:49:12.903000Z", "end_at": "2023-05-04T13:49:11.903000Z", "renew": true, "is_paused": false, "pauses": [], "type": "subscribe" } ]

Проверка текущих подписок пользователя

Получить список текущих подключенных подписок пользователю можно с помощью метода

GET /v2/users/{user_id}/subscriptions

curl -X 'GET' \ 'https://$platform_name$.platform24.tv/v2/users/10364/subscriptions?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \ -H 'accept: application/json'

В качестве ответа будет JSON структура

[ { "id": "849505762352128683", "packet": { "id": 9, "name": "", "row_slug": "", "short": "Библиотека Plan B для партнера", "description": "", "old_price": "0.00", "price": null, "base": true, "is_public": true, "agreement": "", "libraries": [ { "id": 23, "title": "Plan B", "description": "SignalTV", "library_type": "signaltv", "cover": { "light_bg": "http://media.24h.tv/background_images/40/26/4026c4464529468379b479eff6750abe.png", "dark_bg": "http://media.24h.tv/background_images/56/d3/56d3f7cd0696d143c7689567bb23dc5a.png", "color_bg": "http://media.24h.tv/background_images/62/21/6221aaeead0642af39c1ef46902ad8df.png", "bg": "http://media.24h.tv/background_images/8c/4f/8c4fa62226c40094093e344b95e17f09.png" }, "logo": null } ], "available": null, "include": null, "period": "0-1-0", "period_human": { "days": 0, "months": 1, "years": 0 }, "design": { "background_tv": null, "background_mobile": null, "small_background_tv": null, "small_background_mobile": null, "big_background_tv": null, "logo": null, "mini_logo": null, "corner_badge": null, "inline_badge": null, "special_features": null } }, "start_at": "2023-04-04T13:49:12.903000Z", "end_at": "2023-05-04T13:49:11.903000Z", "renew": true, "is_paused": false, "pauses": [], "type": "subscribe" } ]

Отключение подписки пользователя

Для отключения подписки пользователю нужно использовать метод

DELETE /v2/users/{user_id}/subscriptions/{id}

curl -X 'DELETE' \ 'https://$platform_name$.platform24.tv/v2/users/10364/subscriptions/849505762352128683?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \ -H 'accept: */*'

В случае успеха будет ответ

{ "id": "849505762352128683", "packet": { "id": 9, "name": "", "row_slug": "", "short": "Библиотека Plan B для партнера", "description": "", "old_price": "0.00", "price": null, "base": true, "agreement": "", "libraries": [ { "id": 23, "title": "Plan B", "description": "SignalTV", "library_type": "signaltv", "cover": { "light_bg": "http://media.24h.tv/background_images/40/26/4026c4464529468379b479eff6750abe.png", "dark_bg": "http://media.24h.tv/background_images/56/d3/56d3f7cd0696d143c7689567bb23dc5a.png", "color_bg": "http://media.24h.tv/background_images/62/21/6221aaeead0642af39c1ef46902ad8df.png", "bg": "http://media.24h.tv/background_images/8c/4f/8c4fa62226c40094093e344b95e17f09.png" }, "logo": null } ], "available": null, "include": null, "period": "0-1-0", "period_human": { "days": 0, "months": 1, "years": 0 }, "design": { "background_tv": null, "background_mobile": null, "small_background_tv": null, "small_background_mobile": null, "big_background_tv": null, "logo": null, "mini_logo": null, "corner_badge": null, "inline_badge": null, "special_features": null } }, "start_at": "2023-04-04T13:49:12.903000Z", "end_at": "2023-04-07T15:26:57.217095Z", "renew": false, "is_paused": false, "pauses": [], "type": "subscribe" }

В результате этого запроса подписка закончится временем выполнения запроса.

В случае когда надо изменить срок действия подписки, например когда идёт отключение в запланированный день и время, то надо использовать метод

PATCH/v2/users/{user_id}/subscriptions/{id}

Работа с этим методом аналогична методу DELETE описанному выше.

Добавление устройства пользователя

Для того что бы пользователь смог получить ссылку на поток, необходимо зарегистрировать устройство пользователя. Необходимо, чтобы у пользователя был минимум одно зарегистрированное устройство. Для регистрации необязательно указывать реальные данные.

Для регистрации устройства необходимо использовать метод

POST /v2/devices

{ "user_id" : 10364, #Обязательный параметр "name": "Telatel_10364", #Обязательный параметр "device_type": "pc", #Обязательный параметр "vendor": "Telatel", #Обязательный параметр "application_type": "web", #Обязательный параметр "model": "SB-129", "version": "24", "serial": "232233", "os_name": "Windows", "os_version": "11" }

Поле device_type должно содержать одно из следующих значений: tv, stb, tablet, phone, pc.

В зависимости от конфигурации платформы, по device_type и application_type сервер может отдавать ссылки на получение плейлистов по HTTP или HTTPS.

Пример:

  1. HTTP
    "device_type": "phone"
    "application_type": "ios"

  2. HTTPS
    "device_type": "pc"
    "application_type": "web"

Добавление устройства можно осуществлять как с BackEnd, так и с устройства пользователя и подписывать пользовательским токеном, полученным при вызове метода /v2/auth/provider. Это позволит получить дополнительные данные по устройству и более полно заполнить свойства устройства. Создание устройства с пользовательского устройства позволяет снизить RPS нагрузку на BackEnd и не выработать лимиты по запросам.

В случае успешного выполнения запроса будет JSON из которого нужно будет сохранить для этого пользователя ID созданного устройства. Он содержится в теге ID (e67044b9-70a2-482d-b857-f80369c14187).

{ "id": "e67044b9-70a2-482d-b857-f80369c14187", "name": "Telatel_10364", "device_type": "pc", "vendor": "Telatel", "model": SB-219, "version": 24, "serial": 232233, "os_name": Windows, "os_version": 11, "application_type": web, "profile": profile_name, "store_source": null, "settings": null, "notification": null, "interfaces": [], "created_at": "2023-04-13T08:24:47.964052Z", "login_at": null, "user_id": 10364, "parental_settings": null }

 

Методы вызываемые c устройства пользователя

Авторизация по device_id

Теперь, на устройстве пользователя, надо получить пользовательский токен для созданного устройства с помощью метода.

POST /v2/auth/device

curl -X 'POST' \ 'https://$platform_name$.platform24.tv/v2/auth/device' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "device_id": "e67044b9-70a2-482d-b857-f80369c14187" }'

В случае успеха будет JSON ответ

{ "access_token": "37efadb21cf871cfee4d47fe2d0521552dc4be5f", "expired": null, "device": { "id": "42a757fe-9126-4809-8ac7-2989f8c555ce", "name": "SHIELD", "device_type": "stb", "vendor": "NVIDIA", "model": "SHIELD Android TV", "version": "3.348 (2022-12-24 19:37:48)", "serial": "NVIDIA_SHIELD Android TV_74e173f971f0ccc2_74e173f971f0ccc2_00:00:00:00:00:00", "os_name": "Android", "os_version": "30", "application_type": "android-tv", "profile": null, "store_source": null, "settings": { "adapter": null, "parentalControl": false, "referrer_url": "utm_source=google-play&utm_medium=organic", "sleepTimer": null, "startVersion": 3348, "streamAspect": { "accept": [ "original", "zoom", "wide", "letterbox" ], "adapter": null, "value": "original" }, "streamType": { "accept": [ "hls", "local_low", "local" ], "adapter": null, "value": "hls" }, "tvOnly": false, "unique_id": null }, "notification": { "notification_type": "android_stb", "token": "cWcaamu0TbCJqBTTA9EmCy:APA91bFBn1NN99ApJ7WwZ45mdH5lkZPK4N0USKfltLsCA8J7WEOvmuQy5A-XUP5D1p6iKMubOaksIHk9VU4xqLaYqioLFvjPobvXGKG3qzTqRuE-9DEOY_Kbu60YiSiRu4ww0JI6mlKI", "created_at": "2022-12-24T22:33:41.880885Z" }, "interfaces": [ { "name": "lo", "mac": "00:00:00:00:00:00" } ], "created_at": "2022-12-24T22:33:36.663327Z", "login_at": "2023-04-07T16:10:08.296208Z", "user_id": 43, "parental_settings": null }, "profile": null }

Из полученного ответа нужно только значение поля “access_token“. Это значение далее надо будет использовать для получения ссылки на контент запрашиваемый пользователем.

Запрос ссылки на стрим

Теперь когда все зарегистрировано, подключено, создано и т.п. можно запросить поток.

Запрос стрима нужно делать из клиентского приложения.

Для запроса потока надо знать library_id, content_id запрашиваемого контента и токен пользователя, для которого получаем поток.

library_id - неизменный в рамках всей библиотеки и сообщается партнёром
content_id - содержится в файле с выгрузкой метаданных. Доступ к файлу также предоставляется партнёром.

Для получение непосредственно ссылки на контент используется метод

GET /v2/libraries/{library_id}/contents/{id}/stream

curl -X 'GET' \ 'https://$platform_name$.platform24.tv/v2/libraries/23/contents/832404576750893135/stream?access_token=37efadb21cf871cfee4d47fe2d0521552dc4be5f' \ -H 'accept: application/json'

В полученном ответе в теге hls будет содержаться ссылка на запрошенный контент, которую надо отдать клиенту на воспроизведение.

{ "history": null, "type": "full", "from": 0, "to": 0, "mime_type": "application/vnd.apple.mpegurl", "hls": "http://195.191.208.9:8060/hls/jwt/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYXRoX21kNSI6IjhlNzQ3MDA2ODQ2YmQzNzQ0ZGNkYTc5NDgyMTIzNDliIiwidCI6IjM3ZWZhZGIyMWNmODcxY2ZlZTRkNDdmZTJkMDUyMTU1MmRjNGJlNWYiLCJ0cyI6MTY4MTM3NzI3MCwiaXQiOmZhbHNlfQ.UyWBryJ_FOvW3M_zdmd8MOuGVJD0P2zaLZOR2YzVBx4/vod/tracks/v1-v2-v3-a1/signaltv/db68a2a1266669a06fee290d5225b18d.mp4/clipFrom/0000/master.m3u8", "packshots": [], "stat": { "id": "4418d851-aab2-4fd4-a9d5-4888e7a484de" } }