Adicionar suporte para o Android Automotive OS ao seu app a partir de um modelo

O Android Automotive OS permite que os usuários instalem apps no carro. Para alcançar os usuários nessa plataforma, você precisa distribuir um app otimizado para motoristas que seja compatível com o Android Automotive OS. É possível reutilizar quase todo o código e os recursos do seu app original no app Android Auto, mas é necessário criar uma versão separada que atenda aos requisitos descritos nesta página.

Para executar o app para carros no Android Automotive OS, você precisa do Host de modelos mais recente, que vem como um app do sistema.

Visão geral do desenvolvimento

A adição de suporte para o Android Automotive OS exige apenas algumas etapas, conforme descrito nas seções desta página:

  1. Criar um módulo automotivo
  2. Declarar suporte ao Android Automotive OS
  3. Declarar CarAppService e CarAppActivity
  4. Atualizar as dependência do Gradle

Use o Android Studio Bumblebee ou mais recente para garantir que todos os recursos do Automotive OS estejam ativados.

Criar um módulo automotivo

Alguns componentes do Android Automotive OS, como o manifesto, têm requisitos específicos da plataforma. Crie um módulo que possa manter o código desses componentes separado do restante do código do seu projeto, como o código usado no app para smartphones.

Para um projeto já existente, siga as etapas abaixo para adicionar um módulo automotivo ao seu projeto.

  1. No Android Studio, clique em File > New > New Module.
  2. Selecione Automotive Module e clique em Next.
  3. Preencha o campo Application/Library name. Esse é o nome do seu app que os usuários veem no Android Automotive OS.
  4. Preencha o campo Module name.
  5. Edite o Package name para corresponder ao app já existente.
  6. Selecione API 29: Android 10 (Q) para o Minimum SDK e clique em Next. Todos os carros que oferecem suporte à biblioteca Car App no Android Automotive OS são executados no Android 10 (nível 29 da API) ou mais recente. Portanto, a seleção desse valor se destina a todos os carros compatíveis.

  7. Clique em Add No Activity e, em seguida, clique em Finish.

Se você estiver iniciando um novo projeto, siga estas etapas:

  1. No Android Studio, clique em File > New > New Project.
  2. Selecione Automotive em Project Type.
  3. Selecione No Activity e clique em Next.
  4. Forneça um Name para o projeto. Esse é o nome do seu app que os usuários veem no Android Automotive OS.
  5. Insira um Package name. Para ver mais detalhes sobre como selecionar um nome de pacote, consulte a seção Nomes de pacotes.
  6. Selecione API 29: Android 10 (Q) para o Minimum SDK e clique em Next.

    Todos os carros que oferecem suporte à biblioteca Car App no Android Automotive OS são executados no Android 10 (nível 29 da API) ou mais recente. Portanto, a seleção desse valor se destina a todos os carros compatíveis.

Depois de criar seu módulo no Android Studio, abra o arquivo AndroidManifest.xml no novo módulo automotivo:

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

O elemento application tem algumas informações padrão do app, bem como um elemento uses-feature que declara suporte para o Android Automotive OS. Observe que não há atividades declaradas no manifesto.

Em seguida, adicione os seguintes elementos uses-feature ao seu manifesto:

<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" />
    <uses-feature
        android:name="android.software.car.templates_host"
        android:required="true" />

    <uses-feature
        android:name="android.hardware.wifi"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.screen.portrait"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.screen.landscape"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.camera"
        android:required="false" />

</manifest>

O primeiro elemento uses-feature declara que seu app usa o Templates Host para ser executado. Definir explicitamente os quatro elementos uses-feature restantes para required="false" garante que o app não entre em conflito com os recursos de hardware disponíveis nos dispositivos Android Automotive OS.

Atualizar as dependência do Gradle

No seu módulo automotivo, você precisa adicionar uma dependência no artefato androidx.car.app:app-automotive. Isso inclui a implementação de CarAppActivity necessária para que o app seja executado no Android Automotive OS.

Se você está desenvolvendo seu app para oferecer suporte ao Android Auto e ao Android Automotive OS, recomendamos manter o CarAppService em um módulo separado que você compartilhe entre os módulos automotivo e para dispositivos móveis. Se você estiver usando essa abordagem, será necessário atualizar o módulo automotivo para incluir o módulo compartilhado usando as dependências do projeto (link em inglês) do Gradle, conforme mostrado no seguinte snippet:

Groovy

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

Kotlin

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

Declarar suporte ao Android Automotive OS

Use esta entrada de manifesto para declarar que o app oferece suporte ao Android Automotive OS:

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

Essa entrada de manifesto se refere a um arquivo XML que declara a quais recursos automotivos seu app oferece suporte.

Para indicar que você tem um app da biblioteca Car App, adicione um arquivo XML chamado automotive_app_desc.xml ao diretório res/xml/ no módulo do Android Automotive OS. Esse arquivo precisa incluir este conteúdo:

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

Declarar CarAppService e CarAppActivity

Assim como no Android Auto, o Android Automotive OS usa a implementação do CarAppService para executar seu app. Consulte Criar CarAppService e Session e Declarar o CarAppService para conferir instruções sobre como implementar e declarar o CarAppService.

