Adicionar compatibilidade com o Android Automotive OS ao seu projeto do Android Auto

Se você já tem um app de mídia que funciona com o Android Auto, pode adicionar compatibilidade com o Android Automotive OS seguindo apenas algumas etapas. O Android Automotive OS permite que os usuários instalem apps independentes no sistema de sistema de infoentretenimento de veículos. Para alcançar usuários que têm carro com o Android Automotive OS, é necessário criar um app autônomo que seja otimizado para o trânsito e funcione separadamente do app para smartphones.

O Android Automotive OS se conecta ao seu app usando o mesmo Serviço de navegação de mídia usado pelo app para smartphones para se conectar ao Android Auto.

Visão geral do desenvolvimento

Adicionar compatibilidade com o Android Automotive OS é simples e requer apenas algumas etapas:

  1. Crie um módulo automotivo.
  2. Examine seu arquivo de manifesto.
  3. Atualize suas dependências do Gradle.
  4. Adicione configurações ou atividades de entrada (opcional).

Considerações sobre o design

O Android Automotive OS cuida da disposição do conteúdo de mídia que ele recebe do Serviço de navegação de mídia do seu app. Assim como no Android Auto, isso significa que seu app não desenha a IU nem inicia nenhuma atividade quando um usuário aciona a reprodução de mídia.

No entanto, se você estiver implementando atividades de configurações ou login, essas atividades precisam ser otimizadas para veículos. Consulte as diretrizes de design (link em inglês) do Android Automotive OS ao projetar essas áreas do seu app.

Configurar seu projeto

É necessário configurar várias partes diferentes do projeto do seu app para ativar a compatibilidade com o Android Automotive OS.

Ativar recursos automotivos no Android Studio

Para acessar os recursos de compilação e teste do Android Automotive OS, use o Android Studio 3.5 Canary 11 ou uma versão posterior.

Em seguida, siga estas etapas para ativar os recursos automotivos:

  1. Crie um arquivo studioFlags.xml (se ele ainda não existir) em um dos seguintes locais, dependendo do sistema operacional:

    • Windows: %USERPROFILE%\.AndroidStudioPreview3.5\config\options
    • macOS: ~/Library/Preferences/AndroidStudioPreview3.5/options
    • Linux: ~/.AndroidStudioPreview3.5/config/options
  2. Inclua a seguinte entrada no arquivo studioFlags.xml:

    <application>
        <component name="StudioFlags">
          <option name="data">
            <map>
              <entry key="npw.templates.automotive" value="true" />
            </map>
          </option>
        </component>
        </application>
        

Criar um módulo automotivo

Alguns componentes do Android Automotive OS, como o manifesto, têm requisitos específicos da plataforma. Portanto, é necessário criar 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. Siga as etapas abaixo para adicionar um módulo automotivo ao seu projeto:

  1. No Android Studio, selecione 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. Ajuste o Package name para corresponder ao seu app.
  6. Selecione API 28:Android 9.0 (Pie) como Minimum SDK e clique em Next.

    Todos os carros compatíveis com o Android Automotive OS executam o Android 9 (API de nível 28) ou uma versão posterior. Portanto, a seleção desse valor abrange todos os carros que usam o Android Automotive OS.

  7. Você já tem um Serviço de navegação de mídia para o Android Auto, então, selecione Add No Activity e clique em Finish.

Examinar seu arquivo de manifesto

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

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

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

Você notará algumas informações padrão do app no elemento <application>, mas também verá que há um elemento <uses-feature> que declara compatibilidade com o Android Automotive OS. Observe que não há atividades declaradas no manifesto. Se seu app precisa delas, adicione uma atividade de configurações ou login, embora essas atividades sejam acionadas pelo sistema usando intents explícitos e sejam as únicas atividades a ser declaradas no manifesto do app para Android Automotive OS.

Atualizar suas dependências do Gradle

