Medien-App mit Vorlage erstellen

Auf Vorlagen basierende Media-Apps befinden sich in der Betaphase
Derzeit kann jeder, der möchte, Medien-Apps mit Vorlagen in den Tracks für interne und geschlossene Tests im Google Play Store veröffentlichen. Die Veröffentlichung in offenen Tracks und Produktions-Tracks wird zu einem späteren Zeitpunkt zugelassen.

Medien-Apps, die die Vorlagen der Car App Library verwenden, können das Durchsuchen und die Wiedergabe von Medien anpassen. Gleichzeitig wird sichergestellt, dass die Nutzung für Bildschirme im Auto optimiert ist und Ablenkungen während der Fahrt minimiert werden.

In diesem Leitfaden wird davon ausgegangen, dass Sie bereits eine Medien-App haben, die Audio auf einem Smartphone abspielt, und dass Ihre Medien-App der Architektur für Android-Medien-Apps entspricht. Mit der Car App Library können Sie die In-App-Oberfläche durch Vorlagen ersetzen, anstatt die Datenstruktur MediaBrowser aus Medien-Apps für Autos entwickeln zu verwenden. Sie müssen weiterhin einen MediaSession für die Wiedergabesteuerung und einen MediaBrowserService oder MediaLibraryService angeben, der für Empfehlungen und andere intelligente Funktionen verwendet wird.

Park-to-Drive-Funktionen sind jetzt in der Betaversion verfügbar
Medien-Apps mit Vorlage können jetzt für Android Automotive OS optimiert werden, sodass sie sowohl im geparkten Zustand als auch während der Fahrt genutzt werden können. So kann Ihre App bei geparktem Fahrzeug adaptive native Aktivitäten hinzufügen und nahtlos zur vorlagenbasierten Medienwiedergabe wechseln, wenn das Fahrzeug fährt.

Manifest der App konfigurieren

Zusätzlich zu den unter Android for Cars-App-Bibliothek verwenden beschriebenen Schritten sind für Vorlagen-Medien-Apps die folgenden Anforderungen zu erfüllen:

Unterstützung von Kategorien im Manifest deklarieren

In Ihrer App muss die androidx.car.app.category.MEDIA Auto-App-Kategorie im Intent-Filter von CarAppService deklariert werden.

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

Damit Ihre App auf die MediaPlaybackTemplate zugreifen kann, muss sie außerdem die Berechtigung androidx.car.app.MEDIA_TEMPLATES in ihrer Manifestdatei deklarieren:

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

Mindest-API-Level für die Car App festlegen

Medien-Apps, die MediaPlaybackTemplate verwenden, werden nur in CAL API 8 und höher unterstützt. Achten Sie darauf, dass die Mindest-Car App API level auf 8 festgelegt ist.

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

Attributionssymbol bereitstellen

Fügen Sie für Medien-Apps, die mit der Car App-Mediathek erstellt wurden, ein Attributionssymbol hinzu.

Android Auto-Unterstützung deklarieren

Achten Sie darauf, dass das Manifest Ihrer App Folgendes enthält:

<application>
  ...
  <meta-data android:name="com.google.android.gms.car.application"
      android:resource="@xml/automotive_app_desc"/>
  ...
</application>

Fügen Sie dann die template-Deklaration zu automotive_app_desc.xml in Ihren XML-Ressourcen hinzu. Das sollte so aussehen:

<automotiveApp xmlns:android="http://schemas.android.com/apk/res/android">
 <uses name="media"/>
 <uses name="template"/>
</automotiveApp>

Unterstützung für Android Automotive OS deklarieren

Es gibt zwei verschiedene Möglichkeiten, eine Medien-App, die die Car App Library unterstützt, auf Android Automotive OS bereitzustellen: als einzelnes APK oder als zwei separate APKs. Wenn du ein einzelnes APK bereitstellst, werden Fahrzeuge unterstützt, die für Android Automotive OS mit dem Car App Library-Host aktiviert sind. Andernfalls wird auf eine MediaBrowserService- oder MediaLibraryService-Anwendung zurückgegriffen, auch bei älteren Android-Versionen (Android 10 bis Android 13). Wenn Sie zwei separate APKs bereitstellen, können Sie die neuen Ergänzungen der Car App Library-Version aktualisieren, ohne dass sich dies auf die MediaBrowserService- oder MediaLibraryService-Version Ihrer App auswirkt.

