Cómo permitir las búsquedas en apps para TV

Android TV usa la interfaz de búsqueda de Android para recuperar datos de contenido de las apps instaladas y enviar los resultados de la búsqueda al usuario. Se pueden incluir los datos de contenido de tu app con estos resultados para brindar al usuario acceso instantáneo al contenido.

Tu app debe proporcionar a Android TV los campos de datos desde los que el sistema pueda generar resultados de búsqueda sugeridos a medida que el usuario ingresa caracteres en el diálogo de búsqueda. Para ello, tu app debe implementar un proveedor de contenido que entregue las sugerencias junto con un archivo de configuración searchable.xml que describa el proveedor de contenido y otra información vital para Android TV. También necesitas una actividad que controle el intent que se activa cuando el usuario selecciona un resultado de la búsqueda sugerido. Para obtener más detalles, consulta Cómo agregar sugerencias de búsqueda personalizadas. En esta guía, se abordan los puntos principales específicos de las apps para Android TV.

Antes de leer esta guía, asegúrate de conocer los conceptos que se explican en la guía de la API de búsqueda. Además, consulta Cómo agregar la funcionalidad de búsqueda.

El código de muestra que aparece en esta guía proviene de la app de ejemplo de Leanback.

Cómo identificar columnas

La SearchManager describe los campos de datos que espera representando como columnas de una base de datos local. Sin importar el formato de los datos, debes asignar los campos de datos a estas columnas, por lo general, en la clase que accede a los datos de tu contenido. Para obtener más información sobre cómo compilar una clase que asigne tus datos existentes a los campos obligatorios, consulta Cómo crear una tabla de sugerencias.

La clase SearchManager incluye varias columnas para Android TV. Algunas de las columnas más importantes se describen en la siguiente tabla.

Para el marco de trabajo de búsqueda, se necesitan las siguientes columnas:

• SUGGEST_COLUMN_TEXT_1
• SUGGEST_COLUMN_PRODUCTION_YEAR
• SUGGEST_COLUMN_DURATION

Cuando los valores de estas columnas de tu contenido coinciden con los valores para el mismo contenido de otros proveedores que se encuentran en los servidores de Google, el sistema proporciona un vínculo directo a tu app en la vista de detalles del contenido, junto con vínculos a las apps de otros proveedores. Esto se explica con más detalle en la sección Vínculo directo a tu app en la pantalla de detalles.

La clase de la base de datos de tu app puede definir las columnas de la siguiente manera:

class VideoDatabase {
    companion object {
        // The columns we'll include in the video database table
        val KEY_NAME = SearchManager.SUGGEST_COLUMN_TEXT_1
        val KEY_DESCRIPTION = SearchManager.SUGGEST_COLUMN_TEXT_2
        val KEY_ICON = SearchManager.SUGGEST_COLUMN_RESULT_CARD_IMAGE
        val KEY_DATA_TYPE = SearchManager.SUGGEST_COLUMN_CONTENT_TYPE
        val KEY_IS_LIVE = SearchManager.SUGGEST_COLUMN_IS_LIVE
        val KEY_VIDEO_WIDTH = SearchManager.SUGGEST_COLUMN_VIDEO_WIDTH
        val KEY_VIDEO_HEIGHT = SearchManager.SUGGEST_COLUMN_VIDEO_HEIGHT
        val KEY_AUDIO_CHANNEL_CONFIG = SearchManager.SUGGEST_COLUMN_AUDIO_CHANNEL_CONFIG
        val KEY_PURCHASE_PRICE = SearchManager.SUGGEST_COLUMN_PURCHASE_PRICE
        val KEY_RENTAL_PRICE = SearchManager.SUGGEST_COLUMN_RENTAL_PRICE
        val KEY_RATING_STYLE = SearchManager.SUGGEST_COLUMN_RATING_STYLE
        val KEY_RATING_SCORE = SearchManager.SUGGEST_COLUMN_RATING_SCORE
        val KEY_PRODUCTION_YEAR = SearchManager.SUGGEST_COLUMN_PRODUCTION_YEAR
        val KEY_COLUMN_DURATION = SearchManager.SUGGEST_COLUMN_DURATION
        val KEY_ACTION = SearchManager.SUGGEST_COLUMN_INTENT_ACTION
        ...
    }
    ...
}

