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 nella tua 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 disporre dell'ultima versione di Templates Host, che viene fornita come app di sistema.

Panoramica dello sviluppo

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

1. Crea un modulo per il settore automobilistico
2. Dichiarare il supporto di Android Automotive OS
3. Dichiarare CarAppService e CarAppActivity
4. Aggiornare le dipendenze di Gradle

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

Crea un modulo per il settore automobilistico

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

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

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

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

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

Se stai iniziando un nuovo progetto:

1. In Android Studio, fai clic su File > Nuovo > Nuovo progetto.
2. Seleziona Automotive 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 sul sistema operativo Android Automotive.
5. Inserisci un nome pacchetto. Per ulteriori dettagli sulla selezione di un nome del pacchetto, consulta la sezione Nomi pacchetto.

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

   Tutte le auto che supportano la libreria di app per auto su Android Automotive OS funzionano con Android 10 livello API 29 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 il settore automobilistico:

<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 manifest non sono dichiarate attività.

Dichiarare i requisiti delle funzionalità

Successivamente, aggiungi il seguente elemento uses-feature al 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.

Aggiornare le dipendenze di Gradle

All'interno del modulo per il settore automobilistico, devi aggiungere una dipendenza dall'artefatto androidx.car.app:app-automotive, che include l'implementazione CarAppActivity necessaria per l'esecuzione dell'app su Android Automotive OS.

Se stai sviluppando la tua app per supportare sia Android Auto che Android Automotive OS, ti consigliamo di mantenere il tuo CarAppService in un modulo separato che condividi tra i moduli mobile e automotive. Se utilizzi questo approccio, devi aggiornare il modulo per auto in modo da includere 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"))
    }
}

Dichiarare il supporto di Android Automotive OS

Utilizza la seguente voce del 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 manifest fa riferimento a un file XML che dichiara le funzionalità automobilistiche supportate dalla tua app.

Per indicare che hai un'app Car App Library, 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>

Dichiarare CarAppService e CarAppActivity

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

A differenza di Android Auto, devi includere un componente dell'applicazione aggiuntivo, CarAppActivity, che funge da punto di ingresso per l'app Android Automotive OS. L'implementazione di questa attività è inclusa nell'elemento androidx.car.app:app-automotive ed è responsabile della comunicazione con l'applicazione host del modello per il rendering della UI dell'app. Nel 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, quindi l'utente può tornare alla stessa istanza dell'attività da Avvio app se si allontana.
• android:theme è impostato su @android:style/Theme.DeviceDefault.NoActionBar in modo che l'app occupi tutto lo spazio disponibile sullo schermo.
• Il filtro per intent indica che questa è l'attività di avvio dell'app.
• Esiste un elemento <meta-data> che indica al sistema operativo che l'app può essere utilizzata mentre sono in vigore limitazioni della UX, ad esempio quando il veicolo è in movimento.

Requisiti aggiuntivi per le app di navigazione

Per le app di navigazione, sono necessarie alcune voci del 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 comunica al 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.

Supportare i link diretti

Per migliorare l'esperienza della tua app basata su modelli sui dispositivi Android Automotive OS, puoi aggiungere il supporto per i link diretti al tuo CarAppActivity. Ad esempio, ciò consente agli utenti di aprire la tua app direttamente da un browser o quando ricevono un URL condiviso da uno smartphone tramite Quick Share.

Aggiungere filtri per intent di link diretti

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

Per garantire la migliore esperienza utente, ti consigliamo di supportare tutti i link diretti supportati dalla tua app mobile che possono essere ragionevolmente supportati dalla tua app in auto.

Gestire gli intent di link diretti

Per gestire gli intent, la tua app deve leggere i dati dagli intent in entrata sia quando viene creato Session dell'app per l'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 a mente queste altre considerazioni quando sviluppi la tua app per Android Automotive OS:

Nomi pacchetto

Poiché distribuisci un kit Android Package (APK) separato per Android Automotive OS, puoi riutilizzare il nome del pacchetto della tua app mobile o crearne uno nuovo. Se utilizzi un nome di pacchetto diverso, la tua app ha due schede separate del Play Store. Se riutilizzi il nome del pacchetto attuale, la tua app avrà un'unica scheda su entrambe le piattaforme.

Si tratta principalmente di una decisione aziendale. Ad esempio, se hai un team che lavora all'app mobile e un team separato che 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 nell'impegno 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 del pacchetto:

Contenuti 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, si prevede che le auto abbiano una connettività più variabile rispetto ai dispositivi mobili.

Ecco alcuni aspetti da tenere presente quando valuti la tua strategia di assistenza offline:

• Il momento migliore per scaricare i contenuti è mentre l'app è in uso.
• Non dare per scontato che il Wi-Fi sia disponibile. Un'auto potrebbe non rientrare mai nel raggio d'azione del Wi-Fi oppure il produttore di apparecchiature originali (OEM) potrebbe aver disattivato il Wi-Fi a favore di una rete mobile.
• Sebbene sia 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

Consulta le sezioni seguenti per trovare 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 della conformità a tutti i requisiti di qualità delle app per auto.

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

Per informazioni dettagliate su come pubblicare la tua app per Android Automotive OS utilizzando Google Play Console, consulta la pagina Distribuire su auto.

Risoluzione dei problemi

Di seguito sono riportati alcuni scenari comuni di risoluzione dei problemi su Android Automotive OS.

• Anche dopo aver disinstallato un'app della libreria 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.