La pantalla principal de Android TV proporciona una IU que muestra el contenido recomendado como una tabla de canales y programas. Cada fila corresponde a un canal. Un canal contiene tarjetas para cada programa disponible en ese canal:
En este documento, se muestra cómo agregar canales y programas a la pantalla principal, actualizar el contenido, controlar las acciones de los usuarios y brindarles la mejor experiencia. (Si quieres profundizar en la API, prueba el codelab de la pantalla principal y mira la sesión de Android TV de I/O 2017).
IU de la pantalla principal
Las apps pueden crear canales nuevos, agregar, quitar y actualizar los programas de un canal, y controlar el orden de los programas en un canal. Por ejemplo, una app puede crear un canal llamado "Novedades" y mostrar tarjetas para los programas disponibles recientemente.
Las apps no pueden controlar el orden en que se muestran los canales en la pantalla principal. Cuando tu app crea un canal nuevo, la pantalla principal lo agrega al final de la lista de canales. El usuario puede reordenar, ocultar y mostrar los canales.
Canal "Ver a continuación"
El canal Ver a continuación es la segunda fila que aparece en la pantalla principal, después de la fila de apps. El sistema crea y mantiene este canal. Tu app puede agregar programas al canal Mirar a continuación. Para obtener más información, consulta Cómo agregar programas al canal Mirar a continuación.
Canales de apps
Todos los canales que crea tu app siguen este ciclo de vida:
- El usuario descubre un canal en tu app y solicita agregarlo a la pantalla principal.
- La app crea el canal y lo agrega a
TvProvider(en este punto, el canal no es visible). - La app le solicita al sistema que muestre el canal.
- El sistema le solicita al usuario que apruebe el nuevo canal.
- El nuevo canal se muestra en la última fila de la pantalla principal.
Canal predeterminado
Tu app puede ofrecer cualquier cantidad de canales para que el usuario los agregue a la pantalla principal. Por lo general, el usuario debe seleccionar y aprobar cada canal antes de que aparezca en la pantalla principal. Cada app tiene la opción de crear un canal predeterminado. El canal predeterminado es especial porque aparece automáticamente en la pantalla principal; el usuario no tiene que solicitarlo de forma explícita.
Requisitos previos
La pantalla principal de Android TV usa las APIs de TvProvider de Android para administrar los canales y programas que crea tu app. Para acceder a los datos del proveedor, agrega
el siguiente permiso al manifiesto de tu app:
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
La biblioteca de compatibilidad TvProvider facilita el uso del proveedor. Agrégala a las dependencias en tu archivo build.gradle:
Groovy
implementation 'androidx.tvprovider:tvprovider:1.0.0'
Kotlin
implementation("androidx.tvprovider:tvprovider:1.0.0")
Para trabajar con canales y programas, asegúrate de incluir estas importaciones de la biblioteca de compatibilidad en tu programa:
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
Canales
El primer canal que crea tu app se convierte en el canal predeterminado. El canal predeterminado aparece automáticamente en la pantalla principal. El usuario debe seleccionar y aceptar todos los demás canales que crees antes de que puedan aparecer en la pantalla principal.
Cómo crear un canal
Tu app debe pedirle al sistema que muestre los canales recién agregados solo cuando se ejecute en primer plano. Esto evita que tu app muestre un diálogo en el que se solicite aprobación para agregar tu canal mientras el usuario ejecuta otra app. Si intentas agregar un canal mientras se ejecuta en segundo plano, el método onActivityResult() de la actividad mostrará el código de estado RESULT_CANCELED.
Para crear un canal, sigue estos pasos:
Diseña un compilador de canales y establece sus atributos. Ten en cuenta que el tipo de canal debe ser
TYPE_PREVIEW. Agrega más atributos según sea necesario.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)
Inserta el canal en el proveedor:
var channelUri = context.contentResolver.insert( TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues() )
Debes guardar el ID del canal para agregarle programas más adelante. Extrae el ID de canal de la URI que se muestra:
var channelId = ContentUris.parseId(channelUri)
Debes agregar un logotipo para el canal. Usa un elemento
UrioBitmap. El ícono del logotipo debe ser de 80 dp x 80 dp y debe ser opaco. Se muestra debajo de una máscara circular:
// Choose one or the other. storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL. storeChannelLogo(context, channelId, logo)
Crea el canal predeterminado (opcional): Cuando tu app cree su primer canal, puedes convertirlo en el canal predeterminado para que aparezca en la pantalla principal de inmediato sin que el usuario deba realizar ninguna acción. Los demás canales que crees no serán visibles hasta que el usuario los seleccione de forma explícita.
TvContractCompat.requestChannelBrowsable(context, channelId)
Puedes hacer que el canal predeterminado se muestre antes de que el usuario abra la app. Para lograr este comportamiento, agrega un
BroadcastReceiverque escuche la acciónandroid.media.tv.action.INITIALIZE_PROGRAMS, que la pantalla principal envía después de que se instala la app:<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>Cuando realices el sideloading de tu app durante el desarrollo, puedes probar este paso activando el intent a través de adb, donde your.package.name/.YourReceiverName es el
BroadcastReceiverde tu app:adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \ your.package.name/.YourReceiverNameEn casos excepcionales, es posible que tu app reciba la transmisión al mismo tiempo que el usuario la inicia. Asegúrate de que tu código no intente agregar el canal predeterminado más de una vez.
Cómo actualizar un canal
La actualización de canales es muy similar a la creación.
Usa otro Channel.Builder para configurar los atributos que deben cambiarse.
Usa ContentResolver para actualizar el canal. Usa el ID del canal que guardaste
cuando se agregó originalmente:
context.contentResolver.update( TvContractCompat.buildChannelUri(channelId), builder.build().toContentValues(), null, null )
Para actualizar el logotipo de un canal, usa storeChannelLogo().
Cómo borrar un canal
context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)
Programas
Los programas son las tarjetas de contenido individuales que se muestran en un canal. Puedes publicar programas en los canales personalizados de tu app y en el canal Mirar a continuación administrado por el sistema.
Cómo agregar programas a un canal de app
Crea un PreviewProgram.Builder y establece sus atributos:
val builder = PreviewProgram.Builder() builder.setChannelId(channelId) .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP) .setTitle("Title") .setDescription("Program description") .setPosterArtUri(uri) .setIntentUri(uri) .setInternalProviderId(appProgramId)
Agrega más atributos según el tipo de programa. (Para ver los atributos disponibles para cada tipo de programa, consulta las tablas que se incluyen más abajo).
Inserta el programa en el proveedor:
var programUri = context.contentResolver.insert( TvContractCompat.PreviewPrograms.CONTENT_URI, builder.build().toContentValues() )
Obtén el ID de programa para referencia futura:
val programId = ContentUris.parseId(programUri)
Cómo agregar programas al canal "Ver a continuación"
Para insertar programas en el canal Mirar a continuación, consulta Cómo agregar programas al canal Mirar a continuación.
Cómo actualizar un programa
Puedes cambiar la información de un programa, Por ejemplo, tal vez quieras actualizar el precio de alquiler de una película o una barra de progreso que muestre qué parte de un programa miró el usuario.
Usa un PreviewProgram.Builder para establecer los atributos que necesitas cambiar y, luego,
llama a getContentResolver().update para actualizar el programa. Especifica el ID del programa que guardaste cuando se agregó originalmente:
context.contentResolver.update( TvContractCompat.buildPreviewProgramUri(programId), builder.build().toContentValues(), null, null )
Cómo borrar un programa
context.contentResolver .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)
Cómo controlar las acciones del usuario
Tu app puede ayudar a los usuarios a descubrir contenido proporcionando una IU para mostrar y agregar canales. Tu app también debe controlar las interacciones con tus canales después de que aparezcan en la pantalla principal.
Cómo descubrir y agregar canales
Tu app puede proporcionar un elemento de la IU que permita al usuario seleccionar y agregar sus canales (por ejemplo, un botón que solicite agregar el canal).
Después de que el usuario solicite un canal específico, ejecuta este código para obtener el permiso del usuario y agregarlo a la IU de la pantalla principal:
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
}
El sistema muestra un diálogo que solicita al usuario que apruebe el canal. Controla el
resultado de la solicitud en el método onActivityResult de tu actividad
(Activity.RESULT_CANCELED o Activity.RESULT_OK).
Eventos de la pantalla principal de Android TV
Cuando el usuario interactúa con los programas y canales que publica la app, la pantalla principal envía intents a la app:
- La pantalla principal envía el
Urialmacenado en el atributo APP_LINK_INTENT_URI de un canal a la app cuando el usuario selecciona el logotipo del canal. La app solo debe iniciar su IU principal o una vista relacionada con el canal seleccionado. - La pantalla principal envía a la app el
Urialmacenado en el atributo INTENT_URI de un programa cuando el usuario selecciona un programa. La app debería reproducir el contenido seleccionado. - El usuario puede indicar que ya no le interesa un programa y que quiere quitarlo de la IU de la pantalla principal. El sistema quita el programa de la IU y envía a la app propietaria del programa un intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED o android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) con el ID del programa. La app debe quitar el programa del proveedor y NO debe volver a insertarlo.
Asegúrate de crear filtros de intents para todos los Uris que envía la pantalla principal para las interacciones del usuario, por ejemplo:
<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>
Consideraciones adicionales
- Muchas apps de TV requieren que los usuarios accedan. En este caso, el
BroadcastReceiverque escuchaandroid.media.tv.action.INITIALIZE_PROGRAMSdebería sugerir contenido del canal para los usuarios no autenticados. Por ejemplo, tu app puede mostrar inicialmente el mejor contenido o el contenido popular en ese momento. Después de que el usuario accede, puede mostrar contenido personalizado. Esta es una gran oportunidad para que las apps realicen ventas incrementales a los usuarios antes de que accedan. - Cuando tu app no esté en primer plano y necesites actualizar un canal o un programa, usa
JobSchedulerpara programar el trabajo (consultaJobScheduleryJobService). - El sistema puede revocar los permisos de proveedor de tu app si esta se comporta de forma inadecuada (por ejemplo, si envía spam de forma continua al proveedor con datos). Asegúrate de unir el código que accede al proveedor con cláusulas try-catch para controlar las excepciones de seguridad.
- Antes de actualizar los programas y canales, consulta al proveedor los datos que necesitas actualizar y conciliar. Por ejemplo, no es necesario actualizar un programa que el usuario desea quitar de la IU. Usa un trabajo en segundo plano que inserte o actualice tus datos en el proveedor después de consultar los datos existentes y, luego, solicita la aprobación de tus canales. Puedes ejecutar este trabajo cuando se inicie la app y cada vez que esta necesite actualizar sus datos.
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. } } })
- Use URI exclusivas para todas las imágenes (logotipos, íconos, imágenes de contenido). Asegúrate de usar un URI diferente cuando actualices una imagen. Todas las imágenes se almacenan en caché. Si no cambias el URI cuando cambias la imagen, seguirá apareciendo la imagen anterior.
- Recuerda que no se permiten las cláusulas WHERE y que las llamadas a los proveedores con cláusulas WHERE arrojarán una excepción de seguridad.
Atributos
En esta sección, se describen los atributos de canal y de programa por separado.
Atributos de canal
Debes especificar los siguientes atributos para cada canal:
| Atributo | Notas |
|---|---|
| TIPO | Se define en TYPE_PREVIEW. |
| DISPLAY_NAME | Se define en el nombre del canal. |
| APP_LINK_INTENT_URI | Cuando el usuario selecciona el logotipo del canal, el sistema envía un intent para iniciar una actividad que presenta el contenido relevante al canal. Define este atributo en la URI usada por el filtro de intent para esa actividad. |
Además, un canal también tiene seis campos reservados para uso interno de la app. Estos campos se pueden usar para almacenar claves o cualquier otro valor que pueda ayudar a la app a asignar el canal a su estructura de datos interna:
- INTERNAL_PROVIDER_ID
- INTERNAL_PROVIDER_DATA
- INTERNAL_PROVIDER_FLAG1
- INTERNAL_PROVIDER_FLAG2
- INTERNAL_PROVIDER_FLAG3
- INTERNAL_PROVIDER_FLAG4
Atributos de programa
Consulta las páginas individuales de los atributos para cada tipo de programa:
- Atributos de programa de video
- Atributos de programa de audio
- Atributo de programa de juegos
- Atributos de programa "Ver a continuación"
Código de muestra
Para obtener más información sobre cómo compilar apps que interactúen con la pantalla principal y agregar canales y programas a la pantalla principal de Android TV, consulta nuestro codelab de la pantalla principal.