Recomendamos que você mantenha o serviço de navegação de mídia em um módulo diferente do que você compartilha entre o app para smartphones e o módulo automotivo. Se você estiver usando essa abordagem, precisará atualizar seu novo módulo automotivo para incluir o módulo compartilhado com o Serviço de navegação de mídia, conforme mostrado no seguinte snippet:

my-auto-module/build.gradle

    buildscript {
      ...
      dependencies {
        ...
        implementation project(':shared_module_name')
      }
    }
    

Implementar atividades de configurações e login no Android Automotive OS

Além do serviço de navegador de mídia, você também pode oferecer atividades de configurações e login otimizadas para veículos no seu app para Android Automotive OS. Essas atividades permitem oferecer funcionalidades de apps que não estão incluídas nas APIs de mídia do Android.

Adicionar uma atividade de configurações

Adicione uma atividade de configurações otimizada para veículos para que os usuários possam definir as configurações do seu app no carro. Sua atividade de configurações também pode fornecer outros fluxos de trabalho, como fazer login ou sair da conta de um usuário ou alternar entre contas.

Fluxos de trabalho da atividade de configurações

Sua atividade de configurações pode fornecer diferentes fluxos de trabalho ao usuário. A imagem a seguir mostra como um usuário interage com sua atividade de configurações usando o Android Automotive OS:

Fluxos de trabalho para uma atividade de configurações

Figura 1. Diagrama de fluxos de trabalho para uma atividade de configurações.

Declarar uma atividade de configurações

Declare sua atividade de configurações no arquivo de manifesto do seu app, conforme mostrado no snippet de código a seguir:

<application>
        ...
        <activity android:name=".AppSettingsActivity"
                  android:exported="true"
                  android:theme="@style/SettingsActivity"
                  android:label="@string/app_settings_activity_title">
            <intent-filter>
                <action android:name="android.intent.action.APPLICATION_PREFERENCES"/>
            </intent-filter>
        </activity>
        ...
    <application>
    

Implementar sua atividade de configurações

Quando um usuário inicia seu app, o Android Automotive OS detecta a atividade de configurações que você declarou e exibe uma affordance. O usuário pode selecionar essa affordance ou tocar nelausando o visor do carro para navegar para a atividade. O Android Automotive OS envia o intent ACTION_APPLICATION_PREFERENCES, que informa ao seu app para iniciar a atividade de configurações.

Adicionar uma atividade de login

Se seu app exigir que o usuário faça login para usá-lo, adicione uma atividade de login otimizada para veículos que gerencie o login e a saída do app. Você também pode adicionar fluxos de trabalho de login e saída a uma atividade de configurações, mas precisa usar uma atividade de login dedicada se o app não puder ser usado até que o usuário faça login.

Fluxo de trabalho da atividade de login

A imagem a seguir mostra como um usuário interage com sua atividade de login usando o Android Automotive OS:

Fluxos de trabalho para uma atividade de login

Figura 2. Diagrama de fluxos de trabalho para uma atividade de login.

Login obrigatório na inicialização do app

Para exigir que um usuário faça login usando sua atividade de login antes de poder usar o app, seu serviço de navegação de mídia precisa fazer o seguinte:

  1. Configurar o PlaybackState da sessão de mídia como STATE_ERROR usando o método setState(). Isso informa ao Android Automotive OS que nenhuma outra operação pode ser executada até que o erro seja resolvido.
  2. Configurar o código de erro do PlaybackState da sessão de mídia como ERROR_CODE_AUTHENTICATION_EXPIRED. Isso informa ao Android Automotive OS que o usuário precisa de autenticação.
  3. Definir a mensagem de erro do PlaybackState da sessão de mídia usando o método setErrorMessage(). Como essa mensagem de erro é voltada para o usuário, a mensagem precisa ser traduzida para a localidade dele.
  4. Definir os extras do PlaybackState da sessão de mídia usando o método setExtras(). Inclua as duas chaves a seguir:

    • android.media.extras.ERROR_RESOLUTION_ACTION_LABEL: string que é exibida no botão que inicia o fluxo de trabalho de login. Como essa string é voltada para o usuário, ela precisa ser traduzida para a localidade dele.
    • android.media.extras.ERROR_RESOLUTION_ACTION_INTENT: um PendingIntent que direciona o usuário para sua atividade de login quando ele toca no botão indicado por android.media.extras.ERROR_RESOLUTION_ACTION_LABEL.

