Créer une application multimédia basée sur des modèles

Les applications multimédias basées sur des modèles sont en version bêta
Pour le moment, tout le monde peut publier des applications multimédias à partir d'un modèle sur les canaux de test internes et fermés du Google Play Store. La publication sur les canaux ouverts et de production sera autorisée ultérieurement.

Les applications multimédias qui utilisent les modèles de la bibliothèque d'applications pour voiture peuvent personnaliser leur expérience de navigation et de lecture multimédia, tout en s'assurant que l'expérience est optimisée pour les écrans de voiture et qu'elle minimise les distractions pendant la conduite.

Dans ce guide, nous partons du principe que vous disposez déjà d'une application multimédia qui lit du contenu audio sur un téléphone et que cette application est conforme à l'architecture des applications multimédias Android. La bibliothèque d'applications pour voitures vous permet de remplacer l'expérience dans l'application par des modèles au lieu de ceux créés à l'aide de la structure de données MediaBrowser Créer des applications multimédias pour voitures. Vous devez toujours fournir un MediaSession pour les commandes de lecture, ainsi qu'un MediaBrowserService ou un MediaLibraryService, qui est utilisé pour les recommandations et d'autres expériences intelligentes.

Les expériences de stationnement et de conduite sont désormais disponibles en version bêta
Les applications multimédias basées sur des modèles peuvent désormais ajouter une expérience de passage du mode stationnement au mode conduite sur Android Automotive OS. Cela permet à votre application d'ajouter des activités natives adaptatives lorsque le véhicule est garé et de passer facilement à l'expérience de lecture multimédia basée sur un modèle lorsque le véhicule roule.

Configurer le fichier manifeste de votre application

En plus des étapes décrites dans Utiliser la bibliothèque d'applications Android for Cars, les applications multimédias basées sur des modèles doivent respecter les exigences suivantes :

Déclarer la catégorie compatible dans votre fichier manifeste

Votre application doit déclarer la catégorie d'applications automobiles androidx.car.app.category.MEDIA dans le filtre d'intent de son CarAppService.

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

Pour accéder à MediaPlaybackTemplate, votre application doit également déclarer l'autorisation androidx.car.app.MEDIA_TEMPLATES dans son fichier manifeste :

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

Définir le niveau d'API minimal de l'application pour voiture

Les applications multimédias utilisant MediaPlaybackTemplate ne sont compatibles qu'avec l'API CAL 8 et les versions ultérieures. Assurez-vous que votre Car App API level minimal est défini sur 8.

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

Fournir une icône d'attribution

Veillez à ajouter une icône d'attribution pour les applications multimédias créées à l'aide de la bibliothèque d'applications pour voitures.

Déclarer la prise en charge d'Android Auto

Assurez-vous que les éléments suivants sont inclus dans le fichier manifeste de votre application :

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

Ajoutez ensuite la déclaration template à automotive_app_desc.xml dans vos ressources XML. Voici le résultat attendu :

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

Déclarer la prise en charge d'Android Automotive OS

Vous pouvez distribuer une application multimédia compatible avec la bibliothèque d'applications pour voitures sur Android Automotive OS de deux manières différentes : sous la forme d'un seul APK ou de deux APK distincts. Si vous distribuez un seul APK, il sera compatible avec les véhicules équipés d'Android Automotive OS avec l'hôte de la bibliothèque d'applications pour voitures et utilisera une application MediaBrowserService ou MediaLibraryService si ce n'est pas le cas, même pour les anciennes versions d'Android (Android 10 à Android 13). Si vous choisissez de distribuer deux APK distincts, vous pouvez mettre à jour les nouveaux ajouts à la version de la bibliothèque d'applications pour voitures sans craindre d'avoir un impact sur la version MediaBrowserService ou MediaLibraryService de votre application.

Distribuer un seul APK

Lorsque vous distribuez un seul APK pour la bibliothèque d'applications pour voitures et les versions MediaBrowserService ou MediaLibraryService de votre application, il est essentiel de définir android.software.car.templates_host.media sur android:required="false".

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

