Usar a biblioteca Android for Cars App

A biblioteca Android for Cars App permite levar seus apps de navegação, ponto de interesse (PDI) e Internet das Coisas (IoT) para o carro. Ela faz isso fornecendo um conjunto de modelos projetados para atender aos padrões de distração do motorista e cuidando de detalhes como a variedade de fatores da tela do carro e modalidades de entrada.

Este guia fornece uma visão geral dos principais recursos e conceitos da biblioteca e apresenta o processo de configuração de um app básico.

Codelab

Aprenda os conceitos básicos da biblioteca Car App

arrow_forward

Antes de começar

1. Consulte as páginas de Design para direção que abordam a biblioteca Car App
   • Visões gerais das categorias de apps de navegação e Outros apps relacionados a condução
   • Visão geral de Criar apps com modelos
   • Elementos básicos que abrangem Modelos e Componentes de modelo
   • Fluxos de amostra que demonstram padrões comuns de UX
   • Requisitos de apps baseados em modelos
2. Revise os principais termos e conceitos na seção a seguir.
3. Familiarize-se com a interface do sistema Android Auto e o design do Android Automotive OS.
4. Leia as Notas da versão.
5. Analise os Exemplos (link em inglês).

Principais termos e conceitos

Estilos e modelos

A interface do usuário é representada por um gráfico de objetos de modelo que podem ser organizados de maneiras diferentes, conforme permitido pelo modelo a que pertencem. Os modelos são um subconjunto dos modelos que podem atuar como raiz nesses gráficos. Os modelos incluem as informações a serem exibidas para o usuário na forma de texto e imagens, bem como atributos para configurar aspectos da aparência visual dessas informações, por exemplo, cores de texto ou tamanhos de imagens. O host converte os modelos em visualizações projetadas para atender aos padrões de distração do motorista e cuida de detalhes como a variedade de fatores da tela do carro e as modalidades de entrada.

Host

O host é o componente de back-end que implementa a funcionalidade oferecida pelas APIs da biblioteca para que seu app possa ser executado no carro. As responsabilidades do host variam desde descobrir o app e gerenciar o ciclo de vida dele até converter seus modelos em visualizações e notificar o app sobre interações do usuário. Em dispositivos móveis, esse host é implementado pelo Android Auto. No Android Automotive OS, esse host é instalado como um app do sistema.

Restrições de modelos

Diferentes modelos impõem restrições ao conteúdo dos estilos principais. Por exemplo, modelos de lista têm limites quanto ao número de itens que podem ser apresentados ao usuário. Os modelos também têm restrições quanto à maneira de se conectar para formar o fluxo de uma tarefa. Por exemplo, o app só pode enviar até cinco modelos para a pilha de telas. Consulte Restrições de modelo para mais detalhes.

Screen

Screen é uma classe fornecida pela biblioteca que os apps implementam para gerenciar a interface do usuário apresentada ao usuário. Um Screen tem um ciclo de vida e fornece o mecanismo para que o app envie o modelo para exibição quando a tela estiver visível. As instâncias Screen também podem ser enviadas e retiradas de uma pilha Screen, o que garante que elas sigam as restrições de fluxo de modelo.

CarAppService

CarAppService é uma classe Service abstrata que o app precisa implementar e exportar para ser descoberto e gerenciado pelo host. O CarAppService do app é responsável por validar que uma conexão de host é confiável usando createHostValidator e, em seguida, fornecer instâncias Session para cada conexão usando onCreateSession.

Session

Session é uma classe abstrata que o app precisa implementar e retornar usando CarAppService.onCreateSession. Ele serve como ponto de entrada para mostrar informações na tela do carro. Ele tem um ciclo de vida que informa o estado atual do app na tela do carro, como quando ele está visível ou oculto.

Quando um Session é iniciado, por exemplo, quando o app é iniciado pela primeira vez, o host solicita que o Screen inicial seja mostrado usando o método onCreateScreen.

Instalar a biblioteca Car App

Consulte a página de lançamento da biblioteca do Jetpack para instruções sobre como adicionar a biblioteca ao seu app.

Configurar os arquivos de manifesto do app

Antes de criar seu app para carro, configure os arquivos de manifesto dele da seguinte maneira.

Declarar o CarAppService

O host se conecta ao app usando a implementação do CarAppService. Declare esse serviço no manifesto para permitir que o host descubra e se conecte ao app.

Também é necessário declarar a categoria do app no elemento <category> do filtro de intent. Veja a lista de categorias de apps compatíveis para os valores permitidos para esse elemento.

O snippet de código abaixo mostra como declarar um serviço de app para carros para um app de ponto de interesse no manifesto:

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService"/>
        <category android:name="androidx.car.app.category.POI"/>
      </intent-filter>
    </service>

    ...
<application>

Categorias de apps compatíveis

Declare a categoria do app adicionando um ou mais dos seguintes valores de categoria no filtro de intent ao declarar o CarAppService, conforme descrito na seção anterior:

• androidx.car.app.category.NAVIGATION: um app que fornece rotas de navegação guiada. Consulte Criar apps de navegação para carros para mais documentação sobre essa categoria.
• androidx.car.app.category.POI: um app que oferece funcionalidades relevantes para encontrar pontos de interesse, como vagas de estacionamento, postos de recarga e postos de gasolina. Consulte Criar apps de ponto de interesse para carros para mais documentação sobre essa categoria.
• androidx.car.app.category.IOT: um app que permite aos usuários realizar ações relevantes em dispositivos conectados de dentro do carro. Consulte Criar apps de Internet das Coisas para carros para mais documentação sobre essa categoria.

