Android for Cars App-Bibliothek verwenden

Über die Android for Cars-App-Bibliothek können Sie Ihre Navigations-, POI- und IoT-Apps in Ihr Auto einbinden. Dazu stellt sie eine Reihe von Vorlagen bereit, die den Standards für die Ablenkung von Fahrern entsprechen und Details wie die Vielfalt der Fahrzeugbildschirme und Eingabemodalitäten berücksichtigen.

Dieser Leitfaden bietet einen Überblick über die wichtigsten Funktionen und Konzepte der Bibliothek und führt Sie durch die Einrichtung einer einfachen Anwendung.

Codelab

Grundlagen der Auto-App-Mediathek

arrow_forward

Hinweis

1. Sehen Sie sich die Seiten Design fürs Autofahren an, die die Auto-App-Bibliothek behandeln.
   • Kategorieübersichten für Navigations-Apps und andere fahrbezogene Apps
   • Apps mit Vorlagen erstellen – Übersicht
   • Bausteine für Vorlagen und Vorlagenkomponenten
   • Beispielabläufe für gängige UX-Muster
   • Anforderungen an Vorlagen-Apps
2. Im folgenden Abschnitt finden Sie die wichtigsten Begriffe und Konzepte.
3. Mach dich mit der System-UI von Android Auto und dem Design von Android Automotive OS vertraut.
4. Lesen Sie die Versionshinweise.
5. Sehen Sie sich die Beispiele an.

Wichtige Begriffe und Konzepte

Modelle und Vorlagen

Die Benutzeroberfläche wird durch einen Graphen von Modellobjekten dargestellt, die auf unterschiedliche Weise angeordnet werden können, sofern dies von der zugehörigen Vorlage zulässig ist. Vorlagen sind eine Teilmenge der Modelle, die als Wurzel in diesen Grafiken fungieren können. Modelle umfassen die Informationen, die dem Nutzer in Form von Text und Bildern angezeigt werden sollen, sowie Attribute zur Konfiguration von Aspekten des visuellen Erscheinungsbildes solcher Informationen, z. B. Textfarben oder Bildgrößen. Der Host konvertiert die Modelle in Ansichten, die den Standards für Ablenkungen von Fahrern entsprechen, und kümmert sich um Details wie die Vielfalt der Fahrzeugbildschirmfaktoren und Eingabemodalitäten.

Host

Der Host ist die Backend-Komponente, die die von den APIs der Bibliothek angebotenen Funktionen implementiert, damit Ihre App im Auto ausgeführt werden kann. Die Aufgaben des Hosts reichen von der Entdeckung Ihrer App und der Verwaltung ihres Lebenszyklus bis hin zur Umwandlung Ihrer Modelle in Ansichten und der Benachrichtigung Ihrer App über Nutzerinteraktionen. Auf Mobilgeräten wird dieser Host von Android Auto implementiert. Unter Android Automotive OS wird dieser Host als System-App installiert.

Vorlageneinschränkungen

Verschiedene Vorlagen erzwingen Einschränkungen beim Inhalt ihrer Modelle. So ist beispielsweise bei Listenvorlagen die Anzahl der Elemente begrenzt, die dem Nutzer angezeigt werden können. Außerdem gibt es Einschränkungen bei der Verbindung von Vorlagen, um den Ablauf einer Aufgabe zu bilden. Die App kann beispielsweise nur bis zu fünf Vorlagen in den Bildschirmstapel schieben. Weitere Informationen finden Sie unter Vorlageneinschränkungen.

Screen

Screen ist eine von der Bibliothek bereitgestellte Klasse, die von Apps implementiert wird, um die Benutzeroberfläche zu verwalten, die dem Nutzer angezeigt wird. Ein Screen hat einen Lebenszyklus und stellt den Mechanismus für die Anwendung bereit, die Vorlage zu senden, wenn der Bildschirm sichtbar ist. Screen-Instanzen können auch per Push-Funktion in einen oder aus einem Screen-Stack übertragen werden. Dadurch wird sichergestellt, dass sie den Ablaufbeschränkungen der Vorlage entsprechen.

CarAppService

CarAppService ist eine abstrakte Service-Klasse, die von Ihrer Anwendung implementiert und exportiert werden muss, damit sie vom Host erkannt und verwaltet werden kann. Der CarAppService Ihrer App ist dafür verantwortlich, mithilfe von createHostValidator zu prüfen, ob eine Hostverbindung vertrauenswürdig ist, und anschließend mithilfe von onCreateSession Session-Instanzen für jede Verbindung bereitzustellen.

Session

Session ist eine abstrakte Klasse, die Ihre App implementieren und mit CarAppService.onCreateSession zurückgeben muss. Sie dient als Einstiegspunkt für die Anzeige von Informationen auf dem Autodisplay. Sie haben einen Lebenszyklus, der den aktuellen Status Ihrer App auf dem Autodisplay angibt, z. B. wann sie sichtbar oder ausgeblendet ist.

Wenn eine Session gestartet wird, z. B. beim ersten Starten der App, fordert der Host die Anzeige der ersten Screen mit der Methode onCreateScreen an.

Auto-App-Bibliothek installieren

Eine Anleitung zum Hinzufügen der Bibliothek zu Ihrer App finden Sie auf der Releaseseite der Jetpack-Bibliothek.

Manifestdateien Ihrer App konfigurieren

Bevor du die Auto-App erstellen kannst, musst du die Manifestdateien der App so konfigurieren.

CarAppService deklarieren

Der Host stellt über deine CarAppService-Implementierung eine Verbindung zu deiner App her. Sie deklarieren diesen Dienst in Ihrem Manifest, damit der Host Ihre App finden und eine Verbindung herstellen kann.

Außerdem müssen Sie die Kategorie Ihrer App im Element <category> des Intent-Filters Ihrer App angeben. Die für dieses Element zulässigen Werte finden Sie in der Liste der unterstützten App-Kategorien.

Das folgende Code-Snippet zeigt, wie du in deinem Manifest einen Auto-App-Dienst für eine POI-App deklarieren kannst:

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService"/>
        <category android:name="androidx.car.app.category.POI"/>
      </intent-filter>
    </service>

    ...
<application>

Unterstützte App-Kategorien

Gib die Kategorie deiner App an, indem du einen oder mehrere der folgenden Kategoriewerte im Intent-Filter hinzufügst, wenn du CarAppService wie im vorherigen Abschnitt beschrieben deklarierst:

• androidx.car.app.category.NAVIGATION: Eine App, die detaillierte Wegbeschreibungen bietet. Weitere Informationen zu dieser Kategorie finden Sie unter Navigations-Apps für Autos entwickeln.
• androidx.car.app.category.POI: eine App, die Funktionen zum Auffinden von POIs wie Parkplätzen, Ladestationen und Tankstellen bietet Weitere Informationen zu dieser Kategorie finden Sie unter Apps mit POIs für Autos entwickeln.
• androidx.car.app.category.IOT: Eine App, mit der Nutzer im Auto relevante Aktionen auf verbundenen Geräten ausführen können. Weitere Informationen zu dieser Kategorie finden Sie unter Internet of Things-Apps für Autos entwickeln.

Unter Qualität von Android-Apps für Autos findest du detaillierte Beschreibungen der einzelnen Kategorien und Kriterien für zugehörige Apps.

App-Name und -Symbol angeben

Sie müssen einen App-Namen und ein Symbol angeben, mit dem der Host Ihre App in der System-UI darstellen kann.

Sie können den App-Namen und das App-Symbol, das für Ihre App verwendet wird, mit den Attributen label und icon Ihres CarAppService angeben:

...
<service
   android:name=".MyCarAppService"
   android:exported="true"
   android:label="@string/my_app_name"
   android:icon="@drawable/my_app_icon">
   ...
</service>
...

Wenn das Label oder Symbol nicht im Element <service> deklariert ist, verwendet der Host die für das Element <application> angegebenen Werte.

Benutzerdefiniertes Design festlegen

Wenn Sie ein benutzerdefiniertes Design für Ihre Auto-App festlegen möchten, fügen Sie Ihrer Manifestdatei ein <meta-data>-Element hinzu. Gehen Sie dazu so vor:

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

Deklarieren Sie dann Ihre Stilressource, um die folgenden Attribute für das benutzerdefinierte Design Ihrer Auto-App festzulegen:

<resources>
  <style name="MyCarAppTheme">
    <item name="carColorPrimary">@layout/my_primary_car_color</item>
    <item name="carColorPrimaryDark">@layout/my_primary_dark_car_color</item>
    <item name="carColorSecondary">@layout/my_secondary_car_color</item>
    <item name="carColorSecondaryDark">@layout/my_secondary_dark_car_color</item>
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

Car App API-Level

In der Car App Library sind eigene API-Ebenen definiert, damit du weißt, welche Bibliotheksfunktionen vom Vorlagenhost für ein Fahrzeug unterstützt werden. Verwenden Sie die Methode getCarAppApiLevel(), um die höchste Car App API-Ebene abzurufen, die von einem Host unterstützt wird.

Deklarieren Sie in der Datei AndroidManifest.xml die von Ihrer App unterstützte Mindest-Car App API-Ebene:

<manifest ...>
    <application ...>
        <meta-data
            android:name="androidx.car.app.minCarApiLevel"
            android:value="1"/>
    </application>
</manifest>

Weitere Informationen zur Beibehaltung der Abwärtskompatibilität und zum Deklarieren der Mindest-API-Version, die für die Verwendung eines Features erforderlich ist, finden Sie in der Dokumentation für die Anmerkung RequiresCarApi. Eine Definition der API-Ebene, die für die Verwendung einer bestimmten Funktion der Auto-App-Bibliothek erforderlich ist, finden Sie in der Referenzdokumentation für CarAppApiLevels.

CarAppService und Sitzung erstellen

Ihre Anwendung muss die CarAppService-Klasse erweitern und ihre onCreateSession-Methode implementieren, die eine Session-Instanz zurückgibt, die der aktuellen Verbindung zum Host entspricht:

class HelloWorldService : CarAppService() {
    ...
    override fun onCreateSession(): Session {
        return HelloWorldSession()
    }
    ...
}

public final class HelloWorldService extends CarAppService {
    ...
    @Override
    @NonNull
    public Session onCreateSession() {
        return new HelloWorldSession();
    }
    ...
}

Die Instanz Session ist dafür verantwortlich, die Instanz Screen für den ersten Start der Anwendung zurückzugeben:

class HelloWorldSession : Session() {
    ...
    override fun onCreateScreen(intent: Intent): Screen {
        return HelloWorldScreen(carContext)
    }
    ...
}

public final class HelloWorldSession extends Session {
    ...
    @Override
    @NonNull
    public Screen onCreateScreen(@NonNull Intent intent) {
        return new HelloWorldScreen(getCarContext());
    }
    ...
}

Wenn Ihre Auto-App von einem Bildschirm aus gestartet werden muss, der nicht der Start- oder Landingpage Ihrer App entspricht, z. B. bei der Verarbeitung von Deeplinks, können Sie mit ScreenManager.push einen Backstack mit Bildschirmen vorbereiten, bevor Sie von onCreateScreen zurückkehren. Mit Pre-Seeding können Nutzer vom ersten Bildschirm, der in Ihrer App angezeigt wird, zu vorherigen Bildschirmen zurückkehren.

Startbildschirm erstellen

Zum Erstellen der von Ihrer App angezeigten Bildschirme definieren Sie Klassen, die die Klasse Screen erweitern, und implementieren ihre Methode onGetTemplate, die die Template-Instanz zurückgibt, die den Status der UI darstellt, die auf dem Autodisplay angezeigt werden soll.

Das folgende Snippet zeigt, wie eine Screen deklariert wird, die mit einer PaneTemplate-Vorlage einen einfachen String „Hallo Welt!“ anzeigt:

class HelloWorldScreen(carContext: CarContext) : Screen(carContext) {
    override fun onGetTemplate(): Template {
        val row = Row.Builder().setTitle("Hello world!").build()
        val pane = Pane.Builder().addRow(row).build()
        return PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build()
    }
}

public class HelloWorldScreen extends Screen {
    @NonNull
    @Override
    public Template onGetTemplate() {
        Row row = new Row.Builder().setTitle("Hello world!").build();
        Pane pane = new Pane.Builder().addRow(row).build();
        return new PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build();
    }
}

Die Klasse „CarContext“

Die Klasse CarContext ist eine ContextWrapper-Unterklasse, auf die Ihre Session- und Screen-Instanzen zugreifen können. Sie bietet Zugriff auf Autodienste wie ScreenManager zum Verwalten des Bildschirmstapels, AppManager für allgemeine appbezogene Funktionen wie den Zugriff auf das Surface-Objekt zum Zeichnen von Karten und NavigationManager, die von Apps für die Schritt-für-Schritt-Navigation verwendet wird, um Navigationsmetadaten und andere navigationsbezogene Ereignisse mit dem Host zu kommunizieren.

