Creare un'app multimediale basata su modelli

Le app multimediali basate su modelli sono in versione beta
Al momento, chiunque può pubblicare app multimediali basate su modelli nei canali di test interni e chiusi del Google Play Store. La pubblicazione nei canali aperti e di produzione sarà consentita in un secondo momento.

Le app multimediali che utilizzano i modelli della libreria di app per auto possono personalizzare l'esperienza di navigazione e riproduzione dei contenuti multimediali, garantendo al contempo che l'esperienza sia ottimizzata per gli schermi delle auto e riduca al minimo le distrazioni durante la guida.

Questa guida presuppone che tu abbia già un'app multimediale che riproduce audio su uno smartphone e che l'app multimediale sia conforme all'architettura delle app multimediali Android. La raccolta di app per auto ti consente di sostituire l'esperienza con l'app con modelli anziché con quelli creati utilizzando la struttura dei dati Crea app multimediali per auto MediaBrowser. Devi comunque fornire un MediaSession per i controlli di riproduzione e un MediaBrowserService o MediaLibraryService, che viene utilizzato per i consigli e altre esperienze smart.

Le esperienze di parcheggio e guida sono ora disponibili in versione beta
Le app multimediali basate su modelli ora sono idonee per l'aggiunta di un'esperienza di passaggio dalla modalità di parcheggio alla modalità di guida su Android Automotive OS. In questo modo, la tua app può aggiungere attività native adattive quando l'auto è parcheggiata e passare senza problemi all'esperienza di riproduzione di contenuti multimediali basata su modelli quando l'auto è in movimento.

Configura il manifest dell'app

Oltre ai passaggi descritti in Utilizzare la raccolta di app Android for Cars, per le app multimediali basate su modelli sono richiesti i seguenti requisiti:

Dichiara il supporto delle categorie nel manifest

La tua app deve dichiarare la androidx.car.app.category.MEDIA categoria di app per auto nel filtro per intent del suo 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>

Per accedere a MediaPlaybackTemplate, la tua app deve anche dichiarare l'autorizzazione androidx.car.app.MEDIA_TEMPLATES nel file manifest:

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

Imposta il livello API minimo dell'app per auto

Le app multimediali che utilizzano MediaPlaybackTemplate sono supportate solo nell'API CAL 8 e versioni successive. Assicurati che il valore minimo di Car App API level sia impostato su 8.

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

Fornisci un'icona di attribuzione

Assicurati di aggiungere un'icona di attribuzione per le app multimediali create utilizzando la raccolta di app per auto.

Dichiara il supporto di Android Auto

Assicurati che nel manifest della tua app sia incluso quanto segue:

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

Poi, aggiungi la dichiarazione template a automotive_app_desc.xml nelle risorse XML. Dovrebbe avere il seguente aspetto:

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

Dichiara il supporto di Android Automotive OS

Esistono due modi diversi per distribuire un'app multimediale abilitata per la Raccolta di app per auto su Android Automotive OS: come singolo APK o come due APK separati. Se distribuisci un singolo APK, questo supporterà i veicoli abilitati per Android Automotive OS con l'host della Raccolta di app per auto e, in caso contrario, eseguirà il fallback a un'applicazione MediaBrowserService o MediaLibraryService, anche per le versioni di Android precedenti (Android 10 - Android 13). Se scegli di distribuire due APK separati, puoi aggiornare le nuove aggiunte alla versione della Raccolta di app per auto senza timore di influire sulla versione MediaBrowserService o MediaLibraryService della tua app.

Distribuzione di un singolo APK

Quando distribuisci un singolo APK per la Raccolta di app per auto e le versioni MediaBrowserService o MediaLibraryService della tua app, è fondamentale impostare android.software.car.templates_host.media su android:required="false".

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

