На главном экране Android TV рекомендованный контент представлен в виде таблицы каналов и программ. Каждая строка соответствует одному каналу. Канал содержит карточки для каждой доступной на нем программы.
В этом документе показано, как добавлять каналы и программы на главный экран, обновлять контент, обрабатывать действия пользователей и обеспечивать наилучшие условия для пользователей. Если вы хотите узнать больше об API, попробуйте практическую работу по главному экрану и посмотрите семинар по Android TV на I/O 2017.
Интерфейс главного экрана
Приложения могут создавать новые каналы, добавлять, удалять и обновлять программы в канале, а также управлять порядком программ в канале. Например, приложение может создать канал "Что нового" и показывать карточки для новых программ.
Приложения не могут управлять порядком, в котором каналы появляются на главном экране. Когда приложение создает новый канал, он добавляется в конец списка на главном экране. Пользователь может менять порядок каналов, а также скрывать и показывать их.
Канал "Смотреть дальше"
Канал "Смотреть дальше" – это вторая строка на главном экране, которая находится под строкой приложений. Этот канал создается и поддерживается системой. Ваше приложение может добавлять программы в канал "Смотреть дальше". Подробнее о том, как добавлять программы в канал "Смотреть дальше"…
Каналы приложений
Все каналы, создаваемые приложением, проходят следующий жизненный цикл:
- Пользователь находит канал в вашем приложении и запрашивает его добавление на главный экран.
- Приложение создает канал и добавляет его в
TvProvider(на этом этапе канал не виден). - Приложение запрашивает у системы показ канала.
- Система просит пользователя одобрить новый канал.
- Новый канал появится в последней строке главного экрана.
канал по умолчанию;
Приложение может предлагать пользователю любое количество каналов для добавления на главный экран. Обычно пользователю нужно выбрать и одобрить каждый канал, прежде чем он появится на главном экране. В каждом приложении можно создать один канал по умолчанию. Канал по умолчанию автоматически появляется на главном экране, и пользователю не нужно запрашивать его.
Требования
На главном экране Android TV используются API TvProvider Android для управления каналами и программами, которые создает ваше приложение. Чтобы получить доступ к данным поставщика, добавьте в манифест приложения следующее разрешение:
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
Библиотека поддержки TvProvider упрощает использование поставщика. Добавьте его в зависимости в файле build.gradle:
Яркий
implementation 'androidx.tvprovider:tvprovider:1.0.0'
Kotlin
implementation("androidx.tvprovider:tvprovider:1.0.0")
Чтобы работать с каналами и программами, добавьте в код следующие импорты из библиотеки поддержки:
import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram
Каналы
Первый канал, созданный приложением, становится каналом по умолчанию. Канал по умолчанию автоматически появляется на главном экране. Все остальные каналы, которые вы создаете, должны быть выбраны и приняты пользователем, прежде чем они появятся на главном экране.
Как создать канал
Приложение должно запрашивать у системы показ новых каналов, только когда оно работает в активном режиме. Это предотвратит появление диалогового окна с запросом на добавление канала, когда пользователь работает с другим приложением. Если вы попытаетесь добавить канал в фоновом режиме, метод onActivityResult() вернет код статуса RESULT_CANCELED.
Чтобы создать канал, выполните следующие действия:
Создайте конструктор каналов и задайте его атрибуты. Обратите внимание, что тип канала должен быть
TYPE_PREVIEW. При необходимости добавьте другие атрибуты.val builder = Channel.Builder() // Every channel you create must have the type `TYPE_PREVIEW`. builder.setType(TvContractCompat.Channels.TYPE_PREVIEW) .setDisplayName("Channel Name") .setAppLinkIntentUri(uri)
Вставьте канал в поставщика:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
Чтобы добавлять программы на канал, вам нужно сохранить идентификатор канала. Извлеките идентификатор канала из возвращенного URI:
var channelId = ContentUris.parseId(channelUri)
Добавьте логотип канала. Используйте
UriилиBitmap. Значок логотипа должен быть непрозрачным и иметь размер 80 x 80 dp. Оно показывается в круглой маске:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
Создайте канал по умолчанию (необязательно). При создании первого канала в приложении вы можете сделать его каналом по умолчанию, чтобы он сразу появлялся на главном экране без каких-либо действий со стороны пользователя. Любые другие созданные вами каналы не будут видны, пока пользователь явно не выберет их.
TvContractCompat.requestChannelBrowsable(context, channelId)
Сделайте так, чтобы канал по умолчанию появлялся до открытия приложения. Для этого добавьте
BroadcastReceiver, который будет отслеживать действиеandroid.media.tv.action.INITIALIZE_PROGRAMS, отправляемое главным экраном после установки приложения.<receiver android:name=".RunOnInstallReceiver" android:exported="true"> <intent-filter> <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </receiver>При установке приложения из неизвестного источника во время разработки вы можете протестировать этот шаг, активировав намерение через adb, где your.package.name/.YourReceiverName – это
BroadcastReceiverвашего приложения:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameВ редких случаях приложение может получить широковещательное сообщение в момент запуска пользователем. Убедитесь, что ваш код не пытается добавить канал по умолчанию более одного раза.
Обновление канала
Обновление каналов выполняется почти так же, как и их создание.
Используйте другой файл Channel.Builder, чтобы задать атрибуты, которые нужно изменить.
Обновите канал с помощью ContentResolver. Используйте идентификатор канала, который вы сохранили, когда канал был добавлен:
context.contentResolver.update( TvContractCompat.buildChannelUri(channelId), builder.build().toContentValues(), null, null )
Чтобы обновить логотип канала, используйте storeChannelLogo().
удалять канал;
context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)
Программы
Программы – это отдельные карточки контента, которые показываются на канале. Вы можете публиковать программы как в пользовательских каналах приложения, так и в системном канале "Смотреть дальше".
Как добавить программы в канал приложения
Создайте объект PreviewProgram.Builder и задайте его атрибуты:
val builder = PreviewProgram.Builder() builder.setChannelId(channelId) .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP) .setTitle("Title") .setDescription("Program description") .setPosterArtUri(uri) .setIntentUri(uri) .setInternalProviderId(appProgramId)
Добавьте дополнительные атрибуты в зависимости от типа программы. (Чтобы посмотреть атрибуты, доступные для каждого типа программы, ознакомьтесь с таблицами ниже.)
Вставьте программу в поставщика:
var programUri = context.contentResolver.insert( TvContractCompat.PreviewPrograms.CONTENT_URI, builder.build().toContentValues() )
Получите идентификатор программы, чтобы использовать его в дальнейшем:
val programId = ContentUris.parseId(programUri)
Добавление программ на канал "Смотреть дальше"
Чтобы добавить программы в канал "Смотреть дальше", ознакомьтесь с этой статьей.
Как обновить программу
Вы можете изменить информацию о программе. Например, вы можете изменить цену проката фильма или обновить индикатор выполнения, показывающий, какую часть программы пользователь уже посмотрел.
Используйте PreviewProgram.Builder, чтобы задать атрибуты, которые нужно изменить, а затем вызовите getContentResolver().update, чтобы обновить программу. Укажите идентификатор программы, который вы сохранили при ее добавлении:
context.contentResolver.update( TvContractCompat.buildPreviewProgramUri(programId), builder.build().toContentValues(), null, null )
Как удалить программу
context.contentResolver .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)
Обработка действий пользователя
Приложение может помогать пользователям находить контент, предоставляя интерфейс для просмотра и добавления каналов. Приложение также должно обрабатывать взаимодействия с каналами после их появления на главном экране.
Поиск и добавление каналов
В приложении можно добавить элемент интерфейса, позволяющий пользователю выбрать и добавить каналы (например, кнопку с предложением добавить канал).
После того как пользователь запросит определенный канал, выполните этот код, чтобы получить разрешение пользователя на добавление канала в интерфейс главного экрана:
val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
// handle error
}
Появится диалоговое окно с запросом на одобрение канала. Обработайте результат запроса в методе onActivityResult своего объекта activity (Activity.RESULT_CANCELED или Activity.RESULT_OK).
События на главном экране Android TV
Когда пользователь взаимодействует с программами и каналами, опубликованными приложением, главный экран отправляет приложению намерения:
- Когда пользователь нажимает на логотип канала, главный экран отправляет в приложение значение
Uri, сохраненное в атрибуте APP_LINK_INTENT_URI канала. Приложение должно просто запустить свой основной интерфейс или представление, связанное с выбранным каналом. - Когда пользователь выбирает программу, главный экран отправляет в приложение значение
Uri, сохраненное в атрибуте INTENT_URI программы. Приложение должно воспроизвести выбранный контент. - Пользователь может указать, что его больше не интересует программа и он хочет удалить ее с главного экрана. Система удаляет программу из интерфейса и отправляет приложению, которому принадлежит программа, намерение (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED или android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) с идентификатором программы. Приложение должно удалить программу из поставщика и НЕ добавлять ее повторно.
Убедитесь, что вы создали фильтры интентов для всех Uris, которые главный экран отправляет для взаимодействия с пользователем. Например:
<receiver
android:name=".WatchNextProgramRemoved"
android:enabled="true"
android:exported="true">
<intent-filter>
<action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
</intent-filter>
</receiver>
Дополнительные сведения
- Многие ТВ-приложения требуют входа в аккаунт. В этом случае
BroadcastReceiver, который ожидаетandroid.media.tv.action.INITIALIZE_PROGRAMS, должен предлагать контент канала для неаутентифицированных пользователей. Например, в приложении можно сначала показывать лучший или популярный контент. После входа в аккаунт пользователю может показываться персонализированный контент. Это отличная возможность для приложений продавать более дорогостоящие товары или услуги пользователям до того, как они войдут в систему. - Если приложение неактивно и вам нужно обновить канал или программу, используйте
JobScheduler, чтобы запланировать работу (см.JobSchedulerиJobService). - Система может отозвать разрешения поставщика, если приложение работает некорректно (например, постоянно отправляет поставщику спам). Обязательно оберните код, который обращается к поставщику, в блоки try-catch, чтобы обрабатывать исключения безопасности.
- Прежде чем обновлять программы и каналы, запросите у поставщика данные, которые нужно обновить и согласовать. Например, не нужно обновлять программу, которую пользователь хочет удалить из интерфейса. Используйте фоновое задание, которое вставляет или обновляет данные в поставщике после запроса существующих данных, а затем запрашивает одобрение для ваших каналов. Вы можете запускать это задание при запуске приложения и каждый раз, когда приложению нужно обновить данные.
context.contentResolver .query( TvContractCompat.buildChannelUri(channelId), null, null, null, null ).use({ cursor -> if (cursor != null && cursor.moveToNext()) { val channel = Channel.fromCursor(cursor) if (channel.isBrowsable()) { // update channel's programs. } } })
- Используйте уникальные URI для всех изображений (логотипов, значков, изображений контента). При обновлении изображения обязательно используйте другой URI. Все изображения кешируются. Если вы не измените URI при изменении изображения, будет по-прежнему показываться старое изображение.
- Помните, что операторы WHERE не разрешены, и вызовы поставщиков с операторами WHERE вызовут исключение безопасности.
Атрибуты
В этом разделе атрибуты каналов и программ описаны отдельно.
Атрибуты канала
Для каждого канала необходимо указать следующие атрибуты:
| Атрибут | Примечания |
|---|---|
| ПЕЧАТ | Установлено значение TYPE_PREVIEW. |
| DISPLAY_NAME | имеет значение, равное названию канала. |
| APP_LINK_INTENT_URI | Когда пользователь выбирает логотип канала, система отправляет намерение запустить действие, которое показывает контент, связанный с каналом. Укажите в этом атрибуте URI, который используется в фильтре интентов для этого объекта activity. |
Кроме того, в канале есть шесть полей, зарезервированных для внутреннего использования приложения. Эти поля можно использовать для хранения ключей или других значений, которые могут помочь приложению сопоставить канал с его внутренней структурой данных:
- INTERNAL_PROVIDER_ID
- INTERNAL_PROVIDER_DATA
- INTERNAL_PROVIDER_FLAG1
- INTERNAL_PROVIDER_FLAG2
- INTERNAL_PROVIDER_FLAG3
- INTERNAL_PROVIDER_FLAG4
Атрибуты программы
Подробную информацию об атрибутах для каждого типа программ можно найти на следующих страницах:
- Атрибуты видеопрограмм
- Атрибуты аудиопрограмм
- Атрибуты программы Game
- Атрибуты рекомендованных видео
Пример кода
Чтобы узнать больше о создании приложений, взаимодействующих с главным экраном, и добавлении каналов и программ на главный экран Android TV, ознакомьтесь с практической работой.