public class VideoDatabase {
    // The columns we'll include in the video database table
    public static final String KEY_NAME = SearchManager.SUGGEST_COLUMN_TEXT_1;
    public static final String KEY_DESCRIPTION = SearchManager.SUGGEST_COLUMN_TEXT_2;
    public static final String KEY_ICON = SearchManager.SUGGEST_COLUMN_RESULT_CARD_IMAGE;
    public static final String KEY_DATA_TYPE = SearchManager.SUGGEST_COLUMN_CONTENT_TYPE;
    public static final String KEY_IS_LIVE = SearchManager.SUGGEST_COLUMN_IS_LIVE;
    public static final String KEY_VIDEO_WIDTH = SearchManager.SUGGEST_COLUMN_VIDEO_WIDTH;
    public static final String KEY_VIDEO_HEIGHT = SearchManager.SUGGEST_COLUMN_VIDEO_HEIGHT;
    public static final String KEY_AUDIO_CHANNEL_CONFIG =
            SearchManager.SUGGEST_COLUMN_AUDIO_CHANNEL_CONFIG;
    public static final String KEY_PURCHASE_PRICE = SearchManager.SUGGEST_COLUMN_PURCHASE_PRICE;
    public static final String KEY_RENTAL_PRICE = SearchManager.SUGGEST_COLUMN_RENTAL_PRICE;
    public static final String KEY_RATING_STYLE = SearchManager.SUGGEST_COLUMN_RATING_STYLE;
    public static final String KEY_RATING_SCORE = SearchManager.SUGGEST_COLUMN_RATING_SCORE;
    public static final String KEY_PRODUCTION_YEAR = SearchManager.SUGGEST_COLUMN_PRODUCTION_YEAR;
    public static final String KEY_COLUMN_DURATION = SearchManager.SUGGEST_COLUMN_DURATION;
    public static final String KEY_ACTION = SearchManager.SUGGEST_COLUMN_INTENT_ACTION;
...

Cuando compilas el mapa desde las columnas SearchManager hasta tus campos de datos, también debes especificar el _ID para asignar un ID único a cada fila.

companion object {
    ....
    private fun buildColumnMap(): Map<String, String> {
        return mapOf(
          KEY_NAME to KEY_NAME,
          KEY_DESCRIPTION to KEY_DESCRIPTION,
          KEY_ICON to KEY_ICON,
          KEY_DATA_TYPE to KEY_DATA_TYPE,
          KEY_IS_LIVE to KEY_IS_LIVE,
          KEY_VIDEO_WIDTH to KEY_VIDEO_WIDTH,
          KEY_VIDEO_HEIGHT to KEY_VIDEO_HEIGHT,
          KEY_AUDIO_CHANNEL_CONFIG to KEY_AUDIO_CHANNEL_CONFIG,
          KEY_PURCHASE_PRICE to KEY_PURCHASE_PRICE,
          KEY_RENTAL_PRICE to KEY_RENTAL_PRICE,
          KEY_RATING_STYLE to KEY_RATING_STYLE,
          KEY_RATING_SCORE to KEY_RATING_SCORE,
          KEY_PRODUCTION_YEAR to KEY_PRODUCTION_YEAR,
          KEY_COLUMN_DURATION to KEY_COLUMN_DURATION,
          KEY_ACTION to KEY_ACTION,
          BaseColumns._ID to ("rowid AS " + BaseColumns._ID),
          SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID to ("rowid AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID),
          SearchManager.SUGGEST_COLUMN_SHORTCUT_ID to ("rowid AS " + SearchManager.SUGGEST_COLUMN_SHORTCUT_ID)
        )
    }
}

...
  private static HashMap<String, String> buildColumnMap() {
    HashMap<String, String> map = new HashMap<String, String>();
    map.put(KEY_NAME, KEY_NAME);
    map.put(KEY_DESCRIPTION, KEY_DESCRIPTION);
    map.put(KEY_ICON, KEY_ICON);
    map.put(KEY_DATA_TYPE, KEY_DATA_TYPE);
    map.put(KEY_IS_LIVE, KEY_IS_LIVE);
    map.put(KEY_VIDEO_WIDTH, KEY_VIDEO_WIDTH);
    map.put(KEY_VIDEO_HEIGHT, KEY_VIDEO_HEIGHT);
    map.put(KEY_AUDIO_CHANNEL_CONFIG, KEY_AUDIO_CHANNEL_CONFIG);
    map.put(KEY_PURCHASE_PRICE, KEY_PURCHASE_PRICE);
    map.put(KEY_RENTAL_PRICE, KEY_RENTAL_PRICE);
    map.put(KEY_RATING_STYLE, KEY_RATING_STYLE);
    map.put(KEY_RATING_SCORE, KEY_RATING_SCORE);
    map.put(KEY_PRODUCTION_YEAR, KEY_PRODUCTION_YEAR);
    map.put(KEY_COLUMN_DURATION, KEY_COLUMN_DURATION);
    map.put(KEY_ACTION, KEY_ACTION);
    map.put(BaseColumns._ID, "rowid AS " +
            BaseColumns._ID);
    map.put(SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID, "rowid AS " +
            SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID);
    map.put(SearchManager.SUGGEST_COLUMN_SHORTCUT_ID, "rowid AS " +
            SearchManager.SUGGEST_COLUMN_SHORTCUT_ID);
    return map;
  }
...

En el ejemplo anterior, observa la asignación del campo SUGGEST_COLUMN_INTENT_DATA_ID. Esta es la parte del URI que apunta al contenido único de los datos de esta fila (la última parte del URI, que describe dónde se almacena el contenido). La primera parte del URI, cuando es común a todas las filas de la tabla, se configura en el archivo searchable.xml como el atributo android:searchSuggestIntentData, como se describe en la sección Administra las sugerencias de búsqueda.

Si la primera parte del URI es diferente para cada fila de la tabla, asigna ese valor al campo SUGGEST_COLUMN_INTENT_DATA. Cuando el usuario selecciona este contenido, el intent que se activa proporciona los datos del intent de la combinación del SUGGEST_COLUMN_INTENT_DATA_ID y el atributo android:searchSuggestIntentData o el valor del campo SUGGEST_COLUMN_INTENT_DATA.

Cómo proporcionar datos de sugerencias de búsqueda

Implementa un proveedor de contenido que muestre sugerencias de términos de búsqueda en el diálogo de búsqueda de Android TV. El sistema consulta al proveedor de contenido en busca de sugerencias llamando al método query() cada vez que se escribe una letra. En tu implementación de query(), el proveedor de contenido busca tus datos de sugerencias y muestra un Cursor que apunta a las filas que designaste para sugerencias.

fun query(uri: Uri, projection: Array<String>, selection: String, selectionArgs: Array<String>,
        sortOrder: String): Cursor {
    // Use the UriMatcher to see what kind of query we have and format the db query accordingly
    when (URI_MATCHER.match(uri)) {
        SEARCH_SUGGEST -> {
            Log.d(TAG, "search suggest: ${selectionArgs[0]} URI: $uri")
            if (selectionArgs == null) {
                throw IllegalArgumentException(
                        "selectionArgs must be provided for the Uri: $uri")
            }
            return getSuggestions(selectionArgs[0])
        }
        else -> throw IllegalArgumentException("Unknown Uri: $uri")
    }
}

private fun getSuggestions(query: String): Cursor {
    val columns = arrayOf<String>(
            BaseColumns._ID,
            VideoDatabase.KEY_NAME,
            VideoDatabase.KEY_DESCRIPTION,
            VideoDatabase.KEY_ICON,
            VideoDatabase.KEY_DATA_TYPE,
            VideoDatabase.KEY_IS_LIVE,
            VideoDatabase.KEY_VIDEO_WIDTH,
            VideoDatabase.KEY_VIDEO_HEIGHT,
            VideoDatabase.KEY_AUDIO_CHANNEL_CONFIG,
            VideoDatabase.KEY_PURCHASE_PRICE,
            VideoDatabase.KEY_RENTAL_PRICE,
            VideoDatabase.KEY_RATING_STYLE,
            VideoDatabase.KEY_RATING_SCORE,
            VideoDatabase.KEY_PRODUCTION_YEAR,
            VideoDatabase.KEY_COLUMN_DURATION,
            VideoDatabase.KEY_ACTION,
            SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID
    )
    return videoDatabase.getWordMatch(query.toLowerCase(), columns)
}

@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
        String sortOrder) {
    // Use the UriMatcher to see what kind of query we have and format the db query accordingly
    switch (URI_MATCHER.match(uri)) {
        case SEARCH_SUGGEST:
            Log.d(TAG, "search suggest: " + selectionArgs[0] + " URI: " + uri);
            if (selectionArgs == null) {
                throw new IllegalArgumentException(
                        "selectionArgs must be provided for the Uri: " + uri);
            }
            return getSuggestions(selectionArgs[0]);
        default:
            throw new IllegalArgumentException("Unknown Uri: " + uri);
    }
}

private Cursor getSuggestions(String query) {
    query = query.toLowerCase();
    String[] columns = new String[]{
        BaseColumns._ID,
        VideoDatabase.KEY_NAME,
        VideoDatabase.KEY_DESCRIPTION,
        VideoDatabase.KEY_ICON,
        VideoDatabase.KEY_DATA_TYPE,
        VideoDatabase.KEY_IS_LIVE,
        VideoDatabase.KEY_VIDEO_WIDTH,
        VideoDatabase.KEY_VIDEO_HEIGHT,
        VideoDatabase.KEY_AUDIO_CHANNEL_CONFIG,
        VideoDatabase.KEY_PURCHASE_PRICE,
        VideoDatabase.KEY_RENTAL_PRICE,
        VideoDatabase.KEY_RATING_STYLE,
        VideoDatabase.KEY_RATING_SCORE,
        VideoDatabase.KEY_PRODUCTION_YEAR,
        VideoDatabase.KEY_COLUMN_DURATION,
        VideoDatabase.KEY_ACTION,
        SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID
    };
    return videoDatabase.getWordMatch(query, columns);
}
...

En tu archivo de manifiesto, el proveedor de contenido recibe un tratamiento especial. En lugar de etiquetarse como una actividad, se describe como <provider>. El proveedor incluye el atributo android:authorities para indicarle al sistema el espacio de nombres de tu proveedor de contenido. Además, debes establecer su atributo android:exported en "true" para que la búsqueda global de Android pueda usar los resultados que se muestran.

<provider android:name="com.example.android.tvleanback.VideoContentProvider"
    android:authorities="com.example.android.tvleanback"
    android:exported="true" />

Cómo controlar sugerencias de búsqueda

Tu app debe incluir un archivo res/xml/searchable.xml para establecer la configuración de las sugerencias de búsqueda.

En el archivo res/xml/searchable.xml, incluye el atributo android:searchSuggestAuthority para indicarle al sistema cuál es el espacio de nombres de tu proveedor de contenido. Este debe coincidir con el valor de cadena que especificas en el atributo android:authorities del elemento <provider> en tu archivo AndroidManifest.xml.

Además, incluye una etiqueta, que es el nombre de la aplicación. La configuración de la búsqueda del sistema usa esta etiqueta cuando enumera las apps en las que se puede buscar.

El archivo searchable.xml también debe incluir android:searchSuggestIntentAction con el valor "android.intent.action.VIEW" para definir la acción de intent y proporcionar una sugerencia personalizada. Esto es diferente de la acción de intent para proporcionar un término de búsqueda, como se describe en la siguiente sección. Si deseas conocer otras maneras de declarar la acción de intent para sugerencias, consulta Cómo declarar la acción de intent.

Junto con la acción de intent, tu app debe proporcionar los datos del intent, que debes especificar con el atributo android:searchSuggestIntentData. Esta es la primera parte del URI que apunta al contenido, que describe la parte del URI común a todas las filas de la tabla de asignación para ese contenido. La parte del URI que es única para cada fila se establece con el campo SUGGEST_COLUMN_INTENT_DATA_ID, como se describe en la sección Cómo identificar columnas. Si deseas conocer otras maneras de declarar los datos del intent para sugerencias, consulta Cómo declarar los datos del intent.

El atributo android:searchSuggestSelection=" ?" especifica el valor que se pasa como parámetro selection del método query(). El valor del signo de interrogación (?) se reemplaza por el texto de la consulta.

Por último, también debes incluir el atributo android:includeInGlobalSearch con el valor "true". Este es un archivo searchable.xml de ejemplo:

<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:searchSettingsDescription="@string/settings_description"
    android:searchSuggestAuthority="com.example.android.tvleanback"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestIntentData="content://com.example.android.tvleanback/video_database_leanback"
    android:searchSuggestSelection=" ?"
    android:searchSuggestThreshold="1"
    android:includeInGlobalSearch="true">
</searchable>

Cómo controlar términos de búsqueda

En cuanto el diálogo de búsqueda tenga una palabra que coincida con el valor de una de las columnas de tu app, como se describe en la sección Cómo identificar columnas, el sistema activará el intent ACTION_SEARCH. La actividad de tu app que controla ese intent busca columnas en el repositorio con la palabra dada en sus valores y muestra una lista de elementos de contenido con esas columnas. En el archivo AndroidManifest.xml, designa la actividad que controla el intent ACTION_SEARCH como se muestra en el siguiente ejemplo:

...
  <activity
      android:name="com.example.android.tvleanback.DetailsActivity"
      android:exported="true">

