TV-Apps suchbar machen

Android TV verwendet die Android-Suchoberfläche , um Inhaltsdaten aus installierten Apps abzurufen und dem Nutzer Suchergebnisse zu präsentieren. Die Inhaltsdaten Ihrer App können in diese Ergebnisse aufgenommen werden, damit der Nutzer sofort auf die Inhalte in Ihrer App zugreifen kann.

Ihre App muss Android TV die Datenfelder zur Verfügung stellen, aus denen Android TV vorgeschlagene Suchergebnisse generieren kann, während der Nutzer Zeichen in das Suchfeld eingibt. Dazu muss Ihre App einen Content Provider implementieren, der die Vorschläge zusammen mit einer searchable.xml-Konfigurationsdatei bereitstellt, die den Content Provider und andere wichtige Informationen für Android TV beschreibt. Außerdem benötigen Sie eine Aktivität, die den Intent verarbeitet, der ausgelöst wird, wenn der Nutzer ein vorgeschlagenes Suchergebnis auswählt. Weitere Informationen finden Sie unter Benutzerdefinierte Suchvorschläge hinzufügen. In diesem Leitfaden werden die wichtigsten Punkte behandelt, die für Android TV-Apps spezifisch sind.

Bevor Sie diesen Leitfaden lesen, sollten Sie mit den Konzepten vertraut sein, die im Leitfaden zur Search API erläutert werden. Lesen Sie außerdem Suchfunktion hinzufügen.

Der Beispielcode in diesem Leitfaden stammt aus der Leanback-Beispiel-App .

Spalten identifizieren

Der SearchManager beschreibt die erwarteten Datenfelder, indem er sie als Spalten einer lokalen Datenbank darstellt. Unabhängig vom Format Ihrer Daten müssen Sie Ihre Datenfelder diesen Spalten zuordnen, in der Regel in der Klasse, die auf Ihre Inhaltsdaten zugreift. Informationen zum Erstellen einer Klasse, die Ihre vorhandenen Daten den erforderlichen Feldern zuordnet, finden Sie unter Vorschlagstabelle erstellen.

Die Klasse SearchManager enthält mehrere Spalten für Android TV. Einige der wichtigsten Spalten werden in der folgenden Tabelle beschrieben.

Für das Suchframework sind die folgenden Spalten erforderlich:

• SUGGEST_COLUMN_TEXT_1
• SUGGEST_COLUMN_PRODUCTION_YEAR
• SUGGEST_COLUMN_DURATION

Wenn die Werte dieser Spalten für Ihre Inhalte mit den Werten für dieselben Inhalte anderer Anbieter übereinstimmen, die von Google-Servern gefunden wurden, stellt das System in der Detailansicht für die Inhalte einen Deeplink zu Ihrer App sowie Links zu den Apps anderer Anbieter bereit. Weitere Informationen finden Sie in dem Deeplink zu Ihrer App auf dem Detailbildschirm Abschnitt.

Die Datenbankklasse Ihrer Anwendung kann die Spalten so definieren:

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;
...

Wenn Sie die Zuordnung der SearchManager-Spalten zu Ihren Datenfeldern erstellen, müssen Sie auch _ID angeben, um jeder Zeile eine eindeutige ID zu geben.

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;
  }
...

Im vorherigen Beispiel sehen Sie die Zuordnung zum Feld SUGGEST_COLUMN_INTENT_DATA_ID. Dies ist der Teil des URI, der auf die Inhalte verweist, die für die Daten in dieser Zeile eindeutig sind – der letzte Teil des URI, der beschreibt, wo die Inhalte gespeichert sind. Der erste Teil des URI, wenn er für alle Zeilen in der Tabelle gleich ist, wird in der searchable.xml Datei als android:searchSuggestIntentData Attribut festgelegt, wie im Abschnitt Suchvorschläge verarbeiten beschrieben.