Ao contrário do Android Auto, você precisa incluir outro componente de aplicativo (CarAppActivity) para servir como ponto de entrada para o app Android Automotive OS. A implementação dessa atividade está incluída no artefato androidx.car.app:app-automotive e é responsável por se comunicar com o aplicativo host de modelo para renderizar a interface do seu app. É necessário ter apenas uma instância dessa atividade no manifesto, que precisa ser declarada desta forma:

<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 é definido como o nome totalmente qualificado da classe CarAppActivity do artefato app-automotive.
  • android:exported é definido como true, porque a atividade precisa ser inicializável por um app que não seja o dela mesma, ou seja, pela tela de início.
  • android:launchMode é definido como singleTask para que o usuário possa retornar à mesma instância da atividade da tela de início se sair da tela.
  • android:theme é definido como @android:style/Theme.DeviceDefault.NoActionBar para que o app ocupe todo o espaço disponível em tela cheia.
  • O filtro de intent indica que essa é a atividade da tela de início do app.
  • Há um elemento <meta-data> que indica ao SO que o app pode ser usado enquanto as restrições de UX estão em vigor, como quando o veículo está em movimento.

Para apps de navegação, há mais algumas entradas de manifesto necessárias para o CarAppActivity, conforme mostrado no snippet abaixo:

<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>
  • A categoria extra android.intent.category.APP_MAPS informa ao sistema que seu app pode mostrar a localização do usuário.
  • O filtro de intent androidx.car.app.action.NAVIGATE garante que os usuários tenham a opção de usar seu app ao processar uma intent de navegação implícita de outro app para carro.

Outras considerações

Lembre-se destas considerações quando estiver desenvolvendo seu app Android Automotive OS:

Nomes de pacote

Como você distribui um pacote de aplicativo Android (APK) separado para o Android Automotive OS, é possível reutilizar o nome do pacote do seu app para dispositivos móveis ou criar um novo nome de pacote. Se você usar um nome de pacote diferente, o app terá duas páginas "Detalhes do app" separadas para a Play Store. Se você reutilizar o nome do pacote atual, o app vai ter uma única página de detalhes nas duas plataformas.

Isso é predominantemente uma decisão comercial. Por exemplo, se você tem uma equipe trabalhando no app para dispositivos móveis e uma equipe separada trabalhando no app Android Automotive OS, pode fazer sentido ter nomes de pacotes diferentes e permitir que cada equipe gerencie as próprias páginas "Detalhes do app". Não há uma grande diferença no esforço técnico necessário para usar qualquer uma das abordagens.

A tabela a seguir resume algumas das principais diferenças importantes entre manter o nome do pacote atual ou usar um novo nome:

Recurso Mesmo nome de pacote Novo nome do pacote
Página "Detalhes do app" Uma Várias
Instalação espelhada Sim: reinstalação rápida de app durante o assistente de configuração Não
Processo de análise da Play Store Bloqueio de análises: se a análise falhar para um APK, os outros APKs enviados na mesma versão serão bloqueados Análises individuais
Estatísticas, métricas e vitals Combinado: você pode filtrar por nome de dispositivo para dados específicos de automóveis. Separados
Indexação e classificação na pesquisa Com base na posição atual Sem transferência
Integração a outros apps Provavelmente nenhuma alteração será necessária, supondo que o código de mídia seja compartilhado entre os dois APKs Talvez seja necessário atualizar o app correspondente, como para a reprodução de URIs com o Google Assistente.

Conteúdo off-line

Se aplicável, implemente o suporte off-line no seu app. Os carros com Android Automotive OS precisam ter conectividade de dados própria, o que significa que um plano de dados está incluído no custo do veículo ou pago pelo usuário. No entanto, espera-se que os carros tenham mais conectividade variável do que os dispositivos móveis.

Veja alguns pontos importantes ao considerar sua estratégia de suporte off-line:

  • O melhor momento para baixar conteúdo é enquanto o app está em uso.
  • Não suponha que o Wi-Fi esteja disponível. Um carro pode nunca entrar no alcance do Wi-Fi ou o fabricante de equipamento original (OEM) pode ter desativado o Wi-Fi em favor de uma rede celular.
  • Não há problema em armazenar em cache o conteúdo que você espera que os usuários usem, mas recomendamos permitir que eles mudem esse comportamento.
  • O espaço em disco nos carros varia. Por isso, ofereça aos usuários uma maneira de excluir conteúdo off-line.

Perguntas frequentes

Consulte as seções a seguir para ver respostas de algumas perguntas frequentes sobre o Android Automotive OS.

Há restrições ou recomendações quanto ao uso de SDKs e bibliotecas de terceiros?

Não há diretrizes específicas sobre o uso de SDKs e bibliotecas de terceiros. Se você optar por usar SDKs e bibliotecas de terceiros, ainda será responsável por obedecer a todos os requisitos de qualidade de apps para carros.

Como faço para publicar meu app Android Automotive OS usando o Google Play Console?

Para saber como publicar seu app Android Automotive OS usando o Google Play Console, consulte Distribuir para carros.

Solução de problemas

Consulte esta seção para conseguir ajuda com alguns cenários comuns de solução de problemas no Android Automotive OS.

  • Mesmo depois de desinstalar um app da biblioteca Car App das configurações do sistema, recebo um erro quando tento instalar uma nova versão.

    Para garantir que o app seja desinstalado, use o comando adb uninstall app.package.name.