Настройка и подключение SDK для партнеров
Операционная система (ОС) Салют ТВ построена на базе ОС Android. SDK для интеграции с Салют ТВ предоставляется в виде библиотеки в формате AAR.
Добавление библиотеки в проект:
- скопируйте файл
partner_sdk.aar
в директорию проекта; - при использовании Gradle добавьте следующую зависимость в файле
build.gradle
.
dependencies {
implementation "ru.sberdevices.smartapp:sdk:1.2.0"
implementation files('../partner_sdk.aar')
}
После синхронизации в проекте будут доступны файлы библиотек.
Проверка совместимости функций и ОС
С версии 1.1.1 методы классов SDK отмечены аннотацией @SinceVersion
. Аннотация указывает версию aidl-сервиса, начиная с которой поддерживается метод. Такой подход позволяет избежать использования неактуальных методов, которые не поддерживаются в StarOS. Рассинхронизация в поддержке методов возникает из-за разницы релизных циклов SDK и StarOS.
Чтобы проверить версию сервиса, начиная с которой поддерживается метод, используйте метод getVersion()
.
Проверяйте совместимость методов при имплементации интерфейсов:
Analytics
;PublicDeviceInfoManager
;PartnerTokenApi
.
Получение DeviceID
Начиная с версии прошивки 1.83 имеется возможность использовать метод для получения открытого идентификатора DeviceID. Пример вызова представлен ниже:
private val deviceInfo = PublicDeviceInfoFactory.create(
context = context,
binderHelperFactory2 = BinderHelperFactory2Impl(),
coroutineDispatchers = CoroutineDispatchers
)
fun retrieveDeviceId() {
deviceInfo.registerDeviceInfoListener(object : PublicDeviceInfoListener {
override fun onPublicDeviceInfo(publicDeviceInfo: PublicDeviceInfo) {
publicDeviceInfo.deviceId
Log.d("retrieveDeviceId", "deviceId = ${publicDeviceInfo.deviceId}")
}
})
}
retrieveDeviceId()
Хранение ID устройства
{
publicDeviceInfo.deviceId
}
Для сохранения совместимостей необходимо вызывать метод, реализованный для конкретной прошивки.
В случае, если новый метод не возвращает идентификатор, необходимо использовать метод для предыдущей прошивки соответственно.
Оповещение о полном отказе от предыдущего метода будет направлено за полтора месяца до его обновления.
Получение партнерского токена
<manifest>
<uses-permission android:name="ru.sberdevices.permission.BIND_ACCOUNT_LINKING_SERVICE" />
</manifest>
Получение токена доступно исключительно для заранее сконфигурированных Application ID. Вызов данного метода вернет токен только для партнеров, для других приложений вернет ошибку
private val partnerToken = PartnerTokenFactory.create(
context = context,
binderHelperFactory2 = BinderHelperFactory2Impl(),
coroutineDispatchers = CoroutineDispatchers
)
fun retrievePartnerToken() {
val coroutineScope = CoroutineScope(CoroutineDispatchers.ui)
coroutineScope.launch {
val token =
partnerToken.getPartnerToken().getOrNull()?.token ?: "couldn't get partner token"
Log.d("retrievePartnerToken", "partnerToken = $partnerToken")
}
}
retrievePartnerToken()
Хранение партнерского токена при успешном получении
{
partnerToken.getPartnerToken().getOrNull()?.token ?: "couldn't get partner token"
}
Получение статуса прелогина
Для прошивки 1.88 реализован метод для получения статуса прелогина. Пример кода:
val partnerTokenImpl = PartnerTokenFactory.create(
context = this,
coroutineDispatchers = CoroutineDispatchers,
binderHelperFactory2 = BinderHelperFactory2Impl()
)
coroutineScope.launch {
val version = partnerTokenImpl.getVersion()
if (version != null && version >= 2) {
partnerTokenImpl.isPrelogin().fold(onSuccess = { isPrelogin ->
// Статус прелогина успешно получен.
}, onFailure = {
// Произошла ошибка при получении статуса прелогина.
})
} else {
// Текущая версия сервиса, которая не поддерживает получение статуса прелогина.
}
}
Формирование аналитических данных
private val analytics = AnalyticsFactory.create(context)
// отправка текста в качестве содержимого эвента
analytics.send("event_name", "text")
// отправка JSON, {"key": "value"}
analytics.send("event_name", Analytics.params("key" to "value"))
// отправка JSON, {"key": ["value"]}
analytics.send("event_name", Analytics.params("key" to listOf("value")))
// отправка JSON, {"key": {"child_key": "child_value"}}
analytics.send("event_name", Analytics.params("key" to mapOf("child_key" to "child_value")))
Примеры формирования представлены в таблице:
{
"key":"value"
}
{
"key":[
"value"
]
}
{
"key":{
"child_key":"child_value"
}
}
Партнерские кинотеатры, при возникновении указанных в документации событий, должны сформировать данные в формате JSON в соответствии с нижеуказанными спецификациями и передать их методу analytics.send()
.
Авторизация в сервисе
Название отправляемого события: PartnerAuthorization
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
has_subscription | bool | наличие подписки на момент авторизации |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
subscription | array[JSONobject] | список подписок пользователя |
Формат подписки
Название | Тип | Описание |
name | string | наименование подписки |
amount | float | стоимость подписки в рублях |
period | int | период обновления |
source | string | оплата - INTERNAL или EXTERNAL |
end_date | timestamp | дата окончания подписки |
start_date | timestamp | дата начала подписки |
period_type | string | тип подписки - Promo или Standard |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"has_subscription":true,
"account_created_at":1727220183899,
"subscription":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183899,
"start_date":1728948183899,
"period_type":"standard"
}
]
}
Покупка подписки
Название отправляемого события: PartnerSubscriptionPurchase
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
price | float | стоимость подписки для пользователя |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
name | string | название подписки |
period | int | период обновления |
period_type | string | тип покупки - подписка/триал |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
subscription | array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"name":"Premium Advanced Promo",
"price":99,
"period":15,
"period_type":"promo",
"subscription":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183901,
"start_date":1728948183901,
"period_type":"standard"
}
],
"has_subscription":true,
"account_created_at":1727220183901,
"is_authorized":true
}
Отмена подписки
Название отправляемого события: PartnerSubscriptionCancel
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
price | float | стоимость подписки для пользователя |
name | string | название подписки |
period | int | период обновления |
period_type | string | тип покупки - подписка/триал |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
subscription: array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"name":"Premium Advanced Promo",
"price":99,
"period":15,
"period_type":"promo",
"subscription":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183902,
"start_date":1728948183902,
"period_type":"standard"
}
],
"account_created_at":1727220183902,
"is_authorized":true}
Покупка контента
Название отправляемого события: PartnerContentPurchase
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
price | float | стоимость подписки для пользователя |
name | string | название подписки |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
subscription | array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"name":"Название купленного контента",
"price":999,
"content_id":"84fbfb4f-9f38-4337-9fb1-f8100344283d",
"subscription":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183906,
"start_date":1728948183906,
"period_type":"standard"
}
],
"has_subscription":true,
"account_created_at":1727220183906,
"is_authorized":true}
Событие запуска контента
Название отправляемого события: PartnerContentStart
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
content_id | string | id контента |
content_name | string | название контента |
tags | array[str] | теги (если применимо) |
trigger | string | кто завершил просмотр - user или auto |
subscription | array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"has_subscription":true,
"content_id":"84fbfb4f-9f38-4337-9fb1-f8100344283d",
"content_name":"Название купленного контента",
"content_tags":["мелодрамы","популярное"],
"subscriptions":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183910
"start_date":1728948183910,
"period_type":"standard"
}
],
"trigger":"auto",
"account_created_at":1727220183910,
"is_authorized":true}
Событие завершения просмотра контента
Название отправляемого события: PartnerContentFinished
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
content_id | string | id контента |
content_name | string | название контента |
tags | array[str] | теги (если применимо) |
duration | int | общая длительность контента, секунды |
watched | int | на какой секунде закончен просмотр |
trigger | string | кто завершил просмотр - user или auto |
subscription | array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"has_subscription":true,
"content_id":"84fbfb4f-9f38-4337-9fb1-f8100344283d",
"content_name":"Название купленного контента",
"content_tags":["мелодрамы","популярное"],
"duration":7200,
"watched":1800,
"subscriptions":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731540183911,
"start_date":1728948183911,
"period_type":"standard"
}
],
"trigger":"auto",
"account_created_at":1727220183911,
"is_authorized":true}
События запуска приложения
Название отправляемого события: PartnerAppStart
Параметр | Тип данных | Описание |
---|---|---|
uid | string | ID пользователя в сервисе |
is_authorized | bool | авторизован ли пользователь |
has_subscription | bool | была ли у пользователя подписка на момент авторизации |
package_name | string | название приложения |
account_created_at | int | дата создания аккаунта (для авторизованных пользователей, в секундах UNIXtime) |
subscription | array[JSONobject] | массив JSON-ов с атрибутами |
Формат подписки
Название | Тип | Описание |
start_date | timestamp | дата начала подписки |
end_date | timestamp | дата окончания подписки |
amount | float | стоимость подписки в рублях |
name | string | наименование подписки |
source | string | оплата - INTERNAL или EXTERNAL |
period_type | string | тип подписки - Promo или Standard |
period | int | период обновления |
{
"uid":"7af8d411-e6a9-4009-8615-cbeace4f0169",
"has_subscription":true,
"subscriptions":[
{
"name":"Premium",
"amount":299,
"period":30,
"source":"external",
"end_date":1731541522507,
"start_date":1728949522507,
"period_type":"standard"
}
],
"account_created_at":1727221522507,
"is_authorized":true}
Проверка признака запуска приложения на устройстве Sber
import ru.sberdevices.services.published.environment.info.EnvironmentInfoHelper
if (EnvironmentInfoHelper.isSberDevice(context)) {
// Устройство выпущено Sber
} else {
// Устройство не выпущено Sber
}
Метод передачи виджетов 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 |
title | Главный текст виджета | Мистика |
subtitle | Дополнительный текст виджета | "Фильмы" |
deeplink | Диплинк для перехода при нажатии | 24tv://ag.tv.a24h/live |
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 | Ссылка на видео ролик, который будет проигрываться на фоне |