Einzelnes APK bereitstellen

Wenn Sie ein einzelnes APK für die Car App-Mediathek und die MediaBrowserService- oder MediaLibraryService-Versionen Ihrer App bereitstellen, müssen Sie android.software.car.templates_host.media auf android:required="false" setzen.

<uses-feature android:name="android.software.car.templates_host.media" android:required="false"/>

Folgen Sie als Nächstes den Richtlinien der Car App Library für AAOS und führen Sie eine startbare CarAppActivity (oder Trampolin-Aktivität) ein. Sie müssen die Aktivität im Manifest auf android:enabled="false" festlegen. Fügen Sie als Nächstes der MediaBrowserService-Deklaration ein Metadaten-Tag hinzu, das die CarAppActivity-Komponente als Ersatz angibt. Sehen Sie sich das folgende Beispielmanifest an:

<service android:name=".media.MyMediaService"
    android:exported="true"
    android:label="@string/app_name">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
    </intent-filter>

    <!-- Link to Car App Library Activity -->
    <meta-data
        android:name="androidx.car.app.media.CalMediaActivityComponent"
        android:value="com.example.mediaapp.LaunchableTrampoline"/>
</service>

<activity
    android:name=".LaunchableTrampoline"
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:launchMode="singleTask"
    android:label="@string/app_name_cal"
    android:enabled="false"> <!-- Set to false -->

    <meta-data android:name="distractionOptimized" android:value="true" />

    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <action android:name="androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>

Vertrieb bei Google Play

Ihr APK mit der Car App Library und MediaBrowserService oder MediaLibraryService sollte mit einem höheren Versionscode und minSdk für Android 14 (34) aktiviert werden.

Bereitstellung mit zwei APKs

Wenn du zwei separate APKs bereitstellen möchtest, eines mit der Car App Library und eines mit MediaBrowserService oder MediaLibraryService, gehe so vor, um sicherzustellen, dass die richtigen Fahrzeugfunktionen korrekt angesprochen werden.

Wenn Sie ein separates APK für die Version Ihrer App mit der Car App Library erstellen, müssen Sie android.software.car.templates_host.media auf android:required=true setzen. So wird sichergestellt, dass die App nur auf Android Automotive OS-Builds bereitgestellt wird, die für die Unterstützung des Hosts der Auto-App-Bibliothek zertifiziert sind.

<uses-feature android:name="android.software.car.templates_host.media" android:required="true"/>

Neben der Verwendung von android.software.car.templates_host.media und der Einstellung auf android:required=true müssen Sie die folgenden Schritte ausführen, um Android Automotive OS für Ihre startbare Aktivität in der Auto-App-Bibliothek zu aktivieren.

Play Distribution

Das APK, das die Auto-App-Bibliothek verwendet, sollte im speziellen Automotive OS-Track bereitgestellt werden.

Sprachbefehle unterstützen

Aktiviere die Sprachsteuerung für deine App, damit Nutzer gängige Aktionen per Sprachbefehl ausführen können. Eine ausführliche Anleitung zur Implementierung findest du unter Sprachbefehle für Medien unterstützen. Wenn du eine Vorlage für eine Medien-App verwendest und einen Sprachbefehl erhältst, musst du deine MediaBrowserService oder MediaLibraryService nicht mit Suchergebnissen aktualisieren. Füge stattdessen eine Aktion in deine Vorlage für die Medienwiedergabe ein, mit der der Nutzer basierend auf der Wiedergabe oder Suchanfrage weitere Inhalte finden kann. Die Unterstützung von Sprachbefehlen ist erforderlich, um die Qualitätsrichtlinie VC-1 zu erfüllen.

Wiedergabevorlage erstellen

Die MediaPlaybackTemplate zeigt Informationen zur Medienwiedergabe in Ihrer Medien-App der Auto-App-Bibliothek an. Mit dieser Vorlage können Sie eine Kopfzeile mit einem Titel und anpassbaren Aktionen festlegen, während die Medieninformationen und die Wiedergabesteuerung vom Host basierend auf dem Status der MediaSession Ihrer App ausgefüllt werden.

Ein Musikplayer zeigt „Sounds of Spring“ von Summer Fielding mit einem quadratischen Porträt einer Frau, die Gitarre spielt.

Abbildung 1: MediaPlaybackTemplate mit einer Header-Aktion zum Öffnen der Warteschlange oben.

