Umgang mit TV-Hardware

TV-Hardware unterscheidet sich erheblich von anderen Android-Geräten. Fernseher haben einige der Hardwarefunktionen anderer Android-Geräte nicht, z. B. Touchscreens, Kameras und GPS-Empfänger. Fernseher sind außerdem vollständig von sekundären Hardwaregeräten abhängig: Damit Nutzer mit TV-Apps interagieren können, müssen sie eine Fernbedienung oder ein Gamepad verwenden. (Informationen zu den verschiedenen Eingabemethoden findest du unter TV-Controller verwalten.)

Wenn du eine App für Fernseher entwickelst, solltest du die Hardwareeinschränkungen und -anforderungen für den Betrieb auf TV-Hardware sorgfältig berücksichtigen. Prüfen, ob die App auf einem Fernseher ausgeführt wird, und nicht unterstützte Hardwarefunktionen verarbeiten.

Nach einem TV-Gerät suchen

Wenn du eine App entwickelst, die sowohl auf TV-Geräten als auch auf anderen Geräten funktioniert, musst du möglicherweise prüfen, auf welchem Gerätetyp deine App ausgeführt wird, und die Funktionsweise deiner App anpassen. Wenn du beispielsweise eine App hast, die über einen Intent gestartet werden kann, prüfe die Geräteeigenschaften, um festzustellen, ob eine TV-orientierte Aktivität oder eine Smartphone-Aktivität gestartet werden soll.

Die empfohlene Methode, um festzustellen, ob deine App auf einem TV-Gerät ausgeführt wird, ist die Methode PackageManager.hasSystemFeature. Damit kannst du prüfen, ob das Gerät im TV-Modus ausgeführt wird. Der folgende Beispielcode zeigt, wie Sie prüfen können, ob Ihre App auf einem TV-Gerät ausgeführt wird:

const val TAG = "DeviceTypeRuntimeCheck"

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK)
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device")
} else {
    Log.d(TAG, "Running on a non-TV Device")
}
Hardware.kt

public static final String TAG = "DeviceTypeRuntimeCheck";

boolean isTelevision = getPackageManager().hasSystemFeature(PackageManager.FEATURE_LEANBACK);
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device");
} else {
    Log.d(TAG, "Running on a non-TV Device");
}

Nicht unterstützte Hardwarefunktionen verarbeiten

Je nach Design und Funktionalität deiner App kannst du möglicherweise umgehen, dass bestimmte Hardwarefunktionen nicht verfügbar sind. In diesem Abschnitt wird erläutert, welche Hardwarefunktionen normalerweise nicht für Fernseher verfügbar sind, wie fehlende Hardwarefunktionen erkannt werden und welche Alternativen für diese Funktionen vorgeschlagen werden.

Nicht unterstützte TV-Hardwarefunktionen

Fernseher haben einen anderen Zweck als andere Geräte und verfügen daher nicht über die Hardwarefunktionen, die andere Android-Geräte oft haben. Aus diesem Grund unterstützt das Android-System die folgenden Funktionen für ein TV-Gerät nicht:

Hinweis: Einige TV-Controller haben ein Mikrofon, das nicht mit der hier beschriebenen Mikrofon-Hardwarefunktion identisch ist. Das Mikrofon des Controllers wird vollständig unterstützt.

Eine vollständige Liste der Funktionen, Unterfunktionen und ihrer Deskriptoren finden Sie in der Referenz zu Funktionen.

Hardwareanforderungen für Fernseher deklarieren

Android-Apps können im App-Manifest Hardwareanforderungen deklarieren, um zu verhindern, dass sie auf Geräten installiert werden, die diese Funktionen nicht bieten. Wenn du eine vorhandene App für die Verwendung auf Fernsehern erweiterst, solltest du das Manifest deiner App sorgfältig auf Deklarationen von Hardwareanforderungen prüfen, die die Installation auf einem Fernsehgerät verhindern könnten.

Wenn deine App Hardwarefunktionen wie einen Touchscreen oder eine Kamera verwendet, die auf Fernsehern nicht verfügbar sind, aber auch ohne diese Funktionen genutzt werden kann, musst du in deinem App-Manifest angeben, dass diese Funktionen nicht erforderlich sind. Das folgende Manifest-Code-Snippet zeigt, wie Sie deklarieren, dass Ihre App keine Hardwarefunktionen benötigt, die auf Fernsehern nicht verfügbar sind, diese Funktionen aber auf anderen Geräten verwendet:

<uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/>
<uses-feature android:name="android.hardware.faketouch"
        android:required="false"/>
<uses-feature android:name="android.hardware.telephony"
        android:required="false"/>
<uses-feature android:name="android.hardware.camera"
        android:required="false"/>