Consulte Qualidade do app Android para carros para descrições detalhadas de cada categoria e critério para que os apps pertençam a elas.

Especificar o nome e o ícone do aplicativo

Especifique o nome e o ícone do app que o host pode usar para representar seu app na IU do sistema.

Você pode especificar o nome e o ícone do app usados para representá-lo usando os atributos label e icon da CarAppService:

...
<service
   android:name=".MyCarAppService"
   android:exported="true"
   android:label="@string/my_app_name"
   android:icon="@drawable/my_app_icon">
   ...
</service>
...

Se o rótulo ou o ícone não forem declarados no elemento <service>, o host vai usar os valores especificados para o elemento <application>.

Definir um tema personalizado

Para definir um tema personalizado para o app para carro, adicione um elemento <meta-data> ao arquivo de manifesto da seguinte maneira:

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

Em seguida, declare seu recurso de estilo para definir os seguintes atributos do tema personalizado do app para carro:

<resources>
  <style name="MyCarAppTheme">
    <item name="carColorPrimary">@layout/my_primary_car_color</item>
    <item name="carColorPrimaryDark">@layout/my_primary_dark_car_color</item>
    <item name="carColorSecondary">@layout/my_secondary_car_color</item>
    <item name="carColorSecondaryDark">@layout/my_secondary_dark_car_color</item>
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

Nível da API Car App

A biblioteca Car App define os próprios níveis de API para que você saiba quais recursos da biblioteca oferecem suporte ao host de modelo em um veículo. Para extrair o nível mais alto da API Car App com suporte de um host, use o método getCarAppApiLevel().

Declare o nível mínimo da API Car App com suporte do app no arquivo AndroidManifest.xml:

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

Consulte a documentação da anotação RequiresCarApi para conferir detalhes sobre como manter a compatibilidade com versões anteriores e declarar o nível mínimo de API necessário para usar um recurso. Para conferir uma definição de qual nível de API é necessário para usar um determinado recurso da biblioteca Car App, consulte a documentação de referência de CarAppApiLevels.

Criar CarAppService e Session

Seu app precisa estender a classe CarAppService e implementar o método onCreateSession, que retorna uma instância Session correspondente à conexão atual com o host:

class HelloWorldService : CarAppService() {
    ...
    override fun onCreateSession(): Session {
        return HelloWorldSession()
    }
    ...
}

public final class HelloWorldService extends CarAppService {
    ...
    @Override
    @NonNull
    public Session onCreateSession() {
        return new HelloWorldSession();
    }
    ...
}

A instância Session é responsável por retornar a instância Screen para usar na primeira vez que o app for iniciado:

class HelloWorldSession : Session() {
    ...
    override fun onCreateScreen(intent: Intent): Screen {
        return HelloWorldScreen(carContext)
    }
    ...
}

public final class HelloWorldSession extends Session {
    ...
    @Override
    @NonNull
    public Screen onCreateScreen(@NonNull Intent intent) {
        return new HelloWorldScreen(getCarContext());
    }
    ...
}

Para lidar com cenários em que o app para carro precisa ser iniciado em uma tela que não seja a inicial ou de destino do app, como processar links diretos, é possível predefinir uma backstack de telas usando ScreenManager.push antes de retornar de onCreateScreen. A pré-busca permite que os usuários naveguem de volta para as telas anteriores pela primeira tela que seu app está exibindo.

Criar a tela inicial

Para criar as telas mostradas pelo app, defina classes que estendem a classe Screen e implemente o método onGetTemplate, que retorna a instância Template que representa o estado da interface a ser mostrado na tela do carro.

O snippet abaixo mostra como declarar um Screen que usa um modelo PaneTemplate para exibir uma string "Hello world!" simples:

class HelloWorldScreen(carContext: CarContext) : Screen(carContext) {
    override fun onGetTemplate(): Template {
        val row = Row.Builder().setTitle("Hello world!").build()
        val pane = Pane.Builder().addRow(row).build()
        return PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build()
    }
}

public class HelloWorldScreen extends Screen {
    @NonNull
    @Override
    public Template onGetTemplate() {
        Row row = new Row.Builder().setTitle("Hello world!").build();
        Pane pane = new Pane.Builder().addRow(row).build();
        return new PaneTemplate.Builder(pane)
            .setHeaderAction(Action.APP_ICON)
            .build();
    }
}

Classe CarContext

A classe CarContext é uma subclasse da ContextWrapper acessível às instâncias Session e Screen. Ela fornece acesso a serviços do carro, como o ScreenManager, para gerenciar a pilha de telas; o AppManager para funcionalidades gerais relacionadas ao app, como acessar o objeto Surface para desenhar mapas; e o NavigationManager usado por apps de navegação passo a passo para comunicar metadados de navegação e outros metadados de navegação.

Consulte Acessar os modelos de navegação para uma lista abrangente de funcionalidades da biblioteca disponíveis para apps de navegação.

O CarContext também oferece outras funcionalidades, como permitir que você carregue recursos drawable usando a configuração da tela do carro, inicie um app no carro usando intents e sinalize se o app precisa exibir o mapa no tema escuro.

Implementar a navegação na tela

Geralmente, os apps apresentam várias telas diferentes, cada uma possivelmente usando modelos diferentes em que o usuário pode navegar à medida que interage com a interface mostrada na tela.

A classe ScreenManager fornece uma pilha de tela que pode ser usada para enviar telas que podem ser exibidas automaticamente quando o usuário seleciona um botão "Voltar" na tela do carro ou usa o botão "Voltar" do hardware disponível em alguns carros.