O snippet de código a seguir mostra como seu app pode exigir que o usuário faça login antes de usá-lo:

Kotlin

    val signInIntent = Intent(this, SignInActivity::class.java)
    val signInActivityPendingIntent = PendingIntent.getActivity(this, 0,
        signInIntent, 0)
    val extras = Bundle().apply {
        putString(
            "android.media.extras.ERROR_RESOLUTION_ACTION_LABEL",
            "Sign in"
        )
        putParcelable(
            "android.media.extras.ERROR_RESOLUTION_ACTION_INTENT",
            signInActivityPendingIntent
        )
    }

    val playbackState = PlaybackStateCompat.Builder()
            .setState(PlaybackStateCompat.STATE_ERROR, 0, 0f)
            .setErrorMessage(
                PlaybackStateCompat.ERROR_CODE_AUTHENTICATION_EXPIRED,
                "Authentication required"
            )
            .setExtras(extras)
            .build()
    mediaSession.setPlaybackState(playbackState)
    

Java

    Intent signInIntent = new Intent(this, SignInActivity.class);
    PendingIntent signInActivityPendingIntent = PendingIntent.getActivity(this, 0,
        signInIntent, 0);
    Bundle extras = new Bundle();
    extras.putString(
        "android.media.extras.ERROR_RESOLUTION_ACTION_LABEL",
        "Sign in");
    extras.putParcelable(
        "android.media.extras.ERROR_RESOLUTION_ACTION_INTENT",
        signInActivityPendingIntent);

    PlaybackStateCompat playbackState = new PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR, 0, 0f)
        .setErrorMessage(
                PlaybackStateCompat.ERROR_CODE_AUTHENTICATION_EXPIRED,
                "Authentication required"
        )
        .setExtras(extras)
        .build();
    mediaSession.setPlaybackState(playbackState);
    

Depois que o usuário for autenticado, seu app definirá o PlaybackState para um estado diferente de STATE_ERROR e, em seguida, levar o usuário de volta ao Android Automotive OS chamando o método finish() da atividade.

Implementar a atividade de login

O Google oferece uma variedade de ferramentas de identidade que podem ser usadas para ajudar os usuários a fazer login no seu app no carro. Algumas ferramentas, como a Firebase Authentication, oferecem kits de ferramentas de pilha completa que podem ajudar a criar experiências de autenticação personalizadas. Outras ferramentas aproveitam as credenciais existentes de um usuário ou outras tecnologias para ajudar a criar experiências de login facilitadas para os usuários.

Recomendamos as seguintes ferramentas para ajudar a criar uma experiência de login mais fácil para usuários já conectados a outro dispositivo:

  • Login do Google: se você já tiver implementado o Login do Google em outros dispositivos (como o app para smartphones), também precisará implementá-lo no seu app para Android Automotive OS para oferecer compatibilidade com os usuários desse serviço.
  • Preenchimento automático do Google: se os usuários tiverem ativado o preenchimento automático do Google em outros dispositivos Android, as credenciais deles serão salvas no Gerenciador de senhas do Google. Em seguida, quando o usuário fizer login no seu app para Android Automotive OS, o preenchimento automático do Google sugerirá as credenciais salvas relevantes. O uso do preenchimento automático do Google não requer esforço de desenvolvimento de apps. No entanto, os desenvolvedores precisam otimizar os apps para ter resultados de qualidade melhores. O preenchimento automático do Google é compatível com todos os dispositivos que executam o Android Oreo 8.0 (API de nível 26) ou posterior (incluindo o Android Automotive OS).

Gerenciar ações de login protegidas

Alguns apps permitem que o usuário acesse algumas ações de forma anônima, mas exigem que ele faça login para poder executar outras ações. Por exemplo, um usuário pode tocar música em um app antes de fazer login, mas precisa entrar para poder pular uma música.