Eine umfassende Liste der Bibliotheksfunktionen, die für Navigations-Apps verfügbar sind, finden Sie unter Auf Navigationsvorlagen zugreifen.

CarContext bietet auch andere Funktionen, z. B. das Laden von Zeichnen-Ressourcen über die Konfiguration vom Autodisplay, das Starten einer App im Auto über Intents und das Signalisieren, ob die Karte Ihrer App im dunklen Design angezeigt werden soll.

Bildschirmnavigation implementieren

Apps enthalten häufig eine Reihe verschiedener Bildschirme, die jeweils unterschiedliche Vorlagen verwenden, durch die sich Nutzer bewegen können, während sie mit der auf dem Bildschirm angezeigten Benutzeroberfläche interagieren.

Die Klasse ScreenManager bietet einen Bildschirmstapel, mit dem Sie Bildschirme einblenden können, die automatisch eingeblendet werden, wenn der Nutzer auf dem Bildschirm im Auto eine Schaltfläche „Zurück“ auswählt oder die in einigen Autos verfügbare Hardware-Schaltfläche „Zurück“ verwendet.

Im folgenden Snippet wird gezeigt, wie einer Nachrichtenvorlage eine Rückwärtsaktion sowie eine Aktion hinzugefügt wird, die einen neuen Bildschirm anzeigt, wenn sie vom Nutzer ausgewählt wird:

val template = MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener { screenManager.push(NextScreen(carContext)) }
            .build())
    .build()

MessageTemplate template = new MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        new Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener(
                () -> getScreenManager().push(new NextScreen(getCarContext())))
            .build())
    .build();

Das Action.BACK-Objekt ist ein standardmäßiges Action, das automatisch ScreenManager.pop aufruft. Dieses Verhalten kann mit der OnBackPressedDispatcher-Instanz überschrieben werden, die über die CarContext verfügbar ist.

Damit die App während der Fahrt sicher verwendet werden kann, darf der Bildschirmstapel maximal fünf Bildschirme umfassen. Weitere Informationen finden Sie im Abschnitt Einschränkungen für Vorlagen.

Inhalt einer Vorlage aktualisieren

Ihre App kann durch Aufrufen der Methode Screen.invalidate anfordern, dass der Inhalt einer Screen ungültig wird. Der Host ruft anschließend die Methode Screen.onGetTemplate Ihrer App auf, um die Vorlage mit den neuen Inhalten abzurufen.

Wenn Sie eine Screen aktualisieren, ist es wichtig, die spezifischen Inhalte in der Vorlage zu kennen, die aktualisiert werden können, damit der Host die neue Vorlage nicht auf das Vorlagenkontingent anrechnet. Weitere Informationen finden Sie im Abschnitt Vorlageneinschränkungen.

Wir empfehlen, Ihre Bildschirme so zu strukturieren, dass eine Eins-zu-Eins-Zuordnung zwischen einer Screen und der Art der Vorlage besteht, die über die onGetTemplate-Implementierung zurückgegeben wird.

Karten zeichnen

Navigations- und POI-Apps, die die folgenden Vorlagen verwenden, können Karten zeichnen, indem sie auf eine Surface zugreifen:

Oberflächeberechtigung deklarieren

Zusätzlich zu der Berechtigung, die für die von Ihrer App verwendete Vorlage erforderlich ist, muss Ihre App die Berechtigung androidx.car.app.ACCESS_SURFACE in der Datei AndroidManifest.xml angeben, um auf die Oberfläche zuzugreifen:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
  ...
</manifest>

Auf die Oberfläche zugreifen

Wenn Sie auf die vom Host bereitgestellte Surface zugreifen möchten, müssen Sie eine SurfaceCallback implementieren und diese Implementierung dem AppManager-Autodienst zur Verfügung stellen. Der aktuelle Surface wird über den Parameter SurfaceContainer der Callbacks onSurfaceAvailable() und onSurfaceDestroyed() an deinen SurfaceCallback übergeben.

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

Sichtbarer Bereich der Oberfläche

Der Host kann Elemente der Benutzeroberfläche für die Vorlagen auf der Karte zeichnen. Durch Aufrufen der Methode SurfaceCallback.onVisibleAreaChanged sendet der Host den Bereich der Oberfläche, der garantiert nicht verdeckt und für den Nutzer vollständig sichtbar ist. Außerdem ruft der Host die Methode SurfaceCallback.onStableAreaChanged mit dem kleinsten Rechteck auf, um die Anzahl der Änderungen zu minimieren. Dieses Rechteck ist immer auf der Grundlage der aktuellen Vorlage sichtbar.

Wenn in einer Navigations-App beispielsweise die NavigationTemplate mit einem Aktionsstreifen oben verwendet wird, kann sich der Aktionsstreifen ausblenden, wenn der Nutzer eine Weile nicht mit dem Display interagiert hat, um mehr Platz für die Karte zu schaffen. In diesem Fall gibt es einen Callback von onStableAreaChanged und onVisibleAreaChanged mit demselben Rechteck. Wenn die Aktionsleiste ausgeblendet ist, wird nur onVisibleAreaChanged mit dem größeren Bereich aufgerufen. Wenn der Nutzer mit dem Bildschirm interagiert, wird wieder nur onVisibleAreaChanged mit dem ersten Rechteck aufgerufen.

Dunkles Design unterstützen

Apps müssen ihre Karte mit den richtigen dunklen Farben auf die Surface-Instanz zeichnen, wenn der Host bestimmte Bedingungen bevorzugt. Eine Beschreibung hierzu finden Sie unter Qualität von Android-Apps für Autos.

Mit der Methode CarContext.isDarkMode können Sie festlegen, ob eine dunkle Karte gezeichnet werden soll. Sobald sich der Status des dunklen Designs ändert, erhalten Sie einen Anruf an Session.onCarConfigurationChanged.

Nutzern die Interaktion mit Ihrer Karte ermöglichen

Mit den folgenden Vorlagen können Sie Nutzern die Interaktion mit den von Ihnen erstellten Karten ermöglichen, z. B. durch Zoomen und Schwenken, um verschiedene Teile einer Karte zu sehen.

Callbacks für Interaktivität implementieren

Die SurfaceCallback-Schnittstelle bietet mehrere Callback-Methoden, mit denen Sie Karten, die mit den Vorlagen im vorherigen Abschnitt erstellt wurden, interaktiver gestalten können:

Kartenaktionsleiste hinzufügen