O snippet a seguir mostra como adicionar uma ação de retorno a um modelo de mensagem, bem como uma ação que envia uma nova tela quando selecionado pelo usuário:

val template = MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener { screenManager.push(NextScreen(carContext)) }
            .build())
    .build()

MessageTemplate template = new MessageTemplate.Builder("Hello world!")
    .setHeaderAction(Action.BACK)
    .addAction(
        new Action.Builder()
            .setTitle("Next screen")
            .setOnClickListener(
                () -> getScreenManager().push(new NextScreen(getCarContext())))
            .build())
    .build();

O objeto Action.BACK é uma Action padrão que invoca automaticamente ScreenManager.pop. Esse comportamento pode ser substituído usando a instância OnBackPressedDispatcher disponível em CarContext.

Para garantir que o app seja seguro para usar enquanto dirige, a pilha de telas pode ter uma profundidade máxima de cinco telas. Consulte a seção Restrições de modelo para mais detalhes.

Atualizar o conteúdo de um modelo

Seu app pode solicitar que o conteúdo de uma Screen seja invalidado chamando o método Screen.invalidate. Em seguida, o host vai chamar o método Screen.onGetTemplate do app para extrair o modelo com o novo conteúdo.

Ao atualizar um Screen, é importante entender o conteúdo específico no modelo que pode ser atualizado para que o host não contabilize o novo modelo na cota. Consulte a seção Restrições de modelo para mais detalhes.

Recomendamos estruturar as telas para que haja um mapeamento um para um entre um Screen e o tipo de modelo que ele retorna usando a implementação de onGetTemplate.

Desenhar mapas

Os apps de navegação e ponto de interesse (PDIs) que usam os modelos abaixo podem desenhar mapas acessando uma Surface:

Declarar a permissão de superfície

Além da permissão necessária para o modelo que seu app está usando, ele precisa declarar a permissão androidx.car.app.ACCESS_SURFACE no arquivo AndroidManifest.xml para ter acesso à plataforma:

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

Acessar a superfície

Para acessar o Surface fornecido pelo host, implemente um SurfaceCallback e forneça essa implementação ao serviço de carro AppManager. O Surface atual é transmitido para o SurfaceCallback no parâmetro SurfaceContainer dos callbacks onSurfaceAvailable() e onSurfaceDestroyed().

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

Entender a área visível da superfície

O host pode desenhar elementos da interface do usuário para os modelos na parte de cima do mapa. O host comunica a área da superfície que certamente não estará obstruída e totalmente visível para o usuário, chamando o método SurfaceCallback.onVisibleAreaChanged. Além disso, para minimizar o número de mudanças, ele chama o método SurfaceCallback.onStableAreaChanged com o menor retângulo, que sempre fica visível com base no modelo atual.

Por exemplo, quando um app de navegação usa a NavigationTemplate com uma faixa de ação na parte de cima, essa faixa pode ficar oculta quando o usuário não interage com a tela há algum tempo, liberando mais espaço para o mapa. Nesse caso, há um callback para onStableAreaChanged e onVisibleAreaChanged com o mesmo retângulo. Quando a faixa de ação está oculta, somente onVisibleAreaChanged é chamado com a área maior. Se o usuário interagir com a tela, novamente apenas onVisibleAreaChanged será chamado com o primeiro retângulo.

Oferecer suporte ao tema escuro

Os apps precisam redesenhar o mapa na instância de Surface com as cores escuras adequadas quando o host determinar que as condições justificam isso, conforme descrito em Qualidade do app Android para carros.

Para decidir se você precisa desenhar um mapa escuro, use o método CarContext.isDarkMode. Sempre que o status do tema escuro mudar, você vai receber uma chamada para Session.onCarConfigurationChanged.

Permitir que os usuários interajam com o mapa

Ao usar os modelos a seguir, é possível adicionar suporte para que os usuários interajam com os mapas que você desenhar, por exemplo, permitindo que eles vejam diferentes partes de um mapa, aplicando zoom e movimentando.

Implementar callbacks de interatividade

A interface SurfaceCallback tem vários métodos de callback que podem ser implementados para adicionar interatividade aos mapas criados com os modelos da seção anterior:

Adicionar uma faixa de ações no mapa

Esses modelos podem ter uma faixa de ações no mapa para ações relacionadas ao mapa, como aumentar e diminuir o zoom, recentralizar, mostrar uma bússola e outras ações que você escolher mostrar. A faixa de ações no mapa pode ter até quatro botões somente de ícones que podem ser atualizados sem afetar a profundidade da tarefa. Ela fica oculta no estado inativo e reaparece no estado ativo.

Para receber callbacks de interatividade do mapa, é necessário adicionar um botão Action.PAN à faixa de ações no mapa. Quando o usuário pressiona o botão correspondente, o host entra no modo de movimentação, conforme descrito na seção a seguir.

Se o app omitir o botão Action.PAN na faixa de ações, ele não vai receber entradas do usuário dos métodos SurfaceCallback, e o host sairá de modos de movimentação ativados anteriormente.

Em uma tela touchscreen, o botão de movimentação não é mostrado.

Entender o modo de movimentação

No modo de movimentação, o host do modelo converte a entrada do usuário de dispositivos de entrada sem toque, como controles giratórios e touchpads, em métodos SurfaceCallback adequados. Responda à ação do usuário para entrar ou sair do modo de movimentação com o método setPanModeListener no NavigationTemplate.Builder. O host poderá ocultar outros componentes de interface no modelo enquanto o usuário estiver no modo de movimentação.

Interagir com o usuário

