Fulfillment local

O SDK local do Google Home melhora a integração da sua casa inteligente com o Google Assistente ao adicionar um caminho de fulfillment local para rotear intents da casa inteligente.

O SDK local do Google Home oferece dois recursos: execução local e consulta local.

  • A execução local permite atender comandos enviando intents EXEC pelo caminho de fulfillment local, em vez de fazer uma chamada de API da nuvem. Por exemplo, a solicitação "Acender a luz" pode ser processada pela execução local.
  • A consulta local permite processar consultas relacionadas ao estado do dispositivo enviando intents QUERY pelo caminho de fulfillment local. Por exemplo, a consulta local atenderia à consulta "A luz está acesa?" sem fazer uma chamada de API da nuvem.

O SDK permite criar um app de fulfillment local usando TypeScript ou JavaScript, que contém a lógica de negócios da casa inteligente. Os dispositivos Google Home ou Google Nest podem carregar e executar seu app no dispositivo. O app se comunica diretamente com os dispositivos inteligentes por Wi-Fi em uma rede local (LAN) para atender aos comandos do usuário, usando os protocolos atuais.

A integração do SDK oferece melhorias de desempenho à integração Cloud-to-cloud, incluindo latência mais baixa e maior confiabilidade. A entrega local é compatível com todos os tipos e atributos de dispositivo, exceto aqueles que usam a verificação secundária de usuário.

Comece a criar Teste o exemplo

Entenda como funciona

Depois de receber uma resposta SYNC do fulfillment na nuvem, a plataforma Local Home verifica a rede local do usuário usando mDNS, transmissão UDP ou UPnP para descobrir dispositivos inteligentes conectados ao Google Assistente.

A plataforma envia uma intent IDENTIFY para determinar se o dispositivo é controlável localmente, comparando o ID do dispositivo na resposta IDENTIFY com os retornados pela resposta SYNC anterior. Se o dispositivo detectado for um hub ou ponte, a plataforma vai enviar uma intent REACHABLE_DEVICES e tratar o hub como o dispositivo proxy para se comunicar localmente.

Quando recebe uma resposta confirmando um dispositivo local, a plataforma estabelece um caminho de fulfillment local para o dispositivo Google Home ou Google Nest do usuário e, em seguida, encaminha os comandos do usuário para fulfillment local.

Quando um usuário aciona uma integração Cloud-to-cloud que tem um caminho de fulfillment local, o Google Assistente envia a intent EXECUTE ou QUERY para o dispositivo Google Home ou Google Nest em vez do fulfillment na nuvem. Em seguida, o dispositivo executa o app de fulfillment local para processar a intent.

Esta figura mostra o fluxo de execução do fulfillment local. O caminho de execução captura a intent de um usuário de um smartphone com o Google Assistente. Em seguida, a intent do usuário é processada pelo Google Cloud, depois é executada localmente no dispositivo Google Home e o comando é emitido diretamente para o hub do dispositivo ou diretamente para o dispositivo. A nuvem para desenvolvedores está disponível como uma alternativa de nuvem.
Figura 1: como adicionar um caminho de fulfillment local à sua ação de casa inteligente.

A plataforma Local Home não é determinista na escolha de qual dispositivo Google Home ou Google Nest acionar o comando. As intenções EXECUTE e QUERY podem vir de qualquer dispositivo Google Home ou Google Nest definido na mesma estrutura do Google Home como o dispositivo de destino.

App de fulfillment local

O app de fulfillment local contém a lógica de negócios para processar as intents enviadas pela plataforma Local Home e acessar seu dispositivo inteligente pela rede local. Não é necessário modificar o hardware para integrar a entrega local. O app atende às solicitações de integração Cloud-to-cloud enviando comandos de controle para o dispositivo inteligente por protocolos de camada do aplicativo, incluindo HTTP, TCP ou UDP. Se o caminho de fulfillment local falhar, o fulfillment da nuvem será usado como um caminho de execução alternativo.