Ensuite, suivez les consignes de la bibliothèque d'applications pour voiture pour AAOS et introduisez une CarAppActivity (ou activité trampoline) pouvant être lancée. Vous devez définir l'activité sur android:enabled="false" dans le fichier manifeste. Ensuite, ajoutez un tag de métadonnées à la déclaration MediaBrowserService indiquant le composant CarAppActivity en tant que remplacement. Consultez l'exemple de fichier manifeste suivant :

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

Distribution Play

Votre APK avec la bibliothèque d'applications pour voitures et MediaBrowserService ou MediaLibraryService doit être activé avec un code de version plus élevé et un minSdk ciblant Android 14 (34).

Distribution avec deux APK

Pour distribuer deux APK distincts, l'un utilisant la bibliothèque d'applications pour voitures et l'autre utilisant MediaBrowserService ou MediaLibraryService, suivez ces étapes pour vous assurer que les fonctionnalités du véhicule sont correctement ciblées.

Lorsque vous créez un APK distinct pour la version de votre application utilisant la bibliothèque d'applications pour voitures, vous devez définir android.software.car.templates_host.media sur android:required=true. Cela garantit que l'application n'est distribuée que sur les builds Android Automotive OS certifiés compatibles avec l'hôte de la bibliothèque d'applications pour voitures.

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

En plus d'utiliser android.software.car.templates_host.media et de le définir sur android:required=true, suivez ces étapes pour activer Android Automotive OS pour votre activité de bibliothèque d'applications Car exécutable.

Play Distribution

L'APK qui utilise la bibliothèque d'applications pour voitures doit être distribué dans le canal dédié à Automotive OS.

Accepter les commandes vocales

Activez la commande vocale dans votre application pour permettre aux utilisateurs d'effectuer des actions courantes sans utiliser leurs mains. Pour obtenir des instructions d'implémentation plus détaillées, consultez Accepter les commandes vocales pour les contenus multimédias. Avec une application multimédia basée sur un modèle, si vous recevez une commande vocale, vous n'avez pas besoin de mettre à jour votre MediaBrowserService ou votre MediaLibraryService avec les résultats de recherche. Envisagez plutôt d'ajouter une action dans votre modèle de lecture multimédia pour permettre à l'utilisateur de trouver d'autres contenus en fonction de cette lecture ou de cette requête de recherche. La prise en charge des commandes vocales est requise pour respecter la consigne de qualité VC-1.

Créer votre modèle de lecture

MediaPlaybackTemplate affiche les informations de lecture multimédia dans l'application multimédia de votre bibliothèque d'applications pour voitures. Ce modèle permet de définir un en-tête avec un titre et des actions personnalisables, tandis que les informations multimédias et les commandes de lecture sont renseignées par l'hôte en fonction de l'état de la MediaSession de votre application.

Un lecteur de musique affiche &quot;Sounds of Spring&quot; de Summer Fielding avec un portrait carré d'une femme jouant de la guitare.

Figure 1 : MediaPlaybackTemplate avec une action d'en-tête pour ouvrir la file d'attente en haut.

Cet exemple de code montre comment créer un exemple de modèle de lecture qui définit une action d'en-tête permettant à l'utilisateur d'accéder à un écran contenant la file d'attente des titres.

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

Lorsque vous utilisez MediaPlaybackTemplate, enregistrez un jeton MediaSession à l'aide de MediaPlaybackManager dans votre CarAppService. À défaut, une erreur s'affiche lorsqu'un MediaPlaybackTemplate est envoyé à l'hôte.

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 est nécessaire pour exposer les informations et les commandes de lecture multimédia à Android Auto. Cela est également important pour que l'hôte puisse créer des notifications spécifiques aux contenus multimédias.

Pour les applications utilisant la bibliothèque Media3, qui utilisent un PlatformToken plutôt qu'un MediaSessionCompat.Token standard, vous devez implémenter un SessionCommand personnalisé dans votre MediaLibrarySession.Callback qui renvoie le jeton de plate-forme sous-jacent de la session : session.platformToken. Dans votre CarAppService, envoyez cette commande personnalisée à la session. Une fois que vous avez reçu le jeton de plate-forme, convertissez-le à l'aide de MediaSessionCompat.Token.fromToken(platformToken) et transmettez ce jeton de compatibilité à la bibliothèque d'applications pour voitures dans .registerMediaPlaybackToken().