<uses-feature android:name="android.hardware.nfc"
        android:required="false"/>
<uses-feature android:name="android.hardware.location.gps"
        android:required="false"/>
<uses-feature android:name="android.hardware.microphone"
        android:required="false"/>
<uses-feature android:name="android.hardware.sensor"
        android:required="false"/>
<!-- Some TV devices have an ethernet connection only -->
<uses-feature android:name="android.hardware.wifi"
        android:required="false"/>

Hinweis: Einige Funktionen haben Unterfunktionen, z. B. android.hardware.camera.front, wie in der Funktionsreferenz beschrieben. Markieren Sie alle Unterfunktionen, die ebenfalls in Ihrer App verwendet werden, als required="false".

Bei allen Apps, die für die Verwendung auf TV-Geräten vorgesehen sind, muss deklariert werden, dass die Touchscreen-Funktion nicht erforderlich ist, wie unter Erste Schritte mit TV-Apps beschrieben. Wenn deine App normalerweise eine oder mehrere der Funktionen verwendet, die von TV-Geräten nicht unterstützt werden, ändere die Attribut-Einstellung android:required für diese Funktionen in deinem Manifest zu false.

Achtung: Wenn du eine Hardwarefunktion als erforderlich deklarierst, indem du ihren Wert auf true setzt, kann deine App nicht auf TV-Geräten installiert werden und wird nicht im Android TV-Startbildschirm-Launcher angezeigt.

Berechtigungen, die Hardwarefunktionen voraussetzen

Einige uses-permission-Manifestdeklarationen implizieren Hardwarefunktionen. Das bedeutet, dass die Anforderung bestimmter Berechtigungen in deinem App-Manifest dazu führen kann, dass deine App nicht auf TV-Geräten installiert und verwendet werden kann. Die folgenden häufig angeforderten Berechtigungen erstellen eine implizite Hardwarefunktionsanforderung:

Eine vollständige Liste der Berechtigungsanfragen, die eine Hardwarefunktion erfordern, findest du im uses-feature-Leitfaden. Wenn deine App eine der oben aufgeführten Funktionen anfordert, füge in deinem Manifest eine uses-feature-Deklaration für die implizierte Hardwarefunktion hinzu, die angibt, dass sie nicht erforderlich ist. android:required="false".

Hinweis: Wenn deine App auf Android 5.0 (API-Level 21) oder höher ausgerichtet ist und die Berechtigung ACCESS_COARSE_LOCATION oder ACCESS_FINE_LOCATION verwendet, können Nutzer deine App auch dann auf einem TV-Gerät installieren, wenn das TV-Gerät keine Netzwerkkarte oder keinen GPS-Empfänger hat.

Nachdem du Hardwarefunktionen für deine App als optional festgelegt hast, musst du die Verfügbarkeit dieser Funktionen zur Laufzeit prüfen und dann das Verhalten deiner App anpassen. Im nächsten Abschnitt wird erläutert, wie du nach Hardwarefunktionen suchst. Außerdem werden einige Ansätze zum Ändern des Verhaltens deiner App vorgeschlagen.

Weitere Informationen zum Filtern und Deklarieren von Funktionen im Manifest findest du im Leitfaden zu uses-feature.

Hardwarefunktionen prüfen

Das Android-Framework kann dir mitteilen, ob Hardwarefunktionen auf dem Gerät, auf dem deine App ausgeführt wird, nicht verfügbar sind. Mit der Methode hasSystemFeature(String) können Sie während der Laufzeit nach bestimmten Funktionen suchen. Diese Methode verwendet ein einzelnes Stringargument, das die Funktion angibt, die Sie prüfen möchten.

Im folgenden Codebeispiel wird gezeigt, wie die Verfügbarkeit von Hardwarefunktionen zur Laufzeit erkannt wird:

// Check whether the telephony hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls")
}

// Check whether android.hardware.touchscreen feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.")
}
Hardware.kt

// Check whether the telephony hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls");
}

// Check whether android.hardware.touchscreen feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.");
}

Touchscreen

Die meisten TV-Geräte haben keine Touchscreens oder Zeigereingabefunktionen und sind für die Navigation vollständig auf Steuerkreuz-Fernbedienungen angewiesen. TV-Apps müssen immer eine Fernbedienung mit Steuerkreuz unterstützen.

Weitere Informationen zur ordnungsgemäßen Unterstützung der Navigation mit TV-freundlichen Steuerelementen findest du unter TV-Navigation.

Touch-Unterstützung deklarieren

Einige TV-Geräte unterstützen Fernbedienungen mit Zeiger und Touchscreens. Ihre App kann Klick-, Hover- und Scroll-Interaktionen wie auf einem Mobilgerät unterstützen, um auf Geräten, die diese unterstützen, eine bessere Nutzererfahrung zu bieten.

