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

Инструкция по работе с 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 -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": {}
}

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

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

ПОЛУЧЕНИЕ СПИСКА ДОСТУПНЫХ ПАКЕТОВ

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

POST /v2/packets

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

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

ПОДКЛЮЧЕНИЕ ПАКЕТА ПОЛЬЗОВАТЕЛЮ

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

POST /v2/users/{user_id}/subscriptions

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

ID пользователя в Платформе (10364)
ID подключаемого пакета
Дата и время начала действия подписки
Параметр автопродления подписки (renew)

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

ПРОВЕРКА ТЕКУЩИХ ПОДПИСОК ПОЛЬЗОВАТЕЛЯ

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

GET /v2/users/{user_id}/subscriptions

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

ОТКЛЮЧЕНИЕ ПОДПИСКИ ПОЛЬЗОВАТЕЛЯ

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

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

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

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

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

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

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

ДОБАВЛЕНИЕ УСТРОЙСТВА ПОЛЬЗОВАТЕЛЯ

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

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

POST /v2/devices

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

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

АВТОРИЗАЦИЯ ПО device_id

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

POST /v2/auth/device

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

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

ЗАПРОС ССЫЛКИ НА СТРИМ

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

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

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

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

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

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

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