In diesem Codebeispiel wird gezeigt, wie Sie eine Beispielvorlage für die Wiedergabe erstellen, die eine Headeraktion festlegt, mit der der Nutzer zu einem Bildschirm mit der Songwarteschlange wechseln kann.

val playbackTemplate = MediaPlaybackTemplate.Builder()
      .setHeader(
        Header.Builder()
          .setStartHeaderAction(Action.BACK)
          .addEndHeaderAction(
                Action.Builder()
                  .setTitle(model.context.getString(R.string.queue_button_title))
                  .setIcon(
                    CarIcon.Builder(
                        IconCompat.createWithResource(
                          model.context,
                          R.drawable.gs_queue_music_vd_theme_24,
                        ))
                      .build())
                  .setOnClickListener(showQueueScreen())
                  .build())
          .setTitle(model.context.getString(R.string.media_playback_view_title))
          .build())
      .build()

Wenn Sie MediaPlaybackTemplate verwenden, registrieren Sie ein MediaSession-Token mit dem MediaPlaybackManager in Ihrer CarAppService. Andernfalls wird ein Fehler angezeigt, wenn ein MediaPlaybackTemplate an den Host gesendet wird.

import androidx.car.app.media.MediaPlaybackManager
…

override fun onCreateSession(sessionInfo: SessionInfo): Session {
    return object : Session() {
        …

        init {
          lifecycle.addObserver(
            LifecycleEventObserver { _, event ->
              if (event == ON_CREATE) {
                val token = ... // MediaSessionCompat.Token
                (carContext.getCarService(CarContext.MEDIA_PLAYBACK_SERVICE) as MediaPlaybackManager)
                  .registerMediaPlaybackToken(token)
              }
              ...
            }
          )
        }
    }
}

.registerMediaPlaybackToken ist erforderlich, um Informationen zur Medienwiedergabe und Steuerelemente für Android Auto bereitzustellen. Dies ist auch für den Host wichtig, um medienspezifische Benachrichtigungen zu erstellen.

Bei Apps, die die Media3-Bibliothek verwenden und einen PlatformToken anstelle eines Standard-MediaSessionCompat.Token nutzen, müssen Sie in Ihrem MediaLibrarySession.Callback einen benutzerdefinierten SessionCommand implementieren, der das zugrunde liegende Plattformtoken der Sitzung zurückgibt: session.platformToken. Senden Sie in Ihrer CarAppService diesen benutzerdefinierten Befehl an die Sitzung. Nachdem Sie das Plattform-Token erhalten haben, konvertieren Sie es mit MediaSessionCompat.Token.fromToken(platformToken) und übergeben Sie dieses Kompatibilitäts-Token an die Auto-App-Bibliothek in .registerMediaPlaybackToken().

Medien mithilfe von Vorlagen organisieren

Zum Organisieren von Medien zum Durchsuchen, z. B. Songs oder Alben, empfehlen wir die Verwendung von SectionedItemTemplate. Damit kannst du GridSection und RowSection zusammen verwenden, um Layouts zu erstellen, die Listen mit Bildern und Textelementen kombinieren.

Die Benutzeroberfläche einer Musik-App zeigt Vor Kurzem angehörte Songs und Alben an, darunter zwei vertikale Zeilen und drei horizontale Albumcover im Hochformat.

Abbildung 2: Ein SectionedItemTemplate, der einen RowSection gefolgt von einem GridSection enthält

SectionedItemTemplate in einer TabTemplate verwenden

Eine praktische Möglichkeit, Medien in deiner App zu kategorisieren, ist die Verwendung von SectionedItemTemplate in einem TabTemplate.

val template =
      SectionedItemTemplate.Builder()...build();
val tabTemplate =
      TabTemplate.Builder(tabCallback)
          .setTabContents(TabContents.Builder(template).build)
          .setHeaderAction(Action.APP_ICON)
          …
          .build();

Komponenten und Funktionen der Car App-Bibliothek 1.9

Mit der Version 1.9 der Car App Library API werden benutzerdefinierte Komponenten für einzigartige Suchfunktionen eingeführt, z. B. Chips, Fortschrittsanzeigen, komprimierte Elemente, interaktive und maximierte Header, Spotlight-Bereiche und Banner.

Die Benutzeroberfläche einer Musik-App zeigt Vor Kurzem angehörte Songs und Alben an, darunter zwei vertikale Zeilen und drei horizontale Albumcover im Hochformat.