Diese Vorlagen können einen Kartenaktionsstreifen für kartenbezogene Aktionen wie Heranzoomen und Herauszoomen, Neuausrichten, Einblenden eines Kompasses und andere von Ihnen ausgewählte Aktionen enthalten. Die Kartenaktionsleiste kann bis zu vier Schaltflächen enthalten, die nur Symbolen enthalten und die aktualisiert werden können, ohne die Aufgabentiefe zu beeinträchtigen. Im Ruhezustand wird sie ausgeblendet und im aktiven Zustand wieder angezeigt.

Wenn Sie Interaktivitäts-Callbacks für Karten erhalten möchten, müssen Sie dem Kartenaktionsstreifen eine Schaltfläche vom Typ Action.PAN hinzufügen. Wenn der Nutzer die Schwenktaste drückt, wechselt der Host in den Schwenkmodus, wie im folgenden Abschnitt beschrieben.

Wenn Ihre App die Schaltfläche Action.PAN im Aktionsstreifen der Karte weglässt, erhält sie keine Nutzereingaben über die SurfaceCallback-Methoden und der Host beendet den zuvor aktivierten Schwenkmodus.

Auf einem Touchscreen wird die Schaltfläche zum Schwenken nicht angezeigt.

Schwenkmodus

Im Schwenkmodus übersetzt der Vorlagenhost die Nutzereingaben von Eingabegeräten ohne Touchbedienung, z. B. Drehregler und Touchpads, in die entsprechenden SurfaceCallback-Methoden. Mit der Methode setPanModeListener in der NavigationTemplate.Builder auf die Nutzeraktion zum Aktivieren oder Deaktivieren des Schwenkmodus reagieren Der Host kann andere UI-Komponenten in der Vorlage ausblenden, während sich der Nutzer im Schwenkmodus befindet.

Mit dem Nutzer interagieren

Ihre App kann mit dem Nutzer über Muster interagieren, die denen einer mobilen App ähneln.

Nutzereingaben verarbeiten

Ihre App kann auf Nutzereingaben reagieren, indem die entsprechenden Listener an die Modelle übergeben werden, die sie unterstützen. Das folgende Snippet zeigt, wie Sie ein Action-Modell erstellen, das eine OnClickListener festlegt, die eine vom Code Ihrer App definierte Methode zurückruft:

val action = Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(::onClickNavigate)
    .build()

Action action = new Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(this::onClickNavigate)
    .build();

Die Methode onClickNavigate kann dann die Standard-Navigationsauto-App mithilfe der Methode CarContext.startCarApp starten:

private fun onClickNavigate() {
    val intent = Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address))
    carContext.startCarApp(intent)
}

private void onClickNavigate() {
    Intent intent = new Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address));
    getCarContext().startCarApp(intent);
}

Weitere Informationen zum Starten von Apps, einschließlich des Formats des Intents ACTION_NAVIGATE, finden Sie im Abschnitt Auto-App mit einem Intent starten.

Einige Aktionen, bei denen der Nutzer aufgefordert werden muss, die Interaktion auf seinem Mobilgerät fortzusetzen, sind nur zulässig, wenn das Auto geparkt ist. Sie können diese Aktionen mit dem Symbol ParkedOnlyOnClickListener implementieren. Wenn das Auto nicht geparkt ist, wird dem Nutzer angezeigt, dass die Aktion in diesem Fall nicht zulässig ist. Wenn das Auto geparkt ist, wird der Code normal ausgeführt. Im folgenden Snippet wird gezeigt, wie Sie mit ParkedOnlyOnClickListener einen Einstellungsbildschirm auf dem Mobilgerät öffnen:

val row = Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(::openSettingsOnPhone))
    .build()

Row row = new Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(this::openSettingsOnPhone))
    .build();

Benachrichtigungen anzeigen

An das Mobilgerät gesendete Benachrichtigungen werden nur dann auf dem Autodisplay angezeigt, wenn sie mit einem CarAppExtender erweitert werden. Einige Benachrichtigungsattribute wie Inhaltstitel, Text, Symbol und Aktionen können in der CarAppExtender festgelegt werden, um die Attribute der Benachrichtigung zu überschreiben, wenn sie auf dem Autodisplay angezeigt werden.

Im folgenden Snippet wird gezeigt, wie eine Benachrichtigung an das Autodisplay gesendet wird, die einen anderen Titel als der auf dem Mobilgerät angezeigte hat:

val notification = NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build()

Notification notification = new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        new CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build();

Benachrichtigungen können sich auf die folgenden Bereiche der Benutzeroberfläche auswirken:

• Dem Nutzer wird möglicherweise eine Vorschau-Benachrichtigung angezeigt.
• Es kann ein Eintrag im Benachrichtigungscenter hinzugefügt werden, optional mit einem Symbol, das in der Leiste angezeigt wird.
• Bei Navigations-Apps kann die Benachrichtigung im Eisenbahn-Widget angezeigt werden, wie unter Detaillierte Benachrichtigungen beschrieben.

Sie können festlegen, wie die Benachrichtigungen Ihrer App auf diese Elemente der Benutzeroberfläche wirken sollen. Verwenden Sie dazu die Priorität der Benachrichtigung, wie in der CarAppExtender-Dokumentation beschrieben.

Wenn NotificationCompat.Builder.setOnlyAlertOnce mit dem Wert true aufgerufen wird, wird eine Benachrichtigung mit hoher Priorität nur einmal als HUN angezeigt.

Weitere Informationen zum Entwerfen der Benachrichtigungen Ihrer Auto-App finden Sie im Leitfaden „Google Design for Driving“ unter Benachrichtigungen.

Toasts anzeigen

In Ihrer App kann mit CarToast ein Toast angezeigt werden, wie in diesem Snippet gezeigt:

CarToast.makeText(carContext, "Hello!", CarToast.LENGTH_SHORT).show()

CarToast.makeText(getCarContext(), "Hello!", CarToast.LENGTH_SHORT).show();

Berechtigungen anfordern

Wenn Ihre App Zugriff auf eingeschränkte Daten oder Aktionen benötigt, z. B. auf den Standort, gelten die Standardregeln für Android-Berechtigungen. Mit der Methode CarContext.requestPermissions() können Sie eine Berechtigung anfordern.

Die Verwendung von CarContext.requestPermissions() hat im Vergleich zur Verwendung von Standard-Android-APIs den Vorteil, dass du zum Erstellen des Berechtigungsdialogfelds kein eigenes Activity starten musst. Außerdem kannst du für Android Auto und Android Automotive OS denselben Code verwenden, anstatt plattformabhängige Abläufe erstellen zu müssen.

Stil des Berechtigungsdialogfelds in Android Auto festlegen

