Настройка и подключение SDK для партнеров

Обновлено 3 октября 2024

Операционная система (ОС) Салют ТВ построена на базе ОС 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")))

Примеры формирования представлены в таблице:

Пример кода

Сформированное содержимое эвента

analytics.send("event_name", "text")

text

analytics.send("event_name", Analytics.params("key" to "value"))

{
    "key":"value"
}

analytics.send("event_name", Analytics.params("key" to listOf("value")))

{
   "key":[
      "value"
   ]
}

analytics.send("event_name", Analytics.params("key" to mapOf("child_key" to "child_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 - прямоугольные виджеты, основные poster_type - виджеты постеры, в категории фильмы square_small_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	Ссылка на видео ролик, который будет проигрываться на фоне

Настройка и подключение SDK для партнеров

Проверка совместимости функций и ОС﻿

Получение DeviceID﻿

Хранение ID устройства﻿

Получение партнерского токена﻿

Хранение партнерского токена при успешном получении﻿

Получение статуса прелогина﻿

Формирование аналитических данных﻿

Авторизация в сервисе﻿

Покупка подписки﻿

Отмена подписки﻿

Покупка контента﻿

Событие запуска контента﻿

Событие завершения просмотра контента﻿

События запуска приложения﻿

Проверка признака запуска приложения на устройстве Sber﻿

Метод передачи виджетов postPartnerWidgets﻿

Выходные параметры﻿

Проверка совместимости функций и ОС

Получение DeviceID

Хранение ID устройства

Получение партнерского токена

Хранение партнерского токена при успешном получении

Получение статуса прелогина

Формирование аналитических данных

Авторизация в сервисе

Покупка подписки

Отмена подписки

Покупка контента

Событие запуска контента

Событие завершения просмотра контента

События запуска приложения

Проверка признака запуска приложения на устройстве Sber

Метод передачи виджетов postPartnerWidgets

Выходные параметры