Poi, segui le linee guida della libreria di app per auto per AAOS e introduci un'CarAppActivity avviabile (o attività trampoline). Devi impostare l'attività su android:enabled="false" nel manifest. Poi, aggiungi un tag di metadati alla dichiarazione MediaBrowserService che indica il componente CarAppActivity come sostituto. Vedi il seguente manifest di esempio:

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

Distribuzione su Play

L'APK con la Raccolta di app per auto e MediaBrowserService o MediaLibraryService deve essere attivato con un codice di versione superiore e minSdk che ha come target Android 14 (34).

Distribuzione con due APK

Per distribuire due APK separati, uno che utilizza la libreria di app per auto e un altro che utilizza MediaBrowserService o MediaLibraryService, segui questi passaggi per assicurarti che le funzionalità del veicolo corrette siano scelte come target correttamente.

Quando crei un APK separato per la versione della tua app della Raccolta di app per auto, devi impostare android.software.car.templates_host.media su android:required=true. In questo modo, l'app viene distribuita solo su build di Android Automotive OS certificate con il supporto per l'host della libreria di app per auto.

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

Oltre a utilizzare android.software.car.templates_host.media e impostarlo su android:required=true, segui questi passaggi per attivare Android Automotive OS per l'attività della Raccolta di app per auto avviabile.

Play Distribution

L'APK che utilizza la raccolta di app per auto deve essere distribuito nel canale dedicato ad Automotive OS.

Supporta le azioni vocali

Attiva i comandi vocali nella tua app per consentire agli utenti di completare azioni comuni con comandi vocali. Per istruzioni più dettagliate sull'implementazione, consulta la sezione relativa alle azioni vocali supportate per i contenuti multimediali. Con un'app multimediale basata su modelli, se ricevi un comando vocale, non devi aggiornare MediaBrowserService o MediaLibraryService con i risultati di ricerca. Valuta invece la possibilità di aggiungere un'azione nel modello di riproduzione dei contenuti multimediali per consentire all'utente di trovare altri contenuti in base alla riproduzione o alla query di ricerca. Il supporto dei comandi vocali è necessario per soddisfare le norme sulla qualità di VC-1.

Crea il tuo modello di riproduzione

MediaPlaybackTemplate mostra le informazioni sulla riproduzione dei contenuti multimediali nell'app multimediale della Raccolta di app per auto. Questo modello consente di impostare un'intestazione con un titolo e azioni personalizzabili, mentre le informazioni sui contenuti multimediali e i controlli di riproduzione vengono compilati dall'host in base allo stato di MediaSession della tua app.

Un lettore musicale mostra Sounds of Spring di Summer Fielding con un ritratto quadrato di una donna che suona la chitarra.

Figura 1: MediaPlaybackTemplate con un'azione dell'intestazione per aprire la coda in alto.

Questo esempio di codice mostra come creare un modello di riproduzione di esempio che imposta un'azione di intestazione che consente all'utente di accedere a una schermata con la coda dei brani.

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

Quando utilizzi MediaPlaybackTemplate, registra un token MediaSession utilizzando MediaPlaybackManager nel tuo CarAppService. In caso contrario, viene visualizzato un errore quando viene inviato un MediaPlaybackTemplate all'host.

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 è necessaria per esporre le informazioni e i controlli di riproduzione dei contenuti multimediali ad Android Auto. Questo è importante anche per l'host per creare notifiche specifiche per i contenuti multimediali.

Per le app che utilizzano la libreria Media3, che usano un PlatformToken anziché un MediaSessionCompat.Token standard, dovrai implementare un SessionCommand personalizzato nel tuo MediaLibrarySession.Callback che restituisca il token della piattaforma sottostante della sessione: session.platformToken. Nella tua CarAppService, invia questo comando personalizzato alla sessione. Una volta ricevuto il token della piattaforma, convertilo utilizzando MediaSessionCompat.Token.fromToken(platformToken) e passa questo token di compatibilità alla Raccolta di app per auto in .registerMediaPlaybackToken().