      <!-- Receives the search request. -->
      <intent-filter>
          <action android:name="android.intent.action.SEARCH" />
          <!-- No category needed, because the Intent will specify this class component -->
      </intent-filter>

      <!-- Points to searchable meta data. -->
      <meta-data android:name="android.app.searchable"
          android:resource="@xml/searchable" />
  </activity>
...
  <!-- Provides search suggestions for keywords against video meta data. -->
  <provider android:name="com.example.android.tvleanback.VideoContentProvider"
      android:authorities="com.example.android.tvleanback"
      android:exported="true" />
...

La actividad también debe describir la configuración que se puede buscar con una referencia al archivo searchable.xml. Para usar el diálogo de búsqueda global, el manifiesto debe describir qué actividad debería recibir consultas de búsqueda. El manifiesto también debe describir el elemento <provider> , exactamente como se describe en el archivo searchable.xml.

Vínculo directo a tu app en la pantalla de detalles

Si estableciste la configuración de búsqueda como se describe en la sección Cómo controlar las sugerencias de búsqueda y asignaste los campos SUGGEST_COLUMN_TEXT_1, SUGGEST_COLUMN_PRODUCTION_YEAR y SUGGEST_COLUMN_DURATION como se describe en la sección Cómo identificar columnas, aparece un vínculo directo a una acción de visualización de tu contenido en la pantalla de detalles que se inicia cuando el usuario selecciona un resultado de la búsqueda:

Cuando el usuario selecciona el vínculo para tu app, que se identifica con el botón **Available On** en la pantalla de detalles, el sistema inicia la actividad que controla el ACTION_VIEW configurado como android:searchSuggestIntentAction con el valor "android.intent.action.VIEW" en el archivo searchable.xml.

También puedes configurar un intent personalizado para que inicie tu actividad. Esto se demuestra en la app de ejemplo de Leanback. Ten en cuenta que la app de ejemplo inicia su propio LeanbackDetailsFragment para mostrar los detalles del contenido multimedia seleccionado. En tus apps, inicia la actividad que reproduce el contenido multimedia de inmediato para ahorrarle al usuario uno o dos clics más.

Comportamiento de búsqueda

La búsqueda está disponible en Android TV desde la pantalla principal y desde tu app. Los resultados de la búsqueda son diferentes para estos dos casos.

Cómo buscar desde la pantalla principal

Cuando el usuario realiza una búsqueda desde la pantalla principal, el primer resultado aparece en una tarjeta de entidad. Si hay apps que puedan reproducir el contenido, aparecerá un vínculo a cada una en la parte inferior de la tarjeta:

No puedes colocar de manera programática una app en la tarjeta de entidad. Para que se incluyan como opción de reproducción, los resultados de la búsqueda de una app deben coincidir con el título, el año y la duración del contenido que se buscó.

Es posible que haya más resultados de la búsqueda disponibles debajo de la tarjeta. Para verlos, el usuario debe mantener presionado el control remoto y desplazarse hacia abajo. Los resultados para cada aplicación aparecen en una fila independiente. No puedes controlar el orden de las filas. En primer lugar, se enumeran las apps que admiten acciones de reproducción.

Cómo buscar desde tu app

El usuario también puede iniciar una búsqueda desde tu app iniciando el micrófono desde el control remoto o un controlador para juegos. Los resultados de la búsqueda se muestran en una sola fila, encima del contenido de la app. Tu app genera resultados de la búsqueda usando su propio proveedor de búsqueda global.

Más información

Si quieres obtener más información sobre cómo realizar búsquedas en una app para TV, consulta Cómo integrar funciones de búsqueda de Android a tu app y Cómo agregar funciones de búsqueda.

Si quieres obtener más información para personalizar la experiencia de búsqueda en la app con una SearchFragment, consulta Cómo realizar búsquedas en apps para TV.