Bei Android Auto wird das Berechtigungsdialogfeld für den Nutzer auf dem Smartphone angezeigt. Standardmäßig gibt es keinen Hintergrund hinter dem Dialogfeld. Wenn Sie einen benutzerdefinierten Hintergrund festlegen möchten, deklarieren Sie in Ihrer AndroidManifest.xml-Datei ein Design für die Auto-App und legen Sie das carPermissionActivityLayout-Attribut für das Design der Auto-App fest.

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

Legen Sie dann das carPermissionActivityLayout-Attribut für das Design Ihrer Auto-App fest:

<resources>
  <style name="MyCarAppTheme">
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

Eine Auto-App mit einem Intent starten

Sie können die Methode CarContext.startCarApp aufrufen, um eine der folgenden Aktionen auszuführen:

• Öffne die Telefon App, um einen Anruf zu tätigen.
• Starten Sie die detaillierte Routenführung zu einem Ziel mit der Standard-Navigations-App für Autos.
• Starten Sie Ihre eigene App mit einer Intent-Aktion.

Im folgenden Beispiel wird gezeigt, wie Sie eine Benachrichtigung mit einer Aktion erstellen, die Ihre App mit einem Bildschirm öffnet, auf dem die Details einer Parkreservierung angezeigt werden. Sie erweitern die Benachrichtigungsinstanz um einen Inhalts-Intent, der einen PendingIntent enthält, der einen expliziten Intent für die Aktion Ihrer App umschließt:

val notification = notificationBuilder
    ...
    .extend(
        CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(ComponentName(context, MyNotificationReceiver::class.java)),
                    0))
            .build())

Notification notification = notificationBuilder
    ...
    .extend(
        new CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    new Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(new ComponentName(context, MyNotificationReceiver.class)),
                    0))
            .build());

Ihre App muss auch eine BroadcastReceiver deklarieren, die aufgerufen wird, um die Absicht zu verarbeiten, wenn der Nutzer die Aktion in der Benachrichtigungsoberfläche auswählt und CarContext.startCarApp mit einer Absicht aufruft, die den Daten-URI enthält:

class MyNotificationReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val intentAction = intent.action
        if (ACTION_VIEW_PARKING_RESERVATION == intentAction) {
            CarContext.startCarApp(
                intent,
                Intent(Intent.ACTION_VIEW)
                    .setComponent(ComponentName(context, MyCarAppService::class.java))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)))
        }
    }
}

public class MyNotificationReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        String intentAction = intent.getAction();
        if (ACTION_VIEW_PARKING_RESERVATION.equals(intentAction)) {
            CarContext.startCarApp(
                intent,
                new Intent(Intent.ACTION_VIEW)
                    .setComponent(new ComponentName(context, MyCarAppService.class))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)));
        }
    }
}

Schließlich verarbeitet die Session.onNewIntent-Methode in Ihrer App diesen Intent, indem der Bildschirm für die Parkplatzreservierung in den Stapel geschoben wird, falls er nicht bereits oben ist:

override fun onNewIntent(intent: Intent) {
    val screenManager = carContext.getCarService(ScreenManager::class.java)
    val uri = intent.data
    if (uri != null
        && MY_URI_SCHEME == uri.scheme
        && MY_URI_HOST == uri.schemeSpecificPart
        && ACTION_VIEW_PARKING_RESERVATION == uri.fragment
    ) {
        val top = screenManager.top
        if (top !is ParkingReservationScreen) {
            screenManager.push(ParkingReservationScreen(carContext))
        }
    }
}

@Override
public void onNewIntent(@NonNull Intent intent) {
    ScreenManager screenManager = getCarContext().getCarService(ScreenManager.class);
    Uri uri = intent.getData();
    if (uri != null
        && MY_URI_SCHEME.equals(uri.getScheme())
        && MY_URI_HOST.equals(uri.getSchemeSpecificPart())
        && ACTION_VIEW_PARKING_RESERVATION.equals(uri.getFragment())
    ) {
        Screen top = screenManager.getTop();
        if (!(top instanceof ParkingReservationScreen)) {
            screenManager.push(new ParkingReservationScreen(getCarContext()));
        }
    }
}

Weitere Informationen zum Umgang mit Benachrichtigungen der Auto-App finden Sie unter Benachrichtigungen anzeigen.

Vorlageneinschränkungen

Der Host begrenzt die Anzahl der Vorlagen, die für eine bestimmte Aufgabe angezeigt werden, auf maximal fünf. Die letzte Vorlage muss einen der folgenden Typen haben:

• NavigationTemplate
• PaneTemplate
• MessageTemplate

Dieses Limit gilt für die Anzahl der Vorlagen und nicht für die Anzahl der Screen-Instanzen im Stack. Wenn eine Anwendung beispielsweise in Bildschirm A zwei Vorlagen sendet und dann Bildschirm B überträgt, können jetzt drei weitere Vorlagen gesendet werden. Wenn jeder Bildschirm so strukturiert ist, dass eine einzelne Vorlage gesendet wird, kann die App fünf Bildschirminstanzen auf den ScreenManager-Stack schieben.

Für diese Einschränkungen gibt es Sonderfälle: Aktualisierungs-, Zurück- und Rücksetzungsvorgänge für Vorlagen.

Vorlage wird aktualisiert

Bestimmte Inhaltsaktualisierungen werden nicht auf das Vorlagenlimit angerechnet. Allgemein gilt: Wenn eine Anwendung eine neue Vorlage sendet, die vom gleichen Typ ist und denselben Hauptinhalt wie die vorherige Vorlage enthält, wird die neue Vorlage nicht auf das Kontingent angerechnet. Beispielsweise wird die Aktualisierung des Umschaltstatus einer Zeile in einer ListTemplate nicht auf das Kontingent angerechnet. In der Dokumentation der einzelnen Vorlagen erfahren Sie, welche Arten von Inhaltsaktualisierungen als Aktualisierung betrachtet werden können.

Back-Operationen

Um Unterflüsse innerhalb einer Aufgabe zu aktivieren, erkennt der Host, wenn eine App eine Screen aus dem ScreenManager-Stack herauspoppt, und aktualisiert das verbleibende Kontingent basierend auf der Anzahl der Vorlagen, um die die App zurückgeht.

Wenn die App beispielsweise zwei Vorlagen sendet, während sie sich auf Bildschirm A befindet, dann Bildschirm B anzeigt und zwei weitere Vorlagen sendet, hat die App noch ein Kontingent übrig. Wenn die App dann wieder zu Bildschirm A zurückkehrt, setzt der Host das Kontingent auf drei zurück, da die App um zwei Vorlagen zurückgegangen ist.