Organizza i contenuti multimediali utilizzando i modelli

Per organizzare i contenuti multimediali per la navigazione, come brani o album, ti consigliamo di utilizzare SectionedItemTemplate, che ti consente di utilizzare GridSection e RowSection insieme per creare layout che combinano elenchi di immagini ed elementi di testo.

L'interfaccia di un'app musicale mostra i brani e gli album ascoltati di recente, tra cui due righe verticali e tre copertine di album orizzontali.

Figura 2: un SectionedItemTemplate contenente un RowSection seguito da un GridSection

Utilizzo di SectionedItemTemplate all'interno di un TabTemplate

Un modo pratico per classificare i contenuti multimediali all'interno della tua app è utilizzare SectionedItemTemplate all'interno di un TabTemplate.

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

Componenti e funzionalità della raccolta di app per auto 1.9

La versione 1.9 dell'API Car App Library introduce componenti personalizzati per funzionalità di navigazione uniche, come chip, barre di avanzamento, elementi compressi, intestazione interattiva ed espansa, sezioni in evidenza e banner.

L'interfaccia di un'app musicale mostra i brani e gli album ascoltati di recente, tra cui due righe verticali e tre copertine di album orizzontali.

Figura 3: un SectionedItemTemplate contenente Chips, Condensed Items, un Interactive Header, Grid Items e un Minimized Control Panel

L'interfaccia di un'app musicale mostra i brani e gli album ascoltati di recente, tra cui due righe verticali e tre copertine di album orizzontali.

Figura 4: due schermate di navigazione dei contenuti multimediali con Expanded Header, Spotlight Sections e Progress Bars

Per maggiori dettagli su come progettare l'interfaccia utente della tua app multimediale utilizzando questi modelli, consulta App multimediali.

Quando l'utente sfoglia i contenuti multimediali, è importante che possa passare rapidamente alla MediaPlaybackTemplate con il minimo disturbo.Per soddisfare il requisito di qualità MFT-1, la tua app deve offrire un modo per accedere alla MediaPlaybackTemplate da tutte le schermate di navigazione dei contenuti multimediali.

Se utilizzi SectionedItemTemplate, puoi farlo aggiungendo un pulsante di azione che ti indirizza alla schermata di riproduzione dei contenuti multimediali. Utilizza l'azione standard della Raccolta di app per auto Action.MEDIA_PLAYBACK. Un'app multimediale mostrerà questa azione come un pannello di controllo ridotto a icona, necessario per soddisfare il requisito di qualità MFT-1 se utilizzi l'API Raccolta di app per auto 1.9 o versioni successive. Per altri modelli, un'azione di intestazione è un altro modo per ottenere questo risultato.

Gestisci gli intent di riproduzione di contenuti multimediali di sistema

È necessario indirizzare l'utente alla MediaPlaybackTemplate quando un'applicazione viene avviata da una piattaforma di riproduzione di contenuti multimediali di sistema, ad esempio una scheda multimediale. Richiediamo che le applicazioni multimediali gestiscano questo Intent Action per offrire un'esperienza fluida agli utenti.

Aggiungi l'azione androidx.car.app.media.action.SHOW_MEDIA_PLAYBACK al filtro per intent del componente della raccolta di app per auto (CarAppActivity o il trampoline Activity).

Assicurati che l'attività utilizzi un launchMode di singleTask o singleTop in modo che venga richiamato onNewIntent().

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

Nella classe Session, esegui l'override di onNewIntent() per analizzare l'intent in entrata. Se l'azione dell'intent in entrata corrisponde a SHOW_MEDIA_PLAYBACK, indirizza l'utente alla schermata Now Playing.

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

Se utilizzi un'attività trampoline, controlla l'azione dell'intent all'interno di onCreate(). Passa questa azione all'intent di creazione CarAppActivity prima di chiamare 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();
    }
}