Aggiungi il supporto del sistema operativo Android Automotive alla tua app basata su modelli

Il sistema operativo Android Automotive consente agli utenti di installare app nell'auto. Per raggiungere gli utenti su questa piattaforma, devi distribuire un'app ottimizzata per il conducente compatibile con Android Automotive OS. Puoi riutilizzare quasi tutto il codice e le risorse nell'app Android Auto, ma devi creare una build separata che soddisfi i requisiti descritti in questa pagina.

Per eseguire l'app per auto su Android Automotive OS, devi avere l'ultima versione di Templates Host, che viene fornita come app di sistema.

Panoramica sullo sviluppo

L'aggiunta del supporto di Android Automotive OS richiede solo alcuni passaggi, come descritto nelle sezioni di questa pagina:

1. Crea un modulo per auto
2. Dichiara il supporto di Android Automotive OS
3. Dichiara CarAppService e CarAppActivity
4. Aggiorna le dipendenze Gradle

Utilizza Android Studio Bumblebee o versioni successive per assicurarti che tutte le funzionalità di Automotive OS siano attivate.

Crea un modulo per auto

Alcuni componenti di Android Automotive OS, come il file manifest, hanno requisiti specifici della piattaforma. Crea un modulo che possa mantenere il codice di questi componenti separato da altro codice nel progetto, ad esempio il codice utilizzato per l'app per smartphone.

Per un progetto esistente, segui questi passaggi per aggiungere un modulo per auto al progetto:

1. In Android Studio, fai clic su File > Nuovo > Nuovo modulo.
2. Seleziona Modulo per auto e poi fai clic su Avanti.
3. Fornisci un nome dell'applicazione/della libreria. Questo è il nome che gli utenti vedono per la tua app su Android Automotive OS.
4. Inserisci un nome del modulo.
5. Modifica il nome del pacchetto in modo che corrisponda all'app esistente.

6. Seleziona API 29: Android 10 (Q) per SDK minimo e poi fai clic su Avanti. Tutte le auto che supportano la raccolta di app per auto su Android Automotive OS utilizzano il livello API 29 di Android 10 o versioni successive, quindi la selezione di questo valore ha come target tutte le auto compatibili.

7. Seleziona Aggiungi nessuna attività e poi fai clic su Fine.

Se stai iniziando un nuovo progetto:

1. In Android Studio, fai clic su File > Nuovo > Nuovo progetto.
2. Seleziona Auto per Tipo di progetto.
3. Seleziona Nessuna attività e poi fai clic su Avanti.
4. Fornisci un nome per il progetto. Questo è il nome che gli utenti vedono per la tua app su Android Automotive OS.
5. Inserisci un nome del pacchetto. Per maggiori dettagli sulla selezione di un nome di pacchetto, consulta la sezione Nomi dei pacchetti.

6. Seleziona API 29: Android 10 (Q) per SDK minimo e poi fai clic su Avanti.

   Tutte le auto che supportano la raccolta di app per auto su Android Automotive OS utilizzano il livello API 29 di Android 10 o versioni successive, quindi la selezione di questo valore ha come target tutte le auto compatibili.

Dopo aver creato il modulo in Android Studio, apri il file AndroidManifest.xml nel nuovo modulo per auto:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.car.app">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme" />

    <uses-feature
        android:name="android.hardware.type.automotive"
        android:required="true" />

</manifest>

L'elemento <application> contiene alcune informazioni standard sull'app, nonché un elemento <uses-feature> che dichiara il supporto di Android Automotive OS. Tieni presente che nel file manifest non sono dichiarate attività.

Dichiara i requisiti delle funzionalità

Aggiungi il seguente elemento uses-feature al file manifest per indicare che richiede un host di modelli per funzionare correttamente:

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

Inoltre, assicurati che la tua app soddisfi i requisiti delle funzionalità di Google Play che si applicano a tutte le app create per Android Automotive OS.

Aggiorna le dipendenze Gradle

Nel modulo per auto, devi aggiungere una dipendenza dall' androidx.car.app:app-automotive artefatto, che include l'implementazione CarAppActivity necessaria per l'esecuzione dell'app su Android Automotive OS.