Wenn sich der erste Teil des URI für jede Zeile in der Tabelle unterscheidet, ordnen Sie diesen Wert dem Feld SUGGEST_COLUMN_INTENT_DATA zu. Wenn der Nutzer diese Inhalte auswählt, liefert der ausgelöste Intent die Intent-Daten aus der Kombination von SUGGEST_COLUMN_INTENT_DATA_ID und entweder dem Attribut android:searchSuggestIntentData oder dem SUGGEST_COLUMN_INTENT_DATA Feldwert.

Daten für Suchvorschläge bereitstellen

Implementieren Sie einen Content Provider um Suchbegriffsvorschläge an das Android TV-Suchfeld zurückzugeben. Das System fragt Ihren Content Provider nach Vorschlägen ab, indem es jedes Mal, wenn ein Buchstabe eingegeben wird, die Methode query() aufruft. In Ihrer Implementierung von query() durchsucht Ihr Content Provider Ihre Vorschlagsdaten und gibt einen Cursor zurück, der auf die Zeilen verweist, die Sie für Vorschläge festgelegt haben.

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);
}
...

In Ihrer Manifestdatei wird der Content Provider besonders behandelt. Er wird nicht als Aktivität getaggt, sondern als <provider>beschrieben. Der Provider enthält das Attribut android:authorities, um dem System den Namespace Ihres Content Providers mitzuteilen. Außerdem müssen Sie das Attribut android:exported auf "true" setzen, damit die globale Android-Suche die von ihm zurückgegebenen Ergebnisse verwenden kann.

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

Suchvorschläge verarbeiten

Ihre App muss eine Datei res/xml/searchable.xml enthalten, um die Einstellungen für Suchvorschläge zu konfigurieren.

Fügen Sie in der res/xml/searchable.xml Datei das android:searchSuggestAuthority Attribut ein, um dem System den Namespace Ihres Content Providers mitzuteilen. Dieser muss mit dem Stringwert übereinstimmen, den Sie im android:authorities Attribut des <provider> Elements in Ihrer AndroidManifest.xml Datei angeben.

Fügen Sie auch ein Label hinzu, das der Name der Anwendung ist. Die Systemeinstellungen für die Suche verwenden dieses Label, wenn durchsuchbare Apps aufgelistet werden.

Die searchable.xml Datei muss auch android:searchSuggestIntentAction mit dem Wert "android.intent.action.VIEW" enthalten, um die Intent-Aktion für die Bereitstellung eines benutzerdefinierten Vorschlags zu definieren. Dies unterscheidet sich von der Intent Aktion für die Bereitstellung eines Suchbegriffs, wie im folgenden Abschnitt beschrieben. Weitere Möglichkeiten zum Deklarieren der Intent-Aktion für Vorschläge, siehe Intent-Aktion deklarieren.

Neben der Intent-Aktion muss Ihre App auch die Intent-Daten bereitstellen, die Sie mit dem android:searchSuggestIntentData Attribut angeben. Dies ist der erste Teil des URI, der auf die Inhalte verweist. Er beschreibt den Teil des URI, der für alle Zeilen in der Zuordnungstabelle für diese Inhalte gleich ist. Der Teil des URI, der für jede Zeile eindeutig ist, wird mit dem SUGGEST_COLUMN_INTENT_DATA_ID Feld, wie im Abschnitt Spalten identifizieren beschrieben, festgelegt. Weitere Möglichkeiten zum Deklarieren der Intent-Daten für Vorschläge finden Sie unter Intent-Daten deklarieren.

Das Attribut android:searchSuggestSelection=" ?" gibt den Wert an, der als Parameter selection der Methode query() übergeben wird. Der Wert des Fragezeichens (?) wird durch den Abfragetext ersetzt.

Schließlich müssen Sie auch das android:includeInGlobalSearch Attribut mit dem Wert "true" einfügen. Hier ist ein Beispiel für eine searchable.xml-Datei:

<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>

Suchbegriffe verarbeiten

Sobald das Suchfeld ein Wort enthält, das mit dem Wert in einer der Spalten Ihrer App übereinstimmt, wie im Abschnitt Spalten identifizieren beschrieben, löst das System den ACTION_SEARCH Intent aus. Die Aktivität in Ihrer App, die diesen Intent verarbeitet, durchsucht das Repository nach Spalten, deren Werte das angegebene Wort enthalten, und gibt eine Liste von Inhaltselementen mit diesen Spalten zurück. In Ihrer Datei AndroidManifest.xml legen Sie die Aktivität fest, die den Intent ACTION_SEARCH verarbeitet, wie im folgenden Beispiel gezeigt:

