Инструкция по работе с VoD контентом размещенном на Платформа24
Данная инструкция описывает основные и необходимые действия, которые необходимо произвести оператору партнёру для организации доступа своим пользователям для целей просмотра VoD контента.
Основные этапы
Получить у владельцев платформы технический доступ к панели администратора. В дальнейшем он будет использоваться и для доступа к описанию методов API. Также необходимо запросить ID библиотеки
Получить у владельцев платформы доступ к файлу с выгрузкой мета-данных контента для последующего импорта.
В панели администратора получить TOKEN оператора. Полученный TOKEN будет использоваться для подписания всех запросов к API при работе интеграции.
ВАЖНО: При повторном получении
Реализовать логику регистрации пользователя в Платформа24
Реализовать управление подписками пользователя в Платформа24 (Назначение/Отключение подписки)
Реализовать получение потока запрашиваемого контента для пользователя оператора
РЕГИСТРАЦИЯ ПОЛЬЗОВАТЕЛЯ
Для полноценного управления услугой/подпиской необходимо создать пользователя в платформе.
Позже созданному пользователю будут назначаться соответствующие подписки.
Общая документация по методу создания пользователя здесь: https://$platform_name$.platform24.tv/v2/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 запрос для создания пользователя
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“
Response code 200
{
"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": {}
}
Пользователь успешно создан, теперь можно подключить ему подписку.
В случае возникновения ошибки, в ответе будет содержаться описание ошибки
Response code 400
{
"detail": {
"username": [
"Пользователь с таким именем уже существует."
]
},
"error": {
"message": "{'username': [ErrorDetail(string='Пользователь с таким именем уже существует.', code='invalid')]}"
},
"status_code": 400,
"error_code": "invalid"
}
ПОЛУЧЕНИЕ СПИСКА ДОСТУПНЫХ ПАКЕТОВ
Список доступных пакетов и их ID можно посмотреть в панели администратора или выполнив запрос к API
POST /v2/packets
curl /v2/packets
curl -X 'GET' \
'https://$platform_name$.platform24.tv/v2/packets?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \
-H 'accept: application/json'
В ответе вернётся структурный список содержащий все доступные для подключения пакеты.
Response code 200
[
{
"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": true
}
]'
В качестве ответа будет JSON структура, из которой нужно сохранить ID подписки и дату окончания, если она вам нужна.
В случае успеха, будет ответ Response code 200
[
{
"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 запрос для удаления подписки
curl -X 'DELETE' \
'https://$platform_name$.platform24.tv/v2/users/10364/subscriptions/849505762352128683?token=bd21de6432fdc13f2d783ecf28eebdb46960e052' \
-H 'accept: */*' \
-H 'X-CSRFTOKEN: tUhy3Z7t5LMOVtVsOoIGvadOorFcht5RPZ3vjjntproxIJrW2wFs63fqc7zADuAL'
В случае успеха будет ответ
Успешный ответ
{
"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
Click here to expand...
{
"user_id" : 10364,
"name": "Telatel_10364",
"device_type": "pc",
"vendor": "Telatel"
}
Поле device_type должно содержать одно из следующих значений: tv, stb, tablet, phone, pc
В случае успешного выполнения запроса будет JSON из которого нужно будет сохранить для этого пользователя ID созданного устройства. Он содержится в теге ID (e67044b9-70a2-482d-b857-f80369c14187).
Click here to expand...
{
"id": "e67044b9-70a2-482d-b857-f80369c14187",
"name": "Telatel_10364",
"device_type": "pc",
"vendor": "Telatel",
"model": null,
"version": null,
"serial": null,
"os_name": null,
"os_version": null,
"application_type": null,
"profile": null,
"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
}
АВТОРИЗАЦИЯ ПО device_id
Теперь надо получить пользовательский токен для созданного пользовательского устройства с помощью метода
POST /v2/auth/device
Click here to expand...
curl -X 'POST' \
'https://$platform_name$.platform24.tv/v2/auth/device' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-CSRFTOKEN: B8FOLywf3J5DEqOhXijJfO1oTnDrZjzaXdrL1SMfnpHmrGkLbqgvQH30H3xPlk44' \
-d '{
"device_id": "e67044b9-70a2-482d-b857-f80369c14187"
}'
В случае успеха будет JSON ответ
Click here to expand...
{
"access_token": "bd999428c6760a0369b299e74d9f98899bc2ed4a",
"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 - содержится в файле с выгрузкой метаданных. Доступ к файлу также предоставляется партнёром.
ВНИМАНИЕ: Если JSON файл с мета-данными будет открываться в браузере, то из-за особенностей реализации java-script, ID используемые в файле могут отображаться не корректно.
Для получение непосредственно ссылки на контент надо использовать метод
GET/v2/libraries/{library_id}/contents/{id}/stream
Click here to expand...
curl -X 'GET' \
'https://$platform_name$.platform24.tv/v2/libraries/23/contents/832404576750893135/stream?access_token=37efadb21cf871cfee4d47fe2d0521552dc4be5f' \
-H 'accept: application/json'
В полученном ответе в теге hls будет содержаться ссылка на запрошенный контент, которую надо отдать клиенту на воспроизведение.
В полученном ответе в теге 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"
}
}