Fulfillment local

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

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

A integração do SDK oferece melhorias de desempenho para a ação de casa inteligente, incluindo menor latência e maior confiabilidade. O fulfillment local tem suporte a todos os tipos e características de dispositivos, exceto aqueles que usam a verificação de usuário secundário.

Começar a criar Testar o exemplo

Entenda como funciona

Depois de receber uma resposta SYNC do fulfillment na nuvem, a plataforma de casa local 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 aqueles retornados pela resposta SYNC anterior. Se o dispositivo detectado for um hub ou ponte, a plataforma enviará uma intent REACHABLE_DEVICES e tratará o hub como o dispositivo proxy para comunicação local.

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 comandos do usuário para fulfillment local.

Quando um usuário aciona uma ação de casa inteligente que tem um caminho de fulfillment local, o Google Assistente envia a intent EXECUTE ou QUERY ao 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 e executada localmente no dispositivo
            Google Home. O comando é emitido diretamente para o hub do dispositivo ou
            para o dispositivo. A nuvem do desenvolvedor está disponível como
            um substituto da nuvem.
Figura 1: como adicionar um caminho de fulfillment local para a ação de casa inteligente.

A plataforma local não determina qual dispositivo Google Home ou Google Nest acionará o comando. As intents EXECUTE e QUERY podem vir por qualquer dispositivo Google Home ou Google Nest definido na mesma estrutura do Home Graph que 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 de casa e acessar o dispositivo inteligente pela rede local. Nenhuma modificação do seu hardware é esperada para integrar o fulfillment local. O app atende às solicitações de ação de casa inteligente enviando comandos de controle ao dispositivo inteligente por protocolos de camada de aplicativo, incluindo HTTP, TCP ou UDP. Caso o caminho de fulfillment local falhe, o atendimento na nuvem será usado como um caminho de execução de substituto.

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

  • DeviceManager: fornece métodos para se comunicar com dispositivos inteligentes usando TCP, soquetes UDP ou solicitações HTTP.
  • App: fornece métodos para anexar gerenciadores para intents que o Google envia após 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 no estado atual do dispositivo (QUERY).

Durante o desenvolvimento, você pode criar e testar o aplicativo carregando-o no seu próprio servidor de hospedagem ou máquina de desenvolvimento local. Na produção, o Google hospeda o 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 é compatível com o fulfillment local. O Google depende do fulfillment da nuvem para processar essas solicitações.

Ciclo de vida do aplicativo

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

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

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 ao fulfillment local associado ao agentUserId do usuário.

Dispositivos compatíveis

A plataforma local do Google Home executa seu app de fulfillment local em dispositivos compatíveis com o Google Home ou Google Nest. 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 ambiente 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 Tela Chrome
Nest Hub Max Tela 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 Home local oferece suporte aos seguintes ambientes de execução:

Estrutura do código-fonte

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

Caminho de implementação

Para usar o SDK local do Google Home na sua integração de casa inteligente, faça o seguinte:

1 Definir a configuração da verificação Configure o Console do Actions com os parâmetros necessários para que o Google Assistente descubra dispositivos controláveis localmente.
2 Atualizar a resposta SYNC no fulfillment da nuvem No fulfillment da nuvem, modifique o gerenciador de solicitações SYNC para que ele seja compatível com o campo otherDeviceIds usado pela plataforma 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 local do Google Home para criar um app JavaScript que processe as intents IDENTIFY, EXECUTE e QUERY. Para dispositivos proxy hub ou bridge, você também precisa processar a intent REACHABLE_DEVICES.
4 Testar e depurar o app Teste sua integração (ou autocertificação) usando o Pacote de testes do Google Home.

Antes de começar