Seu app pode interagir com o usuário usando padrões semelhantes aos de um app para dispositivos móveis.

Processar entrada do usuário

Seu app pode responder à entrada do usuário transmitindo os listeners adequados aos estilos compatíveis. O snippet abaixo mostra como criar um modelo de Action que define um OnClickListener que chama um método definido pelo código do app:

val action = Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(::onClickNavigate)
    .build()

Action action = new Action.Builder()
    .setTitle("Navigate")
    .setOnClickListener(this::onClickNavigate)
    .build();

O método onClickNavigate pode iniciar o app de navegação padrão para carro usando o método CarContext.startCarApp:

private fun onClickNavigate() {
    val intent = Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address))
    carContext.startCarApp(intent)
}

private void onClickNavigate() {
    Intent intent = new Intent(CarContext.ACTION_NAVIGATE, Uri.parse("geo:0,0?q=" + address));
    getCarContext().startCarApp(intent);
}

Para saber mais sobre como iniciar apps, incluindo o formato da intent ACTION_NAVIGATE, consulte a seção Iniciar um app para carro com uma intent.

Algumas ações, como as que exigem direcionar o usuário para continuar a interação nos dispositivos móveis, são permitidas apenas quando o carro está parado. Você pode usar o ParkedOnlyOnClickListener para implementar essas ações. Se o carro não estiver estacionado, o host vai mostrar uma indicação ao usuário de que a ação não é permitida nesse caso. Com o carro estacionado, o código é executado normalmente. O snippet a seguir mostra como usar o ParkedOnlyOnClickListener para abrir uma tela de configurações no dispositivo móvel:

val row = Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(::openSettingsOnPhone))
    .build()

Row row = new Row.Builder()
    .setTitle("Open Settings")
    .setOnClickListener(ParkedOnlyOnClickListener.create(this::openSettingsOnPhone))
    .build();

Mostrar notificações

As notificações enviadas ao dispositivo móvel só vão aparecer na tela do carro se forem estendidas com um CarAppExtender. Alguns atributos de notificação, como título, texto, ícone e ações do conteúdo, podem ser definidos no CarAppExtender, substituindo os atributos da notificação quando eles aparecem na tela do carro.

O snippet a seguir mostra como enviar uma notificação para a tela do carro com um título diferente daquele exibido no dispositivo móvel:

val notification = NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build()

Notification notification = new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setContentTitle(titleOnThePhone)
    .extend(
        new CarAppExtender.Builder()
            .setContentTitle(titleOnTheCar)
            ...
            .build())
    .build();

As notificações podem afetar as seguintes partes da interface do usuário:

• Uma notificação de alerta (HUN, sigla em inglês) poderá ser exibida para o usuário.
• É possível adicionar uma entrada à central de notificações, com a opção de um ícone visível na coluna.
• Para apps de navegação, a notificação pode ser mostrada no widget de coluna, conforme descrito em Notificações de navegação guiada.

Você pode escolher como configurar as notificações do app para que afetem cada um desses elementos da interface do usuário usando a prioridade da notificação, conforme descrito na documentação CarAppExtender.

Se NotificationCompat.Builder.setOnlyAlertOnce for chamado com um valor true, uma notificação de alta prioridade vai ser mostrada como HUN apenas uma vez.

Para saber mais sobre como projetar as notificações do seu app para carro, consulte o guia do Google Design para direção sobre notificações.

Mostrar avisos

Seu app pode exibir um aviso usando CarToast, conforme mostrado neste snippet:

CarToast.makeText(carContext, "Hello!", CarToast.LENGTH_SHORT).show()

CarToast.makeText(getCarContext(), "Hello!", CarToast.LENGTH_SHORT).show();

Solicitar permissões

Caso o app precise acessar dados ou ações restritos, como localização, as regras padrão de permissões do Android serão aplicadas. Para solicitar uma permissão, use o método CarContext.requestPermissions().

A vantagem de usar CarContext.requestPermissions(), em vez de usar APIs padrão do Android, é que você não precisa iniciar seu próprio Activity para criar a caixa de diálogo de permissões. Além disso, você pode usar o mesmo código no Android Auto e no Android Automotive OS, em vez de criar fluxos dependentes da plataforma.

Definir o estilo da caixa de diálogo de permissões no Android Auto

No Android Auto, a caixa de diálogo de permissões do usuário será exibida no smartphone. Por padrão, não haverá nenhum plano de fundo atrás da caixa de diálogo. Para definir um segundo plano personalizado, declare um tema de app para carros no arquivo AndroidManifest.xml e defina o atributo carPermissionActivityLayout para o tema do app para carro.

<meta-data
    android:name="androidx.car.app.theme"
    android:resource="@style/MyCarAppTheme />

Em seguida, defina o atributo carPermissionActivityLayout para o tema do app para carro:

<resources>
  <style name="MyCarAppTheme">
    <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
  </style>
</resources>

Iniciar um app para carro com uma intent

É possível chamar o método CarContext.startCarApp para realizar uma das seguintes ações:

• Abrir o discador para fazer uma chamada telefônica
• Inicie a navegação guiada até um local com o app padrão de navegação para carro.
• Iniciar seu app com uma intent

O exemplo a seguir mostra como criar uma notificação com uma ação que abre seu app com uma tela que mostra os detalhes de uma reserva de estacionamento. Amplie a instância de notificação com uma intent de conteúdo que contenha uma PendingIntent que envolve uma intent explícita para a ação do app:

val notification = notificationBuilder
    ...
    .extend(
        CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(ComponentName(context, MyNotificationReceiver::class.java)),
                    0))
            .build())

