Configurar um host de cartão de app

Use AppCardHost para se comunicar com apps que mostram cards de apps.

Permissões

Qualquer app que use uma AppCardHost precisa ter as seguintes permissões:

  • android.permission.INTERACT_ACROSS_USERS_FULL
  • android.permission.QUERY_ALL_PACKAGES
  • Somente no nível 34 da API e versões mais recentes android.car.permission.BIND_APP_CARD_PROVIDER

Initialize

Para inicializar o host, forneça:

  • Contexto
  • updateRate Taxa de atualização do card do app em milissegundos.
  • fastUpdateRate Taxa de atualização em milissegundos para componentes marcados com EnforceFastUpdateRate
  • responseExecutor Uma conversa em que você quer receber respostas de apps do AppCard.

Design

É possível interagir com um AppCardHost de duas maneiras:

OU,

AppCardListener

O componente AppCardListener se registra com um AppCardHost para receber atualizações de comunicação dos apps AppCardHost e AppCard. As funções de interface de um AppCardListener estão detalhadas aqui.

fun onAppCardReceived(AppCardContainer)

Essa função é acionada quando um AppCard é recebido de um app. Ela é enviada como um AppCardContainer, que fornece um AppCard e um appIdentifier para identificar o app que enviou o AppCard

fun onComponentReceived(AppCardComponentContainer)

Essa função é acionada quando um componente de card do app é recebido de um app. Ela é enviada como um AppCardComponentContainer, que fornece um componente de card do app, Identifier para identificar o app que enviou o card e um ID de string para apontar para o card ao qual o componente está relacionado.

fun onProviderRemoved(String, String?)

Essa função é acionada quando um provedor de cardápio de app é removido ou desativado. Use esse método para limpar qualquer AppCard ativo relacionado ao nome do pacote e à autoridade do provedor.

Se a autoridade for {@code null}, um pacote inteiro foi removido.

fun onProviderAdded(String, String?)

Essa função é acionada quando um provedor de AppCard é adicionado ou ativado.

Exemplo de uso. Use essa função como um acionador para atualizar todos os cards de app disponíveis em um seletor de cards de app. Se a autoridade for {@code null}, um pacote inteiro foi adicionado.

fun onPackageCommunicationError(appIdentifier, Throwable)

Essa função é acionada quando o AppCardHost encontra um erro ao se comunicar com um provedor de cartão de app.

Exemplo de uso. Use esse método para mostrar ao usuário que um card de app selecionado encontrou um erro.

APIs

fun refreshCompatibleapp()

Esse método precisa ser chamado sempre que a atividade que está usando o host é retomada para que o host possa atualizar a lista de apps que oferecem suporte a cards de apps.

fun destroy()

Chamar esse método quando uma atividade que está usando um host for destruída para que o host possa limpar todas as conexões e membros internos.

fun registerListener(AppCardListener)

Usado para registrar um AppCardListener.

fun unregisterListener(AppCardListener)

Usado para cancelar o registro de um AppCardListener.

fun getAllAppCards(AppCardContext)

Chamar esse método para fornecer um AppCardListener registrado com todos os cards de app fornecidos no sistema com um AppCardContext específico que oferece dicas aos provedores sobre como estruturar o card de app.

fun requestAppCard(AppCardContext, appIdentifier, String)

Chama esse método para fornecer um AppCardListener registrado com um AppCard específico, considerando um AppCardContext que dá dicas aos provedores sobre como estruturar o AppCard.

fun notifyAppCardRemoved(appIdentifier, String)

Notificar um provedor de cartão do app de que o cartão não está mais ativo.

fun notifyAppCardInteraction(appIdentifier, String, String, String)

Notificar um provedor de cartão que o cartão dele foi usado. A única interação com suporte é um clique no botão, que é indicado por um AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK.

Recomendamos criar um botão para um AppCard com um listener onClick que chame essa função com appIdentifier, o ID do AppCard, o ID do componente e o ID da interação.

fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)

Envie uma atualização AppCardContext para um card de app específico. Por exemplo, ao mudar do modo "Estacionamento" para o modo "Direção", use esse método para enviar uma atualização AppCardContext em que isInteractable é definido como false para cada AppCard ativo.

Perguntas frequentes

  1. Onde posso encontrar exemplos de implementações?

    • Exemplo de host. Mostra todos os App Cards disponíveis no sistema, além dos recursos de teste.

    • DriverUI e Gerenciador Pano. O gerenciador Pano atua como o seletor, enquanto a DriverUI atua como o apresentador.

  2. Com quantos AppCards cada AppCardContentProvider pode ser usado?

    Um AppCardContentProvider pode oferecer suporte a um número infinito de cards de app. No entanto, é importante equilibrar o número de cards de app com a performance degradada em relação a uma experiência do usuário positiva.