Wenn eine App zu einem Bildschirm zurückkehrt, muss sie eine Vorlage desselben Typs senden wie die, die zuletzt von diesem Bildschirm gesendet wurde. Anderen Vorlagentypen können nicht gesendet werden. Solange der Typ jedoch während eines Rückschritts gleich bleibt, kann der Inhalt der Vorlage in einer App frei geändert werden, ohne dass sich das auf das Kontingent auswirkt.

Vorgänge zurücksetzen

Bestimmte Vorlagen haben eine spezielle Semantik, die das Ende einer Aufgabe signalisiert. Die Ansicht NavigationTemplate ist beispielsweise eine Ansicht, die voraussichtlich auf dem Bildschirm verbleibt und mit neuen detaillierten Anweisungen für den Nutzer aktualisiert wird. Wenn er eine dieser Vorlagen erreicht, setzt der Host das Vorlagenkontingent zurück und behandelt die Vorlage so, als wäre sie der erste Schritt einer neuen Aufgabe. So kann die App eine neue Aufgabe starten. In der Dokumentation der einzelnen Vorlagen können Sie nachlesen, welche Vorlagen das Zurücksetzen auf dem Host auslösen.

Wenn der Host eine Intent zum Starten der App über eine Benachrichtigungsaktion oder über den Launcher erhält, wird das Kontingent ebenfalls zurückgesetzt. Mit diesem Mechanismus kann eine App einen neuen Aufgabenablauf über Benachrichtigungen starten. Das gilt auch, wenn eine App bereits verknüpft und im Vordergrund ist.

Weitere Informationen dazu, wie Sie die Benachrichtigungen Ihrer App auf dem Autodisplay anzeigen lassen, finden Sie im Abschnitt Benachrichtigungen anzeigen. Informationen zum Starten deiner App über eine Benachrichtigungsaktion findest du im Abschnitt Auto-App mit einem Intent starten.

Connection API

Sie können mithilfe der CarConnection API Verbindungsinformationen zur Laufzeit abrufen, um festzustellen, ob Ihre App unter Android Auto oder Android Automotive OS ausgeführt wird.

Initialisieren Sie beispielsweise im Session Ihrer Auto-App einen CarConnection und abonnieren Sie LiveData-Updates:

CarConnection(carContext).type.observe(this, ::onConnectionStateUpdated)

new CarConnection(getCarContext()).getType().observe(this, this::onConnectionStateUpdated);

Im Beobachter können Sie dann auf Änderungen des Verbindungsstatus reagieren:

fun onConnectionStateUpdated(connectionState: Int) {
  val message = when(connectionState) {
    CarConnection.CONNECTION_TYPE_NOT_CONNECTED -> "Not connected to a head unit"
    CarConnection.CONNECTION_TYPE_NATIVE -> "Connected to Android Automotive OS"
    CarConnection.CONNECTION_TYPE_PROJECTION -> "Connected to Android Auto"
    else -> "Unknown car connection type"
  }
  CarToast.makeText(carContext, message, CarToast.LENGTH_SHORT).show()
}

private void onConnectionStateUpdated(int connectionState) {
  String message;
  switch(connectionState) {
    case CarConnection.CONNECTION_TYPE_NOT_CONNECTED:
      message = "Not connected to a head unit";
      break;
    case CarConnection.CONNECTION_TYPE_NATIVE:
      message = "Connected to Android Automotive OS";
      break;
    case CarConnection.CONNECTION_TYPE_PROJECTION:
      message = "Connected to Android Auto";
      break;
    default:
      message = "Unknown car connection type";
      break;
  }
  CarToast.makeText(getCarContext(), message, CarToast.LENGTH_SHORT).show();
}

Constraints API

Je nach Fahrzeug können dem Nutzer jeweils eine unterschiedliche Anzahl von Item-Instanzen angezeigt werden. Mit ConstraintManager können Sie das Inhaltslimit zur Laufzeit prüfen und die entsprechende Anzahl von Elementen in Ihren Vorlagen festlegen.

Fordern Sie zuerst ein ConstraintManager von CarContext an:

val manager = carContext.getCarService(ConstraintManager::class.java)

ConstraintManager manager = getCarContext().getCarService(ConstraintManager.class);

Anschließend können Sie das abgerufene ConstraintManager-Objekt im Hinblick auf die entsprechende Inhaltsbeschränkung abfragen. Wenn Sie beispielsweise die Anzahl der Elemente abrufen möchten, die in einem Raster angezeigt werden können, rufen Sie getContentLimit mit CONTENT_LIMIT_TYPE_GRID auf:

val gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID)

int gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID);

Anmeldevorgang hinzufügen

Wenn Ihre App eine Anmeldung für Nutzer bietet, können Sie Vorlagen wie SignInTemplate und LongMessageTemplate mit der Car App API ab Level 2 verwenden, um die Anmeldung in Ihrer App auf dem Infotainmentsystem des Autos zu verwalten.

Um eine SignInTemplate zu erstellen, müssen Sie eine SignInMethod definieren. Die Car App Library unterstützt derzeit die folgenden Anmeldemethoden:

• InputSignInMethod für die Anmeldung mit Nutzernamen und Passwort.
• PinSignInMethod für die PIN-Anmeldung, bei der der Nutzer sein Konto über sein Smartphone mit einer PIN verknüpft, die auf dem Infotainmentsystem angezeigt wird.
• ProviderSignInMethod für die Anmeldung über einen Anbieter, z. B. Google Log-in und One Tap.
• QRCodeSignInMethod für die QR-Code-Anmeldung, bei der der Nutzer einen QR-Code scannt, um sich auf seinem Smartphone anzumelden. Diese Option ist für Car-API-Level 4 und höher verfügbar.

Wenn Sie beispielsweise eine Vorlage implementieren möchten, mit der das Passwort des Nutzers erfasst wird, müssen Sie zuerst eine InputCallback erstellen, um die Nutzereingabe zu verarbeiten und zu validieren:

val callback = object : InputCallback {
    override fun onInputSubmitted(text: String) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    override fun onInputTextChanged(text: String) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
}

InputCallback callback = new InputCallback() {
    @Override
    public void onInputSubmitted(@NonNull String text) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    @Override
    public void onInputTextChanged(@NonNull String text) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
};

Für die InputSignInMethod Builder ist ein InputCallback erforderlich.

val passwordInput = InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build()

InputSignInMethod passwordInput = new InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build();

Verwenden Sie abschließend Ihre neue InputSignInMethod, um eine SignInTemplate zu erstellen.

SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build()

new SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build();

AccountManager verwenden

Android Automotive OS-Apps mit Authentifizierung müssen aus den folgenden Gründen AccountManager verwenden:

• Verbesserte Nutzerfreundlichkeit und einfachere Kontoverwaltung: Nutzer können alle ihre Konten über das Kontomenü in den Systemeinstellungen ganz einfach verwalten, einschließlich Anmeldung und Abmeldung.
• Gastzugriff: Da Autos gemeinsam genutzte Geräte sind, können OEMs im Fahrzeug einen Gastzugriff aktivieren, bei dem keine Konten hinzugefügt werden können.

Textstringvarianten hinzufügen

Je nach Größe des Autodisplays können unterschiedliche Textmengen angezeigt werden. Ab der Car App API-Ebene 2 können Sie mehrere Varianten eines Textstrings angeben, damit er optimal auf dem Bildschirm angezeigt wird. Sie finden Textvarianten in Vorlagen und Komponenten, die ein CarText enthalten.

Mit der Methode CarText.Builder.addVariant() können Sie einem CarText Textstringvarianten hinzufügen:

val itemTitle = CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build()

CarText itemTitle = new CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build();

Sie können diese CarText dann beispielsweise als primären Text einer GridItem verwenden.

GridItem.Builder()
    .addTitle(itemTitle)
    ...
    .build()

new GridItem.Builder()
    .addTitle(itemTitle)
    ...
    build();

Fügen Sie die Strings in absteigender Reihenfolge hinzu, z. B. vom längsten zum kürzesten. Der Host wählt den String mit der richtigen Länge aus, je nachdem, wie viel Platz auf dem Autodisplay verfügbar ist.

In-Line-CarIcons für Zeilen hinzufügen

Mit CarIconSpan können Sie Symbole inline in den Text einfügen, um die visuelle Attraktivität Ihrer App zu erhöhen. Weitere Informationen zum Erstellen dieser Spans finden Sie in der Dokumentation zu CarIconSpan.create. Eine Übersicht über die Textformatierung mit Spans finden Sie unter Spantastic Text Styling with Spans (Spantastic Text-Styling mit Spans).

  
val rating = SpannableString("Rating: 4.5 stars")
rating.setSpan(
    CarIconSpan.create(
        // Create a CarIcon with an image of four and a half stars
        CarIcon.Builder(...).build(),
        // Align the CarIcon to the baseline of the text
        CarIconSpan.ALIGN_BASELINE
    ),
    // The start index of the span (index of the character '4')
    8,
    // The end index of the span (index of the last 's' in "stars")
    16,
    Spanned.SPAN_INCLUSIVE_INCLUSIVE
)

val row = Row.Builder()
    ...
    .addText(rating)
    .build()
  
  

  
SpannableString rating = new SpannableString("Rating: 4.5 stars");
rating.setSpan(
        CarIconSpan.create(
                // Create a CarIcon with an image of four and a half stars
                new CarIcon.Builder(...).build(),
                // Align the CarIcon to the baseline of the text
                CarIconSpan.ALIGN_BASELINE
        ),
        // The start index of the span (index of the character '4')
        8,
        // The end index of the span (index of the last 's' in "stars")
        16,
        Spanned.SPAN_INCLUSIVE_INCLUSIVE
);
Row row = new Row.Builder()
        ...
        .addText(rating)
        .build();
  
  

APIs für Autohardware

Ab Level 3 der Car App API enthält die Car App Library APIs, mit denen du auf Fahrzeugeigenschaften und Sensoren zugreifen kannst.

Voraussetzungen

Wenn Sie die APIs mit Android Auto verwenden möchten, fügen Sie der Datei build.gradle für Ihr Android Auto-Modul zuerst eine Abhängigkeit von androidx.car.app:app-projected hinzu. Füge für Android Automotive OS der Datei build.gradle für das Android Automotive OS-Modul eine Abhängigkeit von androidx.car.app:app-automotive hinzu.

Außerdem müssen Sie in Ihrer AndroidManifest.xml-Datei die relevanten Berechtigungen deklarieren, die zum Anfordern der gewünschten Fahrzeugdaten erforderlich sind. Beachten Sie, dass diese Berechtigungen auch Ihnen vom Nutzer erteilt werden müssen. Sie können denselben Code sowohl für Android Auto als auch für Android Automotive OS verwenden, anstatt platformabhängige Abläufe erstellen zu müssen. Die erforderlichen Berechtigungen unterscheiden sich jedoch.

CarInfo

In dieser Tabelle werden die Properties beschrieben, die von den CarInfo APIs zurückgegeben werden, und die Berechtigungen, die Sie anfordern müssen, um sie zu verwenden:

Um beispielsweise den verbleibenden Bereich abzurufen, instanziieren Sie ein CarInfo-Objekt und erstellen und registrieren Sie dann ein OnCarDataAvailableListener:

val carInfo = carContext.getCarService(CarHardwareManager::class.java).carInfo

val listener = OnCarDataAvailableListener<EnergyLevel> { data ->
    if (data.rangeRemainingMeters.status == CarValue.STATUS_SUCCESS) {
      val rangeRemaining = data.rangeRemainingMeters.value
    } else {
      // Handle error
    }
  }

carInfo.addEnergyLevelListener(carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener)

CarInfo carInfo = getCarContext().getCarService(CarHardwareManager.class).getCarInfo();

OnCarDataAvailableListener<EnergyLevel> listener = (data) -> {
  if(data.getRangeRemainingMeters().getStatus() == CarValue.STATUS_SUCCESS) {
    float rangeRemaining = data.getRangeRemainingMeters().getValue();
  } else {
    // Handle error
  }
};

carInfo.addEnergyLevelListener(getCarContext().getMainExecutor(), listener);
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener);

Gehen Sie nicht davon aus, dass die Daten des Fahrzeugs jederzeit verfügbar sind. Wenn Sie einen Fehler erhalten, prüfen Sie den Status des angeforderten Werts, um besser nachvollziehen zu können, warum die angeforderten Daten nicht abgerufen werden konnten. Die vollständige CarInfo-Klassendefinition finden Sie in der Referenzdokumentation.

CarSensors

Mit der Klasse CarSensors erhältst du Zugriff auf den Beschleunigungsmesser, das Gyroskop, den Kompass und die Standortdaten des Fahrzeugs. Die Verfügbarkeit dieser Werte hängt vom jeweiligen OEM ab. Das Format der Daten vom Beschleunigungsmesser, Gyroskop und Kompass entspricht dem der SensorManager API. So können Sie beispielsweise die Richtung des Fahrzeugs prüfen:

val carSensors = carContext.getCarService(CarHardwareManager::class.java).carSensors