Notification notification = notificationBuilder
    ...
    .extend(
        new CarAppExtender.Builder()
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_VIEW_PARKING_RESERVATION.hashCode(),
                    new Intent(ACTION_VIEW_PARKING_RESERVATION)
                        .setComponent(new ComponentName(context, MyNotificationReceiver.class)),
                    0))
            .build());

Seu app também precisa declarar uma BroadcastReceiver que é invocada para processar a intent quando o usuário seleciona a ação na interface de notificação e invoca CarContext.startCarApp com uma intent que inclui o URI de dados:

class MyNotificationReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val intentAction = intent.action
        if (ACTION_VIEW_PARKING_RESERVATION == intentAction) {
            CarContext.startCarApp(
                intent,
                Intent(Intent.ACTION_VIEW)
                    .setComponent(ComponentName(context, MyCarAppService::class.java))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)))
        }
    }
}

public class MyNotificationReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        String intentAction = intent.getAction();
        if (ACTION_VIEW_PARKING_RESERVATION.equals(intentAction)) {
            CarContext.startCarApp(
                intent,
                new Intent(Intent.ACTION_VIEW)
                    .setComponent(new ComponentName(context, MyCarAppService.class))
                    .setData(Uri.fromParts(MY_URI_SCHEME, MY_URI_HOST, intentAction)));
        }
    }
}

Por fim, o método Session.onNewIntent no seu app processa essa intent enviando a tela de reserva de estacionamento à pilha, se ela ainda não estiver no topo:

override fun onNewIntent(intent: Intent) {
    val screenManager = carContext.getCarService(ScreenManager::class.java)
    val uri = intent.data
    if (uri != null
        && MY_URI_SCHEME == uri.scheme
        && MY_URI_HOST == uri.schemeSpecificPart
        && ACTION_VIEW_PARKING_RESERVATION == uri.fragment
    ) {
        val top = screenManager.top
        if (top !is ParkingReservationScreen) {
            screenManager.push(ParkingReservationScreen(carContext))
        }
    }
}

@Override
public void onNewIntent(@NonNull Intent intent) {
    ScreenManager screenManager = getCarContext().getCarService(ScreenManager.class);
    Uri uri = intent.getData();
    if (uri != null
        && MY_URI_SCHEME.equals(uri.getScheme())
        && MY_URI_HOST.equals(uri.getSchemeSpecificPart())
        && ACTION_VIEW_PARKING_RESERVATION.equals(uri.getFragment())
    ) {
        Screen top = screenManager.getTop();
        if (!(top instanceof ParkingReservationScreen)) {
            screenManager.push(new ParkingReservationScreen(getCarContext()));
        }
    }
}

Consulte a seção Mostrar notificações para mais informações sobre como processar notificações do app para carro.

Restrições de modelos

O host limita o número de modelos a serem exibidos para uma determinada tarefa a um máximo de cinco, sendo que o último modelo precisa ser de um dos seguintes tipos:

• NavigationTemplate
• PaneTemplate
• MessageTemplate

Observe que esse limite se aplica ao número de modelos e não ao número de instâncias de Screen na pilha. Por exemplo, se um app enviar dois modelos enquanto estiver na tela A e depois enviar a tela B, ele poderá enviar mais três modelos. Como alternativa, se cada tela estiver estruturada para enviar um único modelo, o app poderá enviar cinco instâncias de tela para a pilha ScreenManager.

Há casos especiais para essas restrições: atualizações de modelos e operações de retorno e redefinição.

Atualizações de modelos

Algumas atualizações de conteúdo não são contabilizadas no limite de modelos. Em geral, se um app envia um novo modelo do mesmo tipo e com o mesmo conteúdo principal do anterior, o novo modelo não é contabilizado na cota. Por exemplo, a atualização do estado de alternância de uma linha em um ListTemplate não é considerada na cota. Consulte a documentação de modelos individuais para saber mais sobre quais tipos de atualizações de conteúdo podem ser considerados uma atualização.

Operações de retorno

Para ativar subfluxos em uma tarefa, o host detecta quando um app está exibindo um Screen da pilha ScreenManager e atualiza a cota restante com base no número de modelos que o app está recuando.

Por exemplo, se o app envia dois modelos enquanto está na tela A, depois envia a tela B e mais dois modelos, o app tem uma cota restante. Se o app voltar para a tela A, o host redefinirá a cota para três, porque o app voltou dois modelos.

Ao voltar para uma tela, o app precisa enviar um modelo do mesmo tipo que o último enviado por essa tela. O envio de qualquer outro tipo de modelo causa um erro. Porém, contanto que o tipo permaneça o mesmo durante uma operação de retorno, um aplicativo poderá modificar livremente o conteúdo do modelo sem afetar a cota.

Redefinir operações

Alguns modelos têm uma semântica especial que representa o final de uma tarefa. Por exemplo, o NavigationTemplate é uma visualização que precisa permanecer na tela e ser atualizada com novas instruções passo a passo para o consumo do usuário. Quando atinge um desses modelos, o host redefine a cota do modelo, tratando esse modelo como se fosse a primeira etapa de uma nova tarefa. Isso permite que o app inicie uma nova tarefa. Consulte a documentação de modelos individuais para ver quais deles acionam uma redefinição no host.

Se o host receber uma intent para iniciar o app por uma ação de notificação ou pela tela de início, a cota também será redefinida. Esse mecanismo permite que um app inicie um novo fluxo de tarefas pelas notificações e funciona mesmo que um app já esteja vinculado e em primeiro plano.

