Методы PartnerSDK

Обновлено 8 апреля 2025

Ниже описаны методы SDK для подключения внешнего контента к интерфейсу ТВ в разделе лончера. Это позволит обновлять информацию в режиме реального времени.

Передача виджетов

Для передачи виджетов исползуйте метод postPartnerWidgets(). С его помощью партнерские приложения могут публиковать виджеты в ТВ-вертикали (раздел лончера) после того, как пользователь выбрал их приоритетными провайдерами. Для реализации этой опции примените класс ExternalWidgetManager из PartnerSDK. Заранее запросите и согласуйте выдачу ID выделенной галереи (galleryId в примере ниже).

Пример кода:

val manager =  ExternalWidgetsManagerFactory.create(context = this, coroutineDispatchers = CoroutineDispatchers)
val result = manager.postPartnerWidgets(
    galleryId = galleryId,
    listOf(
        ExternalWidget(
            id = widgetId,
            type = ExternalWidgetType.WIDE_MEDIUM,
            deeplink = deeplink,
            title = "Тестовый виджет PartnerSDK, заголовок",
            subtitle = "Тестовый виджет PartnerSDK, подзаголовок",
            imageModelUrl = "https://static.okko.tv/images/v2/14072006" +
                "?width=442&scale=2&quality=80&mediaType=webp",
            backdropImageModelUrl = "https://static.okko.tv/images/v2/13793163?width=1966" +
                "&scale=2&quality=80&mediaType=webp",
        )
    )
)

if (result) {
// Виджет успешно добавлен
} else {
// Произошла ошибка
}

Пример передачи

Параметр	Описание	Пример
type	Тип виджета wide_medium_type — прямоугольные виджеты, основные poster_type — виджеты-постеры, в категории фильмы square_small_type — маленькие квадратные, например, в категории игры	wide_medium_type
title	Главный текст виджета	Мистика
subtitle	Дополнительный текст виджета	«Фильмы»
deeplink	Диплинк для перехода при нажатии	24tv://ag.tv.a24h/live
id	Обязательное наличие в каждом приложении: префикс названия приложения и префикс ID галереи	"titanik_best_films_week_24TV"
imageModelUrl	Картинка виджета	https://static.okko.tv/images/v2/14072006?width=442&scale=2&quality=80&mediaType=webp
backdropImageModelUrl	Картинка на фон	https://static.okko.tv/images/v2/13793163?width=1966&scale=2&quality=80&mediaType=webp
backdropLogoImageModelUrl	Логотип на фоне	https://static.okko.tv/images/v2/13039516?width=1568&scale=2&quality=80&mediaType=webp&trimBorder=true
backdropLogoText	Текст, если не будет логотипа в виде картинки
backdropTitle	Заголовок и описание на фоне	«2020 — Приключения — 2 ч 16 мин — Rus — 16+»
backdropDescriptionText
backdropPrerollUrl	Ссылка на видеоролик, который будет проигрываться на фоне

Передача персональных галерей

Для синхронизации содержимого персональной галереи пользователя вашего приложения с PartnerSDK используйте метод postPartnerCards(). Он позволяет передать данные о контенте, который пользователь просматривает, добавляет в избранное или покупает в вашем приложении.

Используйте метод, когда пользователь:

изменяет персональную галерею:
- запускает просмотр фильма, сериала, ТВ-канала или пользовательского контента (UGC);
- добавляет или удаляет контент из избранного;
авторизуется в приложении и нужно передать актуальные данные о его галереях;
деавторизуется (выходит из системы) и нужно передать пустые галереи (только id_gallery без элементов).

Для использования метода подключите библиотеку androidx.security:security-crypto-ktx:1.1.0-alpha06. Она нужна для шифрования токена, полученного от прошивки.

Описание входных параметров

Метод принимает список карточек (объектов класса Card()), каждая из которых содержит данные о контенте в галерее пользователя.

Сигнатура
Описание

data class Card(
    val galleryId: String,
    val contentId: String,
    val contentType: String? = null,
    val title: String? = null,
    val deepLink: String? = null,
    val imageUrl: String? = null,
    val backdropImageUrl: String? = null,
    val labels: List<String>? = null,
    val timeMark: Long? = null,
    val duration: Long? = null,
    val ageLimit: Int? = null,
    val dataChange: Long? = null,
)