Nesse caso, quando o usuário tenta executar a ação restrita (pular uma música), seu app pode sugerir que ele se autentique emitindo um erro não fatal. Ao usar esse tipo de erro, o sistema exibe a mensagem para o usuário sem interromper a reprodução do item de mídia. Para implementar o gerenciamento de erros não fatais, realize as seguintes etapas:

  1. Configure o errorCode para o PlaybackState da sessão de mídia como ERROR_CODE_AUTHENTICATION_EXPIRED. Isso informa ao Android Automotive OS que o usuário precisa de autenticação.
  2. Mantenha o state do PlaybackState da sessão de mídia como está, não o configure como STATE_ERROR. Isso é o que informa ao sistema que o erro não é fatal.
  3. Defina os extras do PlaybackState da sessão de mídia usando o método setExtras(). Inclua as duas chaves a seguir:

    • android.media.extras.ERROR_RESOLUTION_ACTION_LABEL: string que é exibida no botão que inicia o fluxo de trabalho de login. Como essa string é voltada para o usuário, ela precisa ser traduzida para a localidade dele.
    • android.media.extras.ERROR_RESOLUTION_ACTION_INTENT: um PendingIntent que direciona o usuário para sua atividade de login quando ele toca no botão indicado por android.media.extras.ERROR_RESOLUTION_ACTION_LABEL.
  4. Mantenha o restante do estado PlaybackState da sessão de mídia como está. Isso permite que a reprodução do item de mídia atual continue enquanto o usuário decide se fará login ou não.

Testar seu app para Android Automotive OS

Você pode usar o Android Emulator para testar como seu app otimizado para o motorista é executado em uma tela de veículo do Android Automotive OS. Esta seção descreve como configurar um dispositivo virtual Android (AVD) que pode ser usado para testar seu app.

Editar suas configurações de execução

Apps para Automotive OS são diferentes de outros apps para Android. O Android Automotive OS interage com seu app usando intents explícitos e seu serviço de navegação de mídia.

Para testar o app, siga estas etapas para verificar se módulo automotivo foi configurado para não iniciar nenhuma atividade:

  1. No Android Studio, selecione Run > Edit Configurations.

    Caixa de diálogo de configurações "Run/Debug".

  2. Selecione seu módulo automotivo na lista de módulos do seu app.

  3. Em Launch Options > Launch, selecione Nothing.

  4. Clique em Apply e em OK.

Adicionar imagens do sistema

Antes de criar AVDs que correspondam a hardware específico de fabricantes, é necessário adicionar imagens do sistema a esses dispositivos por meio do SDK Manager do Android Studio. Então, ao criar um AVD, você poderá fazer o download dessas imagens do sistema para usar com ele.

Siga as etapas a seguir para adicionar uma imagem do sistema para o Polestar 2:

  1. No Android Studio, selecione Tools > SDK Manager.
  2. Clique na guia SDK Update Sites.
  3. Clique em Add Ícone de Add.
  4. Digite o seguinte nos campos Name e URL e clique em OK:

    Name: Polestar 2 System Image

    URL: https://developer.polestar.com/sdk/polestar2-sys-img.xml

  5. Clique em Apply e em OK.

Criar um AVD de carro e executar o emulador

Siga as etapas a seguir para criar um dispositivo virtual Android (AVD) que represente um veículo com Android Automotive OS e use esse AVD para executar o emulador:

  1. No Android Studio, selecione Tools > SDK Manager.
  2. Clique em Create Virtual Device.
  3. Na caixa de diálogo Select Hardware, selecione Automotive, escolha um dispositivo e clique em Next.
  4. Selecione uma imagem do sistema segmentada para o Automotive, como Android 9.0 (Automotive), e clique em Next.
  5. Crie um nome para seu AVD, selecione outras opções que quiser personalizar e clique em Finish.
  6. Na barra de ferramentas da janela, selecione seu AVD do Android Automotive OS como destino de implantação.
  7. Clique em Run Ícone de Run.