Consulte a seção Mostrar notificações para mais detalhes sobre como mostrar as notificações do app na tela do carro. Consulte a seção Iniciar um app para carro com uma intent para informações sobre como iniciar o app por uma ação de notificação.

API Connection

Você pode determinar se o app está sendo executado no Android Auto ou no Android Automotive OS usando a API CarConnection para recuperar informações de conexão no momento da execução.

Por exemplo, no Session do app para carro, inicialize um CarConnection e inscreva-se para receber atualizações de LiveData:

CarConnection(carContext).type.observe(this, ::onConnectionStateUpdated)

new CarConnection(getCarContext()).getType().observe(this, this::onConnectionStateUpdated);

No observador, é possível reagir às mudanças no estado da conexão:

fun onConnectionStateUpdated(connectionState: Int) {
  val message = when(connectionState) {
    CarConnection.CONNECTION_TYPE_NOT_CONNECTED -> "Not connected to a head unit"
    CarConnection.CONNECTION_TYPE_NATIVE -> "Connected to Android Automotive OS"
    CarConnection.CONNECTION_TYPE_PROJECTION -> "Connected to Android Auto"
    else -> "Unknown car connection type"
  }
  CarToast.makeText(carContext, message, CarToast.LENGTH_SHORT).show()
}

private void onConnectionStateUpdated(int connectionState) {
  String message;
  switch(connectionState) {
    case CarConnection.CONNECTION_TYPE_NOT_CONNECTED:
      message = "Not connected to a head unit";
      break;
    case CarConnection.CONNECTION_TYPE_NATIVE:
      message = "Connected to Android Automotive OS";
      break;
    case CarConnection.CONNECTION_TYPE_PROJECTION:
      message = "Connected to Android Auto";
      break;
    default:
      message = "Unknown car connection type";
      break;
  }
  CarToast.makeText(getCarContext(), message, CarToast.LENGTH_SHORT).show();
}

API Constraints

Carros diferentes podem permitir que um número diferente de instâncias de Item seja mostrado ao usuário por vez. Use o ConstraintManager para verificar o limite de conteúdo no momento da execução e definir o número adequado de itens nos modelos.

Comece recebendo um ConstraintManager do CarContext:

val manager = carContext.getCarService(ConstraintManager::class.java)

ConstraintManager manager = getCarContext().getCarService(ConstraintManager.class);

Em seguida, consulte o objeto ConstraintManager recuperado para saber o limite de conteúdo relevante. Por exemplo, para saber o número de itens que podem ser mostrados em uma grade, chame getContentLimit com CONTENT_LIMIT_TYPE_GRID:

val gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID)

int gridItemLimit = manager.getContentLimit(ConstraintManager.CONTENT_LIMIT_TYPE_GRID);

Adicionar um fluxo de login

Se o app oferecer uma experiência de login aos usuários, você poderá usar modelos como SignInTemplate e LongMessageTemplate com a API Car App de nível 2 e mais recentes para processar o login no app na unidade principal do carro.

Para criar um SignInTemplate, defina um SignInMethod. Atualmente, a biblioteca Car App oferece suporte aos seguintes métodos de login:

• InputSignInMethod para o login com nome de usuário/senha.
• PinSignInMethod para login com PIN, em que o usuário vincula a conta pelo smartphone usando um PIN mostrado na unidade principal.
• ProviderSignInMethod para login do provedor, como o Login do Google e o um toque.
• QRCodeSignInMethod para login com um QR code, em que o usuário lê um QR code para concluir o login no smartphone. Esse recurso está disponível no nível 4 da API Car e em versões mais recentes.

Por exemplo, para implementar um modelo que colete a senha do usuário, comece criando um InputCallback para processar e validar a entrada do usuário:

val callback = object : InputCallback {
    override fun onInputSubmitted(text: String) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    override fun onInputTextChanged(text: String) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
}

InputCallback callback = new InputCallback() {
    @Override
    public void onInputSubmitted(@NonNull String text) {
        // You will receive this callback when the user presses Enter on the keyboard.
    }

    @Override
    public void onInputTextChanged(@NonNull String text) {
        // You will receive this callback as the user is typing. The update
        // frequency is determined by the host.
    }
};

É necessário um InputCallback para o InputSignInMethod Builder.

val passwordInput = InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build()

InputSignInMethod passwordInput = new InputSignInMethod.Builder(callback)
    .setHint("Password")
    .setInputType(InputSignInMethod.INPUT_TYPE_PASSWORD)
    ...
    .build();

Por fim, use o novo InputSignInMethod para criar um SignInTemplate.

SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build()

new SignInTemplate.Builder(passwordInput)
    .setTitle("Sign in with username and password")
    .setInstructions("Enter your password")
    .setHeaderAction(Action.BACK)
    ...
    .build();

Usar o AccountManager

Os apps Android Automotive OS que têm autenticação precisam usar o AccountManager pelos seguintes motivos:

• Melhor UX e gerenciamento de contas facilitado: os usuários podem gerenciar facilmente todas as contas no menu de contas nas configurações do sistema, incluindo o login e o logout.
• Experiências de"convidado": como os carros são dispositivos compartilhados, os OEMs podem ativar experiências para visitantes no veículo, quando não é possível adicionar contas.

Adicionar variantes de string de texto

Tamanhos de tela de carro diferentes podem mostrar quantidades distintas de texto. Com a API Car App nível 2 e mais recentes, é possível especificar múltiplas variantes de uma string de texto para se adequar melhor à tela. Para ver onde as variantes de texto são aceitas, procure modelos e componentes que usem um CarText.