Se stai sviluppando l'app per supportare sia Android Auto sia Android Automotive OS, ti consigliamo di mantenere CarAppService in un modulo separato che condividi tra i moduli per dispositivi mobili e per auto. Se utilizzi questo approccio, devi aggiornare il modulo per auto in modo che includa il modulo condiviso utilizzando le dipendenze del progetto di Gradle, come mostrato nel seguente snippet:

buildscript {
    ...
    dependencies {
        ...
        implementation "androidx.car.app:app-automotive:car_app_library_version"
        implementation project(':shared_module_name')
    }
}

buildscript {
    ...
    dependencies {
        ...
        implementation("androidx.car.app:app-automotive:car_app_library_version")
        implementation(project(":shared_module_name"))
    }
}

Dichiara il supporto di Android Automotive OS

Utilizza la seguente voce del file manifest per dichiarare che la tua app supporta Android Automotive OS:

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

Questa voce del file manifest fa riferimento a un file XML che dichiara le funzionalità per auto supportate dalla tua app.

Per indicare che hai un'app della raccolta di app per auto, aggiungi un file XML denominato automotive_app_desc.xml alla directory res/xml/ nel modulo Android Automotive OS. Questo file deve includere i seguenti contenuti:

<automotiveApp>
    <uses name="template"/>
</automotiveApp>

Dichiara CarAppService e CarAppActivity

Come per Android Auto, Android Automotive OS utilizza l'implementazione di CarAppService per eseguire l'app. Per istruzioni sull'implementazione e la dichiarazione di CarAppService, consulta Creare CarAppService e Session e Dichiara CarAppService.

A differenza di Android Auto, devi includere un componente dell'applicazione aggiuntivo, CarAppActivity, che funga da punto di ingresso per l'app Android Automotive OS. L'implementazione di questa attività è inclusa nell'artefatto androidx.car.app:app-automotive ed è responsabile della comunicazione con l'applicazione host dei modelli per il rendering dell'interfaccia utente dell'app. Nel file manifest deve essere presente una sola istanza di questa attività, che deve essere dichiarata come segue:

<activity
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:name="androidx.car.app.activity.CarAppActivity"
    android:launchMode="singleTask"
    android:label="Your app name">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

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

</activity>

• android:name è impostato sul nome di classe completo della classe CarAppActivity dell'artefatto app-automotive.
• android:exported è impostato su true perché l'attività deve essere avviabile da un'app diversa da se stessa (ovvero il launcher).
• android:launchMode è impostato su singleTask in modo che l'utente possa tornare alla stessa istanza dell'attività dal launcher se si allontana.
• android:theme è impostato su @android:style/Theme.DeviceDefault.NoActionBar in modo che l'app occupi tutto lo spazio dello schermo a sua disposizione.
• Il filtro per intent indica che questa è l'attività di avvio dell'app.
• È presente un elemento <meta-data> che indica al sistema operativo che l'app può essere utilizzata quando sono in vigore restrizioni dell'esperienza utente, ad esempio quando il veicolo è in movimento.

Requisiti aggiuntivi per le app di navigazione

Per le app di navigazione, sono necessarie alcune voci del file manifest aggiuntive per CarAppActivity, come mostrato nel seguente snippet:

<activity
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:name="androidx.car.app.activity.CarAppActivity"
    android:launchMode="singleTask"
    android:label="Your app name">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <!-- Include the category below ONLY for navigation apps -->
        <category android:name="android.intent.category.APP_MAPS" />
    </intent-filter>

    <!-- Include the intent-filter below ONLY for navigation apps -->
    <intent-filter>
        <action android:name="androidx.car.app.action.NAVIGATE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="geo" />
    </intent-filter>

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

</activity>

• La categoria aggiuntiva android.intent.category.APP_MAPS informa il sistema che la tua app è in grado di mostrare la posizione dell'utente.
• Il filtro per intent androidx.car.app.action.NAVIGATE garantisce che gli utenti abbiano la possibilità di utilizzare la tua app quando gestiscono un intent di navigazione implicito da un'altra app per auto.

Supporta i link diretti

Per migliorare l'esperienza dell'app basata su modelli sui dispositivi Android Automotive OS, puoi aggiungere il supporto dei link diretti a CarAppActivity. Ad esempio, questo consente agli utenti di aprire l'app direttamente da un browser o quando ricevono un URL condiviso da uno smartphone utilizzando Condivisione nelle vicinanze.

Aggiungi filtri per intent di link diretti