Wenn deine App den Touchmodus unterstützt, kannst du die Touch-Unterstützung für die gesamte App oder für einzelne Aktivitäten deklarieren. Füge dazu das Element android.software.leanback.supports_touch <property> mit dem Wert true im Element <application> oder <activity> in deiner AndroidManifest.xml hinzu:

<application ...>
    <property
        android:name="android.software.leanback.supports_touch"
        android:value="true|false" />
    ...
</application>

Hinweis: Auf Geräten, die eine Fernbedienung mit Zeigefunktion (z. B. eine Air Mouse oder ein Trackpad) unterstützen, werden durch Aktivieren dieser Option der Cursor- und der Touchmodus aktiviert, anstatt sich auf die Emulation der Plattformkompatibilität zu verlassen. Eine Deklaration auf Aktivitätsebene überschreibt die Deklaration auf Anwendungsebene für diese Aktivität. Wenn Sie dieses Attribut weglassen, wird standardmäßig false verwendet.

Kamera

Obwohl ein Fernseher normalerweise keine Kamera hat, kannst du trotzdem eine Fotografie-App auf einem Fernseher anbieten. Wenn du beispielsweise eine App hast, mit der Fotos aufgenommen, angesehen und bearbeitet werden können, kannst du die Funktion zum Aufnehmen von Bildern für Fernseher deaktivieren und Nutzern trotzdem erlauben, Fotos anzusehen und sogar zu bearbeiten. Wenn du deine Kamera-App für Fernseher aktivieren möchtest, füge dem App-Manifest die folgende Funktionsdeklaration hinzu:

<uses-feature android:name="android.hardware.camera" android:required="false" />

Wenn du deine App so konfigurierst, dass sie ohne Kamera ausgeführt werden kann, füge deiner App Code hinzu, der erkennt, ob die Kamerafunktion verfügbar ist, und passe die Funktionsweise deiner App entsprechend an. Im folgenden Codebeispiel wird gezeigt, wie du das Vorhandensein einer Kamera erkennst:

// Check whether the camera hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!")
} else {
    Log.d("Camera test", "No camera available. View and edit features only.")
}
Hardware.kt

// Check whether the camera hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!");
} else {
    Log.d("Camera test", "No camera available. View and edit features only.");
}

GPS

Fernseher sind stationäre Geräte für den Innenbereich und haben keine integrierten GPS-Empfänger (Global Positioning System). Wenn deine App Standortinformationen verwendet, kannst du Nutzern trotzdem die Möglichkeit geben, nach einem Standort zu suchen, oder einen statischen Standortanbieter wie eine Postleitzahl verwenden, die bei der Einrichtung des TV-Geräts konfiguriert wurde.

// Request a static location from the location manager.
val locationManager = this.getSystemService(Context.LOCATION_SERVICE) as LocationManager
val location = locationManager.getLastKnownLocation("static")
if (location == null) {
    Log.e(TAG, "Location is null")
    return
}

// Attempt to get postal code from the static location object.
val geocoder = Geocoder(this)
val address: Address? =
        try {
            geocoder.getFromLocation(location.latitude, location.longitude, 1)?.firstOrNull()
                    ?.apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }
Hardware.kt

// Request a static location from the location manager.
LocationManager locationManager = (LocationManager) this.getSystemService(
        Context.LOCATION_SERVICE);
Location location = locationManager.getLastKnownLocation("static");

// Attempt to get postal code from the static location object.
Geocoder geocoder = new Geocoder(this);
Address address = null;
try {
  address = geocoder.getFromLocation(location.getLatitude(),
          location.getLongitude(), 1).get(0);
  Log.d("Postal code", address.getPostalCode());

} catch (IOException e) {
  Log.e(TAG, "Geocoder error", e);
}

Wiedergabe im Energiesparmodus pausieren

Einige TV-Geräte unterstützen einen Energiesparmodus, wenn der Nutzer das Gerät ausschaltet. Anstatt herunterzufahren, deaktiviert das Gerät das Display und lässt Android TV im Hintergrund weiterlaufen. Die Audioausgabe ist in diesem Modus weiterhin aktiviert. Beende daher alle aktuell wiedergegebenen Inhalte, wenn sich das Gerät im Energiesparmodus befindet.

Wenn du die Wiedergabe im Energiesparmodus vermeiden möchtest, überschreibe onStop und beende die Wiedergabe aller aktuell wiedergegebenen Inhalte:

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

Wenn der Nutzer die Stromversorgung wieder einschaltet, wird onStart aufgerufen, sofern Ihre App die aktive App im Vordergrund ist. Weitere Informationen zum Starten und Beenden einer Aktivität finden Sie unter Der Aktivitätslebenszyklus.