Você pode adicionar variantes de string de texto a um CarText com o método CarText.Builder.addVariant():

val itemTitle = CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build()

CarText itemTitle = new CarText.Builder("This is a very long string")
    .addVariant("Shorter string")
    ...
    .build();

Você pode usar esse CarText, por exemplo, como o texto principal de uma GridItem.

GridItem.Builder()
    .addTitle(itemTitle)
    ...
    .build()

new GridItem.Builder()
    .addTitle(itemTitle)
    ...
    build();

Adicione strings em ordem da mais para a menos preferida, por exemplo, da mais longa para a mais curta. O host escolhe a string de tamanho adequado dependendo da quantidade de espaço disponível na tela do carro.

Adicionar CarIcons inline para linhas.

Você pode adicionar ícones inline com texto para melhorar o apelo visual do app usando CarIconSpan. Consulte a documentação de CarIconSpan.create para mais informações sobre como criar esses períodos. Consulte Estilização de texto Spantastic com períodos para ter uma visão geral de como funciona o estilo de texto com períodos.

  
val rating = SpannableString("Rating: 4.5 stars")
rating.setSpan(
    CarIconSpan.create(
        // Create a CarIcon with an image of four and a half stars
        CarIcon.Builder(...).build(),
        // Align the CarIcon to the baseline of the text
        CarIconSpan.ALIGN_BASELINE
    ),
    // The start index of the span (index of the character '4')
    8,
    // The end index of the span (index of the last 's' in "stars")
    16,
    Spanned.SPAN_INCLUSIVE_INCLUSIVE
)

val row = Row.Builder()
    ...
    .addText(rating)
    .build()
  
  

  
SpannableString rating = new SpannableString("Rating: 4.5 stars");
rating.setSpan(
        CarIconSpan.create(
                // Create a CarIcon with an image of four and a half stars
                new CarIcon.Builder(...).build(),
                // Align the CarIcon to the baseline of the text
                CarIconSpan.ALIGN_BASELINE
        ),
        // The start index of the span (index of the character '4')
        8,
        // The end index of the span (index of the last 's' in "stars")
        16,
        Spanned.SPAN_INCLUSIVE_INCLUSIVE
);
Row row = new Row.Builder()
        ...
        .addText(rating)
        .build();
  
  

APIs de hardware do carro

No nível 3 da API Car App, a biblioteca Car App tem APIs que podem ser usadas para acessar propriedades e sensores do veículo.

Requisitos

Para usar as APIs com o Android Auto, comece adicionando uma dependência em androidx.car.app:app-projected ao arquivo build.gradle do módulo do Android Auto. Para o Android Automotive OS, adicione uma dependência em androidx.car.app:app-automotive ao arquivo build.gradle do seu módulo do Android Automotive OS.

Além disso, no seu arquivo AndroidManifest.xml, você precisa declarar as permissões relevantes necessárias para solicitar os dados do carro que quer usar. Essas permissões também precisam ser concedidas pelo usuário. Você pode usar o mesmo código no Android Auto e no Android Automotive OS, em vez de criar fluxos dependentes da plataforma. No entanto, as permissões necessárias são diferentes.

Informações do carro

Esta tabela descreve as propriedades mostradas pelas APIs CarInfo e as permissões necessárias para solicitar o uso delas:

Por exemplo, para ver o intervalo restante, instancie um objeto CarInfo e crie e registre um OnCarDataAvailableListener:

val carInfo = carContext.getCarService(CarHardwareManager::class.java).carInfo

val listener = OnCarDataAvailableListener<EnergyLevel> { data ->
    if (data.rangeRemainingMeters.status == CarValue.STATUS_SUCCESS) {
      val rangeRemaining = data.rangeRemainingMeters.value
    } else {
      // Handle error
    }
  }

carInfo.addEnergyLevelListener(carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener)

CarInfo carInfo = getCarContext().getCarService(CarHardwareManager.class).getCarInfo();

OnCarDataAvailableListener<EnergyLevel> listener = (data) -> {
  if(data.getRangeRemainingMeters().getStatus() == CarValue.STATUS_SUCCESS) {
    float rangeRemaining = data.getRangeRemainingMeters().getValue();
  } else {
    // Handle error
  }
};

carInfo.addEnergyLevelListener(getCarContext().getMainExecutor(), listener);
…
// Unregister the listener when you no longer need updates
carInfo.removeEnergyLevelListener(listener);

Não presuma que os dados do carro estejam sempre disponíveis. Se você receber um erro, verifique o status do valor solicitado para entender melhor por que não foi possível recuperar os dados solicitados. Consulte a documentação de referência para conferir a definição completa da classe CarInfo.

Sensores do carro

A classe CarSensors dá acesso aos dados de acelerômetro, giroscópio, bússola e localização do veículo. A disponibilidade desses valores depende do OEM. O formato dos dados do acelerômetro, do giroscópio e da bússola é o mesmo da API SensorManager. Por exemplo, para verificar a direção do veículo:

val carSensors = carContext.getCarService(CarHardwareManager::class.java).carSensors

val listener = OnCarDataAvailableListener<Compass> { data ->
    if (data.orientations.status == CarValue.STATUS_SUCCESS) {
      val orientation = data.orientations.value
    } else {
      // Data not available, handle error
    }
  }

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, carContext.mainExecutor, listener)
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener)

CarSensors carSensors = getCarContext().getCarService(CarHardwareManager.class).getCarSensors();

OnCarDataAvailableListener<Compass> listener = (data) -> {
  if (data.getOrientations().getStatus() == CarValue.STATUS_SUCCESS) {
    List<Float> orientations = data.getOrientations().getValue();
  } else {
    // Data not available, handle error
  }
};