Abbildung 3: Ein SectionedItemTemplate mit Chips, Condensed Items, einem Interactive Header, Grid Items und einem Minimized Control Panel

Die Benutzeroberfläche einer Musik-App zeigt Vor Kurzem angehörte Songs und Alben an, darunter zwei vertikale Zeilen und drei horizontale Albumcover im Hochformat.

Abbildung 4: Zwei Bildschirme zum Durchsuchen von Medien mit Expanded Header, Spotlight Sections und Progress Bars

Weitere Informationen zum Entwerfen der Benutzeroberfläche Ihrer Medien-App mit diesen Vorlagen finden Sie unter Medien-Apps.

Beim Durchsuchen von Medien ist es wichtig, dass der Nutzer schnell und mit minimaler Ablenkung zum MediaPlaybackTemplate navigieren kann.Damit die Qualitätsanforderung MFT-1 erfüllt wird, muss deine App eine Möglichkeit bieten, von allen Bildschirmen zum Durchsuchen von Medien auf den MediaPlaybackTemplate zuzugreifen.

Wenn du SectionedItemTemplate verwendest, kannst du das erreichen, indem du einen Aktionsbutton hinzufügst, der dich zum Bildschirm für die Medienwiedergabe weiterleitet. Verwenden Sie die Standardaktion Action.MEDIA_PLAYBACK der Auto-App-Mediathek. Eine Medien-App zeigt diese Aktion als minimiertes Steuerfeld an. Dies ist erforderlich, um die Qualitätsanforderung MFT-1 zu erfüllen, wenn Sie die Car App-Mediathek API 1.9 oder höher verwenden. Bei anderen Vorlagen ist eine Header-Aktion eine weitere Möglichkeit, dies zu erreichen.

Intents für die Medienwiedergabe des Systems verarbeiten

Der Nutzer muss zum MediaPlaybackTemplate weitergeleitet werden, wenn eine App über eine Medienoberfläche des Systems gestartet wird, z. B. eine Medienkarte. Wir verlangen, dass Medienanwendungen diesen Intent Action verarbeiten, um Nutzern eine nahtlose Nutzung zu ermöglichen.

Füge dem Intent-Filter deiner Car App Library-Komponente (entweder CarAppActivity oder deinem Trampolin-Activity) die Aktion androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK hinzu.

Achten Sie darauf, dass Ihre Aktivität einen launchMode von singleTask oder singleTop verwendet, damit onNewIntent() aufgerufen wird.

<activity
    android:name=".LaunchableTrampoline"
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:launchMode="singleTask"
    android:label="@string/app_name_cal"
    android:enabled="false">

    <meta-data android:name="distractionOptimized" android:value="true" />

    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <action android:name="androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>

Überschreiben Sie in der Klasse Session die Methode onNewIntent(), um den eingehenden Intent zu parsen. Wenn die eingehende Intent-Aktion mit SHOW_MEDIA_PLAYBACK übereinstimmt, leite den Nutzer zum Bildschirm „Now Playing“ weiter.

@Override
public void onNewIntent(@NonNull Intent intent) {
    super.onNewIntent(intent);
    if (SHOW_MEDIA_PLAYBACK.equals(intent.getAction())) {
        ScreenManager screenManager = getCarContext().getCarService(ScreenManager.class);
        // Avoid redundant navigation if already on the playing screen
        if (screenManager.getTop() instanceof MyMediaPlayScreen) {
            return;
        }
        screenManager.push(MyMediaPlayScreen.createScreenFromPlaying(
                getCarContext(), mMediaSessionController));
    }
}

Wenn Sie eine Trampolin-Aktivität verwenden, suchen Sie in onCreate() nach der Intent-Aktion. Übergeben Sie diese Aktion an den Erstellungs-Intent CarAppActivity, bevor Sie finish() aufrufen.

public class LaunchableTrampoline extends AppCompatActivity {
    private static final String SHOW_MEDIA_PLAYBACK = "androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Intent receivedIntent = getIntent();
        String action;

        if (SHOW_MEDIA_PLAYBACK.equals(receivedIntent.getAction())) {
            action = SHOW_MEDIA_PLAYBACK;
        } else {
            action = Intent.ACTION_MAIN;
        }

        Intent intent = new Intent(action);
        intent.setClassName(getPackageName(), "androidx.car.app.activity.CarAppActivity");
        startActivity(intent);
        finish();
    }
}