As APIs do Google Home para Android fornecem uma superfície de API unificada para permitir que os desenvolvedores interajam com o estado das entidades na casa de um usuário. Essas entidades podem descrever dispositivos e informações não relacionadas a dispositivos associadas à estrutura e aos cômodos de um usuário.
As APIs Home definem as seguintes entidades com que um usuário pode interagir:
- As estruturas representam uma casa com ambientes e dispositivos.
- Os ambientes fazem parte de uma estrutura e contêm dispositivos.
- Dispositivos implementam características contendo atributos, conformam-se a tipos, emitem eventos e respondem a comandos.
- As automações (Automations) fazem parte de uma estrutura e usam metadados e dispositivos domésticos para automatizar tarefas na casa.
A Figura 1 ilustra essa arquitetura:
Os tipos de dispositivos da API Home podem ser compatíveis com Matter, um padrão aberto para a casa inteligente, ou ser um dispositivo Cloud-to-cloud no ecossistema do Google Home. Alguns tipos de dispositivos podem incorporar funcionalidades de ambos. Consulte Tipos de dispositivos compatíveis no Android para mais informações.
Em Matter, a funcionalidade do dispositivo é agrupada por clusters, que são representados nas APIs Home como traços padrão Matter. As APIs do Home suportam o conjunto padrão de clusters Matter conforme definido na especificação Matter atual.
No ecossistema do Google Home, a funcionalidade dos dispositivos é agrupada por características de casa inteligente, que são representadas nas APIs do Home como características de casa inteligente do Google. As APIs Home são compatíveis com o conjunto de características de casa inteligente definido no programa Cloud-to-cloud.
Outras características, como clusters específicos do fabricante e características da plataforma, também estão disponíveis. Para saber mais, consulte Modelo de dados no Android.
Ecossistema
O ecossistema Google Home oferece uma base simplificada para criar, gerenciar, proteger e integrar experiências de casa inteligente. A Figura 2 mostra como os componentes funcionam juntos.
O ecossistema inclui o Google Automation Engine, que armazena e executa automações que oferecem uma maneira de automatizar tarefas e configurações de dispositivos em uma casa.
As APIs Home usam o OAuth 2.0 para conceder acesso aos dispositivos na estrutura. O OAuth permite que um usuário conceda permissão a um app ou serviço sem precisar expor as credenciais de login.
O Google Home Developer Console é usado para gerenciar todas as etapas de um projeto das APIs do Google Home, desde a verificação da marca até o desenvolvimento, teste e certificação para o lançamento final. Ele simplifica o processo de desenvolvimento e oferece ferramentas robustas e distribuição pelo ecossistema do Google Home.
Idioma
As APIs Home para Android são escritas em Kotlin e oferecem uma interface idiomática em Kotlin que usa Flow para gerenciar estado e assinatura. Isso oferece várias vantagens em relação a uma API de assinatura padrão.
Recomendamos que você se familiarize com a documentação do Kotlin sobre corrotinas, fluxo e Jetpack Compose, caso ainda não tenha feito isso:
- Desenvolver apps Android com Kotlin
- Aprenda Kotlin para Android
- Corrotinas do Kotlin no Android. Estes codelabs específicos podem ser úteis:
- Fluxos Kotlin no Android e, mais especificamente, StateFlow.
- Estado e Jetpack Compose, especificamente a
função
collectAsStateWithLifecycle(). Essa função gerencia automaticamente a inscrição e o cancelamento da inscrição nos fluxos com base em se a interface que mostra esse estado está realmente em primeiro plano ou não. - Se você estiver trabalhando com a API Automation, é útil ler sobre builders com segurança de tipo do Kotlin para entender como a DSL de automação funciona.
Identificadores de entidade
Cada entidade nas APIs Home tem um ID que representa o identificador principal. Esse ID é um identificador exclusivo e estável que nunca muda durante a vida útil da entidade. Esse ID pode ser usado para armazenar objetos em cache ou verificar a igualdade, já que os metadados de uma entidade podem mudar.
Consulte a interface HasId para saber quais entidades têm um ID.
Mapeamento de terminologia
As entidades nas APIs Home são mapeadas para os conceitos Matter e Cloud-to-cloud da seguinte forma:
| APIs do Google Home | Matter | Cloud-to-cloud |
|---|---|---|
| Característica | Cluster | Característica |
| Atributo | Atributo | Atributo, Estado |
| Comando | Comando | Comando |
| Evento | Evento | Resposta de acompanhamento, notificação |