Organiser les éléments multimédias à l'aide de modèles

Pour organiser les contenus multimédias à parcourir, tels que des chansons ou des albums, nous vous recommandons d'utiliser SectionedItemTemplate, qui vous permet d'utiliser GridSection et RowSection ensemble pour créer des mises en page qui combinent des listes d'images et des éléments textuels.

L'interface d'une application musicale affiche les titres et albums écoutés récemment, avec deux lignes verticales et trois pochettes d'album horizontales.

Figure 2 : SectionedItemTemplate contenant un RowSection suivi d'un GridSection

Utiliser SectionedItemTemplate dans un TabTemplate

Pour classer les contenus multimédias dans votre application, vous pouvez utiliser SectionedItemTemplate dans un TabTemplate.

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

Composants et fonctionnalités de la bibliothèque d'applications pour voitures 1.9

La version 1.9 de l'API de la bibliothèque d'applications pour voitures introduit des composants personnalisés pour des fonctionnalités de navigation uniques, telles que les chips, les barres de progression, les éléments condensés, l'en-tête interactif et développé, les sections Spotlight et les bannières.

L'interface d'une application musicale affiche les titres et albums écoutés récemment, avec deux lignes verticales et trois pochettes d'album horizontales.

Figure 3 : SectionedItemTemplate contenant Chips, Condensed Items, Interactive Header, Grid Items et Minimized Control Panel

L'interface d'une application musicale affiche les titres et albums écoutés récemment, avec deux lignes verticales et trois pochettes d'album horizontales.

Figure 4 : Deux écrans de navigation multimédia avec Expanded Header, Spotlight Sections et Progress Bars

Pour en savoir plus sur la conception de l'interface utilisateur de votre application multimédia à l'aide de ces modèles, consultez Applications multimédias.

Lorsque l'utilisateur parcourt des contenus multimédias, il est important qu'il puisse accéder rapidement à l'écran MediaPlaybackTemplate avec un minimum de distraction.Pour répondre à l'exigence de qualité MFT-1, votre application doit permettre d'accéder à l'écran MediaPlaybackTemplate depuis tous les écrans de navigation multimédia.

Si vous utilisez SectionedItemTemplate, vous pouvez ajouter un bouton d'action qui vous redirige vers l'écran de lecture multimédia. Utilisez l'action Action.MEDIA_PLAYBACK standard de la bibliothèque d'applications pour voitures. Une application multimédia affichera cette action sous la forme d'un panneau de configuration réduit, ce qui est nécessaire pour répondre à l'exigence de qualité MFT-1 si vous utilisez l'API de la bibliothèque d'applications automobiles 1.9 ou une version ultérieure. Pour les autres modèles, une action d'en-tête est un autre moyen d'y parvenir.

Gérer les intents de lecture multimédia du système

Il est nécessaire de rediriger l'utilisateur vers MediaPlaybackTemplate lorsqu'une application est lancée à partir d'une surface de lecture multimédia du système, telle qu'une fiche multimédia. Nous exigeons que les applications multimédias gèrent ce Intent Action afin d'offrir une expérience fluide aux utilisateurs.

Ajoutez l'action androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK au filtre d'intent de votre composant de la bibliothèque d'applications pour voitures (CarAppActivity ou votre trampoline Activity).

Assurez-vous que votre activité utilise un launchMode de singleTask ou singleTop afin que onNewIntent() soit appelé.

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

Dans votre classe Session, remplacez onNewIntent() pour analyser l'intent entrant. Si l'action d'intent entrant correspond à SHOW_MEDIA_PLAYBACK, redirigez l'utilisateur vers l'écran "Lecture en cours".

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

Si vous utilisez une activité de trampoline, recherchez l'action d'intent dans onCreate(). Transmettez cette action à l'intent de création CarAppActivity avant d'appeler finish().

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