galleryId

string

required

Идентификатор галереи, в которую должна быть добавлена карточка.

Примеры значений:

continue_watching — продолжить просмотр;
favorites — избранное;
continue_watching_tv — продолжить просмотр на ТВ;
favorites_tv — избранное на ТВ;
recommendations — рекомендации;
viewing_history — история просмотра;
purchases — покупки (необязательно).

contentId

string

required

Идентификатор контента, который соответствует значению contentId из SberJson.

contentType

string

required

Тип контента (например, MOVIE, SERIES, TVCHANNEL, TVSHOW, UGC).

title

string

Заголовок карточки.

Параметр является обязательным для контента с типом TVCHANNEL, TVSHOW и UGC.

deepLink

string

Ссылка для перехода при нажатии на карточку.

Параметр является обязательным для контента с типом TVCHANNEL, TVSHOW и UGC.

imageUrl

string

URL изображения карточки.

Параметр является обязательным для контента с типом TVCHANNEL, TVSHOW и UGC.

backdropImageUrl

string

Веб-адрес фонового изображения.

labels

string[]

Список лейблов, отображаемых на фоне карточки.

timeMark

Long

Время в секундах, которое пользователь уже посмотрел контент.

Параметр является обязательным для галереи «продолжить просмотр» (continue_watching) и для контента с типом MOVIE.

duration

Long

Общая продолжительность контента в секундах.

Параметр является обязательным для галереи «продолжить просмотр» (continue_watching) и для контента с типом MOVIE.

ageLimit

integer

Возрастное ограничение для контента. Например, 18 для контента 18+.

dataChange

Long

Время последнего изменения (добавления в избранное, просмотра, покупки) в формате unix timestamp.

Параметр является обязательным для галерей continue_watching, favorites, continue_watching_tv и favorites_tv.

Описание выходных параметров

Метод возвращает экземпляр PartnerCardsResponse, который содержит один из результатов:

Success — метод выполнен успешно.
Error — ошибка выполнения метода с описанием, которое можно использовать для диагностики.
InternalLibraryError — внутренняя ошибка библиотеки с описанием проблемы.

Пример вызова метода postPartnerCards

Пример демонстрирует использование менеджера PartnerCardsManager и обработку результатов выполнения метода postPartnerCards():

val partnerCardsManager = PartnerCardsManagerFactory.create(
    context = this@MainActivity,
    coroutineDispatchers = CoroutineDispatchers
)
 
val response = partnerCardsManager.postPartnerCards(
    context = this@MainActivity,
    cards = listOf(
        Card(
            galleryId = "continue_watching",
            contentId = "99ba738c-dcd4-4262-8e57-67d94e5ace89",
            contentType = "MOVIE",
            title = "Серебряные коньки",
            deepLink = "24tv://ag.tv.a24h/live",
            imageUrl = "https://static.okko.tv/images/v2/14072006?width=442&scale=2&quality=80&mediaType=webp",
            backdropImageUrl = "https://static.okko.tv/images/v2/13793163?width=1966&scale=2&quality=80&mediaType=webp",
            labels = listOf("Сергей Орлов", "3,5 млн просмотров", "5 дней назад"),
            timeMark = 891,
            duration = 1143,
            ageLimit = 18,
            dataChange = System.currentTimeMillis() / 1000
        )
    )
)
 
val resultDescription = when (response) {
    is PartnerCardsResponse.Error -> {
        "Ошибка: ${response.message}"
    }
    is PartnerCardsResponse.InternalLibraryError -> {
        "Внутренняя ошибка библиотеки: ${response.description}"
    }
    PartnerCardsResponse.Success -> {
        "Успешная передача данных"
    }
}

Передача виджетов﻿

Пример передачи﻿

Передача персональных галерей﻿

Описание входных параметров﻿

Описание выходных параметров﻿

Пример вызова метода postPartnerCards﻿

Передача виджетов

Пример передачи

Передача персональных галерей

Описание входных параметров

Описание выходных параметров

Пример вызова метода postPartnerCards