carSensors.addCompassListener(CarSensors.UPDATE_RATE_NORMAL, getCarContext().getMainExecutor(),
    listener);
…
// Unregister the listener when you no longer need updates
carSensors.removeCompassListener(listener);

Para acessar os dados de local do carro, também é necessário declarar e solicitar a permissão android.permission.ACCESS_FINE_LOCATION.

Testes

Para simular dados do sensor durante testes no Android Auto, consulte as seções Sensores e Configuração do sensor do guia da unidade principal do computador. Para simular dados do sensor ao testar no Android Automotive OS, consulte a seção Emular estado de hardware do guia do emulador do Android Automotive OS.

Ciclos de vida de CarAppService, Session e Screen

As classes Session e Screen implementam a interface LifecycleOwner. À medida que o usuário interage com o app, os callbacks do ciclo de vida dos objetos Session e Screen são invocados, conforme descrito nos diagramas a seguir.

Os ciclos de vida de CarAppService e Session

Para ver todos os detalhes, consulte a documentação do método Session.getLifecycle.

O ciclo de vida de Screen

Para ver todos os detalhes, consulte a documentação do método Screen.getLifecycle.

Gravar do microfone do carro

Usando o CarAppService do app e a API CarAudioRecord, é possível conceder ao app acesso ao microfone do carro do usuário. Os usuários precisam dar permissão ao app para acessar o microfone do carro. Seu app pode gravar e processar a entrada do usuário.

Permissão para gravar

Antes de gravar qualquer áudio, é necessário declarar a permissão para gravar no AndroidManifest.xml e solicitar que o usuário a conceda.

<manifest ...>
   ...
   <uses-permission android:name="android.permission.RECORD_AUDIO" />
   ...
</manifest>

Você precisa solicitar a permissão para gravar no momento da execução. Consulte a seção Solicitar permissões para mais detalhes sobre como pedir uma permissão no app para carro.

Gravar áudio

Depois que o usuário der permissão para gravar, você poderá gravar o áudio e processar a gravação.

val carAudioRecord = CarAudioRecord.create(carContext)
        carAudioRecord.startRecording()

        val data = ByteArray(CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE)
        while(carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording()
 

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        carAudioRecord.startRecording();

        byte[] data = new byte[CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE];
        while (carAudioRecord.read(data, 0, CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE) >= 0) {
            // Use data array
            // Potentially call carAudioRecord.stopRecording() if your processing finds end of speech
        }
        carAudioRecord.stopRecording();
 

Seleção de áudio

Ao gravar do microfone do carro, primeiro ative a foco de áudio para garantir que qualquer mídia em andamento seja interrompida. Se você perder a seleção de áudio, pare a gravação.

Veja um exemplo de como adquirir a seleção de áudio:

 
val carAudioRecord = CarAudioRecord.create(carContext)
        
        // Take audio focus so that user's media is not recorded
        val audioAttributes = AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
            // Use the most appropriate usage type for your use case
            .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
            .build()
        
        val audioFocusRequest =
            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                .setAudioAttributes(audioAttributes)
                .setOnAudioFocusChangeListener { state: Int ->
                    if (state == AudioManager.AUDIOFOCUS_LOSS) {
                        // Stop recording if audio focus is lost
                        carAudioRecord.stopRecording()
                    }
                }
                .build()
        
        if (carContext.getSystemService(AudioManager::class.java)
                .requestAudioFocus(audioFocusRequest)
            != AudioManager.AUDIOFOCUS_REQUEST_GRANTED
        ) {
            // Don't record if the focus isn't granted
            return
        }
        
        carAudioRecord.startRecording()
        // Process the audio and abandon the AudioFocusRequest when done

CarAudioRecord carAudioRecord = CarAudioRecord.create(getCarContext());
        // Take audio focus so that user's media is not recorded
        AudioAttributes audioAttributes =
                new AudioAttributes.Builder()
                        .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                        // Use the most appropriate usage type for your use case
                        .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
                        .build();

        AudioFocusRequest audioFocusRequest =
                new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                        .setAudioAttributes(audioAttributes)
                        .setOnAudioFocusChangeListener(state -> {
                            if (state == AudioManager.AUDIOFOCUS_LOSS) {
                                // Stop recording if audio focus is lost
                                carAudioRecord.stopRecording();
                            }
                        })
                        .build();

        if (getCarContext().getSystemService(AudioManager.class).requestAudioFocus(audioFocusRequest)
                != AUDIOFOCUS_REQUEST_GRANTED) {
            // Don't record if the focus isn't granted
            return;
        }

        carAudioRecord.startRecording();
        // Process the audio and abandon the AudioFocusRequest when done
 

Biblioteca de testes

A biblioteca de testes do Android for Cars fornece classes auxiliares que podem ser usadas para validar o comportamento do app em um ambiente de teste. Por exemplo, o SessionController permite simular uma conexão com o host e verificar se a Screen e o Template corretos foram criados e retornados.

Consulte as Amostras para mais exemplos de uso.

Informar um problema na biblioteca Android for Cars App

Se você encontrar um problema com a biblioteca, informe-o usando o Google Issue Tracker. Preencha todas as informações solicitadas no modelo de problema.

Criar novo problema

Antes de informar um novo problema, verifique se ele está listado nas notas da versão da biblioteca ou relatado na lista de problemas. Inscreva-se e vote nos problemas clicando na estrela de um deles no Issue Tracker. Para saber mais, consulte Inscrever-se em um problema.