Per informare il sistema operativo che la tua app è in grado di gestire i link diretti, devi aggiungere i filtri per intent appropriati all'interno dell'elemento <activity> per CarAppActivity della tua app. Per ulteriori indicazioni, consulta Aggiungere filtri per intent per i link in entrata.

Per un'esperienza utente ottimale, ti consigliamo di supportare tutti i link diretti supportati dalla tua app per dispositivi mobili che possono essere ragionevolmente supportati dall'app per auto.

Gestisci gli intent di link diretti

Per gestire gli intent, l'app deve leggere i dati dagli intent in entrata sia quando viene creata la Session dell'app per auto durante onCreateScreen() sia quando riceve un nuovo intent durante onNewIntent():

class MySession : Session() {
    // ...
    override fun onCreateScreen(intent: Intent): Screen {
        // Handle the intent when the app is being started for the first time
        return MyStartScreen(carContext)
    }

    override fun onNewIntent(intent: Intent) {
        // Handle the intent when the app is already running
    }
}
AutomotiveOS.kt

Altre considerazioni

Tieni presente queste altre considerazioni quando sviluppi l'app Android Automotive OS:

Nomi pacchetto

Poiché distribuisci un APK (Android Package Kit) separato per Android Automotive OS, puoi riutilizzare il nome del pacchetto dell'app per dispositivi mobili o crearne uno nuovo. Se utilizzi un nome di pacchetto diverso, la tua app ha due schede del Play Store separate. Se riutilizzi il nome del pacchetto attuale, la tua app ha una singola scheda su entrambe le piattaforme.

Questa è principalmente una decisione di business. Ad esempio, se un team lavora all'app per dispositivi mobili e un altro team lavora all'app Android Automotive OS, potrebbe essere utile avere nomi di pacchetti separati e consentire a ogni team di gestire la propria scheda dello Store. Non c'è una grande differenza nello sforzo tecnico richiesto per utilizzare uno dei due approcci.

La seguente tabella riepiloga alcune altre differenze principali tra il mantenimento del nome del pacchetto attuale e l'utilizzo di un nuovo nome di pacchetto:

Contenuto offline

Se applicabile, implementa il supporto offline nella tua app. Le auto con Android Automotive OS dovrebbero avere una propria connettività dati, il che significa che un piano dati è incluso nel costo del veicolo o pagato dall'utente. Tuttavia, le auto dovrebbero anche avere una connettività più variabile rispetto ai dispositivi mobili.

Ecco alcune cose da tenere a mente quando valuti la tua strategia di supporto offline:

• Il momento migliore per scaricare i contenuti è quando l'app è in uso.
• Non dare per scontato che il Wi-Fi sia disponibile. Un'auto potrebbe non rientrare mai nella portata del Wi-Fi oppure l'OEM (Original Equipment Manufacturer, produttore di apparecchiature originali) potrebbe aver disattivato il Wi-Fi a favore di una rete mobile.
• Anche se è accettabile memorizzare nella cache in modo intelligente i contenuti che prevedi che gli utenti utilizzino, ti consigliamo di consentire all'utente di modificare questo comportamento.
• Lo spazio su disco delle auto varia, quindi offri agli utenti un modo per eliminare i contenuti offline.

Domande frequenti

Nelle seguenti sezioni sono riportate le risposte ad alcune domande frequenti su Android Automotive OS.

Esistono restrizioni o consigli per l'utilizzo di SDK e librerie di terze parti?

Non esistono linee guida specifiche sull'utilizzo di SDK e librerie di terze parti. Se scegli di utilizzare SDK e librerie di terze parti, sei comunque responsabile del rispetto di tutti i requisiti di qualità delle app per auto.

Come faccio a pubblicare la mia app Android Automotive OS utilizzando Google Play Console?

Per informazioni dettagliate su come pubblicare l'app Android Automotive OS utilizzando Google Play Console, consulta Distribuire su auto.

Risoluzione dei problemi

Di seguito sono riportate informazioni utili per alcuni scenari comuni di risoluzione dei problemi su Android Automotive OS.

• Anche dopo aver disinstallato un'app della raccolta di app per auto dalle impostazioni di sistema, ricevo un errore quando provo a installare una nuova versione.

  Per assicurarti che l'app sia disinstallata, utilizza il comando adb uninstall app.package.name.