...
  <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" />
...

Die Aktivität muss auch die durchsuchbare Konfiguration mit einem Verweis auf die searchable.xml Datei beschreiben. Damit das globale Suchfeld verwendet werden kann, muss im Manifest angegeben werden, welche Aktivität Suchanfragen erhalten soll. Das Manifest muss auch das <provider> Element genau so beschreiben, wie es in der searchable.xml Datei beschrieben ist.

Deeplink zu Ihrer App auf dem Detailbildschirm

Wenn Sie die Suchkonfiguration wie im Abschnitt Suchvorschläge verarbeiten beschrieben eingerichtet und die Felder SUGGEST_COLUMN_TEXT_1, SUGGEST_COLUMN_PRODUCTION_YEAR, und SUGGEST_COLUMN_DURATION wie im Abschnitt Spalten identifizieren beschrieben zugeordnet haben, wird auf dem Detailbildschirm, der angezeigt wird, wenn der Nutzer ein Suchergebnis auswählt, ein Deeplink zu einer Wiedergabeaktion für Ihre Inhalte angezeigt:

Wenn der Nutzer den Link für Ihre App auswählt, der auf dem Detailbildschirm mit der Schaltfläche **Verfügbar auf** gekennzeichnet ist, startet das System die Aktivität, die ACTION_VIEW verarbeitet, das in der searchable.xml Datei als android:searchSuggestIntentAction mit dem Wert "android.intent.action.VIEW" festgelegt ist.

Sie können auch einen benutzerdefinierten Intent einrichten, um Ihre Aktivität zu starten. Dies wird in der Leanback-Beispiel-App gezeigt. Beachten Sie, dass die Beispiel-App ihr eigenes LeanbackDetailsFragment startet, um die Details für die ausgewählten Medien anzuzeigen. In Ihren Apps sollten Sie die Aktivität starten, die die Medien sofort wiedergibt, damit der Nutzer nicht noch ein- oder zweimal klicken muss.

Suchverhalten

Die Suche ist in Android TV über den Startbildschirm und in Ihrer App verfügbar. Die Suchergebnisse unterscheiden sich in diesen beiden Fällen.

Vom Startbildschirm suchen

Wenn der Nutzer vom Startbildschirm aus sucht, wird das erste Ergebnis auf einer Entitätskarte angezeigt. Wenn es Apps gibt, die die Inhalte wiedergeben können, wird unten auf der Karte ein Link zu jeder App angezeigt:

Sie können eine App nicht programmatisch auf der Entitätskarte platzieren. Damit eine App als Wiedergabeoption angezeigt wird, müssen die Suchergebnisse der App mit dem Titel, dem Jahr und der Dauer der gesuchten Inhalte übereinstimmen.

Unter der Karte sind möglicherweise weitere Suchergebnisse verfügbar. Um sie zu sehen, muss der Nutzer auf der Fernbedienung nach unten drücken und scrollen. Die Ergebnisse für jede App werden in einer separaten Zeile angezeigt. Sie können die Reihenfolge der Zeilen nicht steuern. Apps, die Wiedergabeaktionen unterstützen, werden zuerst aufgeführt.

In Ihrer App suchen

Der Nutzer kann auch in Ihrer App eine Suche starten, indem er das Mikrofon über die Fernbedienung oder den Gamepad-Controller aktiviert. Die Suchergebnisse werden in einer einzelnen Zeile über den Inhalten der App angezeigt. Ihre App generiert Suchergebnisse mit ihrem eigenen globalen Suchanbieter.

Weitere Informationen

Weitere Informationen zur Suche in einer TV-App finden Sie unter Android-Suchfunktionen in Ihre App einbinden und Suchfunktion hinzufügen.

Weitere Informationen zum Anpassen der Suche in der App mit einem SearchFragment finden Sie unter In TV-Apps suchen.