val listener = OnCarDataAvailableListener<Compass> { data ->
    if (data.orientations.status == CarValue.STATUS_SUCCESS) {
      val orientation = data.orientations.value
    } else {
      // Data not available, handle error
    }
  }

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener)

CarSensors carSensors = getCarContext().getCarService(CarHardwareManager.class).getCarSensors();

OnCarDataAvailableListener<Compass> listener = (data) -> {
  if (data.getOrientations().getStatus() == CarValue.STATUS_SUCCESS) {
    List<Float> orientations = data.getOrientations().getValue();
  } else {
    // Data not available, handle error
  }
};

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, getCarContext().getMainExecutor(),
    listener);
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener);

Für den Zugriff auf Standortdaten aus dem Auto musst du außerdem die Berechtigung android.permission.ACCESS_FINE_LOCATION deklarieren und anfordern.

Testen

Informationen zum Simulieren von Sensordaten bei Tests in Android Auto finden Sie in den Abschnitten Sensoren und Sensorkonfiguration des Leitfadens für Desktop-Infotainmentsysteme. Informationen zum Simulieren von Sensordaten beim Testen unter Android Automotive OS finden Sie im Abschnitt Hardwarestatus emulieren der Anleitung zum Emulator für Android Automotive OS.

Die Lebenszyklen von CarAppService, Session und Screen

Die Klassen Session und Screen implementieren die Schnittstelle LifecycleOwner. Wenn der Nutzer mit der App interagiert, werden die Lebenszyklus-Callbacks Ihrer Session- und Screen-Objekte aufgerufen, wie in den folgenden Diagrammen dargestellt.

Lebenszyklen von CarAppService und Sitzung

Weitere Informationen finden Sie in der Dokumentation zur Methode Session.getLifecycle.

Der Lebenszyklus eines Bildschirms

Ausführliche Informationen finden Sie in der Dokumentation zur Methode Screen.getLifecycle.

Über das Mikrofon des Autos aufnehmen

Mit der CarAppService-API Ihrer App und der CarAudioRecord API können Sie Ihrer App Zugriff auf das Mikrofon des Autos des Nutzers gewähren. Nutzer müssen Ihrer App die Berechtigung zum Zugriff auf das Mikrofon des Autos erteilen. Ihre App kann die Eingaben der Nutzer in Ihrer App aufzeichnen und verarbeiten.

Berechtigung zur Aufzeichnung

Bevor Sie Audioaufnahmen starten, müssen Sie die Berechtigung zur Aufnahme in Ihrer AndroidManifest.xml angeben und den Nutzer bitten, sie zu gewähren.

<manifest ...>
   ...
   <uses-permission android:name="android.permission.RECORD_AUDIO" />
   ...
</manifest>

Sie müssen die Berechtigung zum Aufzeichnen während der Laufzeit anfordern. Im Abschnitt Berechtigungen anfordern finden Sie weitere Informationen dazu, wie Sie eine Berechtigung in Ihrer Auto-App anfordern.

Audio aufnehmen

Nachdem der Nutzer die Berechtigung zur Aufzeichnung erteilt hat, können Sie die Audioaufnahme starten und verarbeiten.

val carAudioRecord = CarAudioRecord.create(carContext)
        carAudioRecord.startRecording()

        val data = ByteArray(CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE)
        while(carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording()
 

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        carAudioRecord.startRecording();

        byte[] data = new byte[CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE];
        while (carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording();
 

Audiofokus

Wenn Sie über das Mikrofon des Autos aufnehmen möchten, müssen Sie zuerst den Audiofokus aktivieren, damit alle laufenden Medien angehalten werden. Wenn der Audiofokus verloren geht, beenden Sie die Aufnahme.

Hier ein Beispiel dafür, wie Sie den Audiofokus erhalten:

 
val carAudioRecord = CarAudioRecord.create(carContext)
        
        // Take audio focus so that user's media is not recorded
        val audioAttributes = AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
            // Use the most appropriate usage type for your use case
            .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
            .build()
        
        val audioFocusRequest =
            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                .setAudioAttributes(audioAttributes)
                .setOnAudioFocusChangeListener { state: Int ->
                    if (state == AudioManager.AUDIOFOCUS_LOSS) {
                        // Stop recording if audio focus is lost
                        carAudioRecord.stopRecording()
                    }
                }
                .build()
        
        if (carContext.getSystemService(AudioManager::class.java)
                .requestAudioFocus(audioFocusRequest)
            != AudioManager.AUDIOFOCUS_REQUEST_GRANTED
        ) {
            // Don't record if the focus isn't granted
            return
        }
        
        carAudioRecord.startRecording()
        // Process the audio and abandon the AudioFocusRequest when done

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        // Take audio focus so that user's media is not recorded
        AudioAttributes audioAttributes =
                new AudioAttributes.Builder()
                        .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                        // Use the most appropriate usage type for your use case
                        .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
                        .build();

        AudioFocusRequest audioFocusRequest =
                new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                        .setAudioAttributes(audioAttributes)
                        .setOnAudioFocusChangeListener(state -> {
                            if (state == AudioManager.AUDIOFOCUS_LOSS) {
                                // Stop recording if audio focus is lost
                                carAudioRecord.stopRecording();
                            }
                        })
                        .build();

        if (getCarContext().getSystemService(AudioManager.class).requestAudioFocus(audioFocusRequest)
                != AUDIOFOCUS_REQUEST_GRANTED) {
            // Don't record if the focus isn't granted
            return;
        }

        carAudioRecord.startRecording();
        // Process the audio and abandon the AudioFocusRequest when done
 

Testbibliothek

Die Testbibliothek von Android for Cars bietet Hilfsklassen, mit denen Sie das Verhalten Ihrer App in einer Testumgebung prüfen können. Mit SessionController können Sie beispielsweise eine Verbindung zum Host simulieren und prüfen, ob die richtigen Screen und Template erstellt und zurückgegeben werden.

Anwendungsbeispiele finden Sie unter Beispiele.

Problem mit der Android for Cars-App-Bibliothek melden

Wenn Sie ein Problem mit der Bibliothek feststellen, melden Sie es über den Google Issue Tracker. Achten Sie darauf, in der Vorlage für Probleme alle angeforderten Informationen anzugeben.

Neues Problem erstellen

Bevor du ein neues Problem meldest, prüfe bitte, ob es in den Versionshinweisen der Bibliothek aufgeführt oder in der Liste der Probleme aufgeführt ist. Sie können Ausgaben abonnieren und über diese abstimmen, indem Sie im Tracker auf den Stern für ein Problem klicken. Weitere Informationen finden Sie unter Probleme abonnieren.