Para oferecer suporte à criação do app, o SDK local do Google Home fornece estas duas classes principais:

  • DeviceManager: fornece métodos para se comunicar com dispositivos inteligentes usando soquetes TCP, UDP ou solicitações HTTP.
  • App: fornece métodos para anexar processadores a intents que o Google envia depois de descobrir dispositivos controláveis localmente (IDENTIFY, REACHABLE_DEVICES). Essa classe também atende aos comandos do usuário (EXECUTE) e responde às consultas do usuário sobre o estado atual do dispositivo (QUERY).

Durante o desenvolvimento, é possível criar e testar o app carregando-o no seu próprio servidor de hospedagem ou máquina de desenvolvimento local. Na produção, o Google hospeda seu app em um ambiente de sandbox seguro do JavaScript no dispositivo Google Home ou Google Nest do usuário.

No momento, a API Report State não tem suporte para fulfillment local. O Google depende do seu atendimento em nuvem para processar essas solicitações.

Ciclo de vida do aplicativo

O app de fulfillment local é carregado sob demanda quando a plataforma Local Home descobre novos dispositivos locais que correspondem à configuração de verificação do projeto ou tem intents pendentes para entrega relacionados a um dispositivo identificado anteriormente.

Os dispositivos Google Home ou Google Nest têm restrição de memória, e seu app fulfillment local pode ser encerrado a qualquer momento devido à pressão de memória no sistema. Isso pode acontecer se o app começar a consumir muita memória ou se o sistema precisar abrir espaço para outro app. A plataforma Local Home reinicia o app somente quando há novas intents para entregar e recursos de memória suficientes para a execução do app.

A plataforma de casa local descarrega seu app após um tempo limite de inatividade quando o usuário desvincula a conta ou não há mais dispositivos com suporte à entrega local associada ao agentUserId do usuário.

Dispositivos compatíveis

A plataforma Local Home executa o app fulfillment local em dispositivos Google Home ou Google Nest compatíveis. A tabela a seguir descreve os dispositivos compatíveis e o ambiente de execução usado em cada um deles. Para saber mais sobre os requisitos de execução, consulte Ambiente de execução.

Dispositivo Tipo Ambiente
Google Home Alto-falante Chrome
Google Home Mini Alto-falante Chrome
Google Home Max Alto-falante Chrome
Nest Mini Alto-falante Chrome
Nest Hub Display Chrome
Nest Hub Max Display Chrome
Nest Wifi Roteador Node.js
Ponto Chrome

Ambiente de execução

O ambiente de execução do app de fulfillment local depende do dispositivo. A plataforma Local Home é compatível com os seguintes ambientes de execução:

Estrutura do código-fonte

Recomendamos agrupar as dependências em um único arquivo JavaScript usando as configurações do bundler fornecidas pelo SDK local da Home e empacotar seu código-fonte como uma expressão de função invocada imediatamente (IIFE, na sigla em inglês).

Caminho de implementação

Para usar o SDK local do Google Home na integração de casa inteligente, você precisa realizar estas tarefas:

1 Configurar a configuração da verificação Configure o Google Home Developer Console com os parâmetros necessários para que o Google Assistente detecte dispositivos controláveis localmente.
2 Atualizar a resposta SYNC no fulfillment da nuvem No fulfillment em nuvem, modifique o gerenciador de solicitações SYNC para oferecer suporte ao campo otherDeviceIds que a plataforma usa para estabelecer um caminho de fulfillment local. Nesse campo, especifique os IDs dos dispositivos que podem ser controlados localmente.
3 Implementar o app de fulfillment local Use o SDK da casa local para criar um app JavaScript e processar as intents IDENTIFY, EXECUTE e QUERY. Para dispositivos proxy de hub ou ponte, também é necessário processar a intent REACHABLE_DEVICES.
4 Testar e depurar seu app Teste sua integração (ou autocertifique) usando o Pacote de testes do Google Home.

Antes de começar

Próxima
Compatibilidade com descoberta de dispositivos