Perguntas frequentes sobre casas inteligentes

Geral

P:onde e em qual idioma devemos implementar nossa infraestrutura de atendimento na nuvem?

R:desde que ela seja compatível com SSL (TLS) moderno e OAuth 2.0, você pode implementar sua infraestrutura em qualquer plataforma e idioma. Recomendamos que você faça a implantação o mais próximo possível do restante da infraestrutura para melhorar a confiabilidade e reduzir a latência de execução em dispositivos de usuários reais.

P:os IDs de dispositivos precisam ser exclusivos?

R:sim. Se você não tiver IDs exclusivos no serviço, eles precisam ser exclusivos pelo menos por usuário. Imagine um usuário com várias casas, em que ambas têm integrações com o mesmo usuário. Pedir para acender uma luz em uma casa não deve acender uma luz com o mesmo ID em outra casa.

P:os nomes dos dispositivos precisam ser exclusivos?

R:não, mas, com o tempo, podemos incentivar as pessoas a melhorar a nomenclatura inadequada após a configuração para uma melhor experiência do usuário.

Confira um guia rápido de nomenclatura:

  • Os nomes precisam ser algo que as pessoas possam dizer.
  • Reconhecemos subconjuntos de strings. Portanto, se você tiver "acme color light", também responderemos a "acme light".
  • Incentivamos o uso de um nome descritivo para o produto e um ou mais nomes definidos pelo usuário.
  • Os usuários não precisam dar nomes de cômodos às luzes, porque já temos cômodos para isso. Elas precisam ter nomes exclusivos por cômodo, mas sempre podem usar plurais para comandar tudo (por exemplo, as duas lâmpadas nas arandelas do escritório são "luz do norte" e "luz do leste", mas podem ser comandadas apenas como "luzes").

P:com que frequência o estado do dispositivo é atualizado?

R:o estado efêmero é recuperado na CONSULTA ou na EXECUÇÃO, que são ações iniciadas pelo usuário. Se o usuário perguntar "a luz está acesa?" ou quiser acender uma luz, precisaremos fazer uma consulta para descobrir o estado atual.

P:é possível atualizar o Home Graph diretamente com o estado atual de um dispositivo?

R: sim, use a chamada da API Report State.

Vinculação de contas e OAuth

R:sim, a vinculação de contas é necessária para conectar os dispositivos de um usuário aos serviços de nuvem do provedor.

P:para o OAuth, expiramos os tokens de acesso a cada 15, 213 horas.Isso está certo?

R:sim, mas teste com um tempo de expiração bastante curto, por exemplo, de 10 a 20 minutos. Nosso cliente OAuth precisa atualizar os tokens conforme necessário, e o teste com um tempo de expiração curto vai comprovar que isso está funcionando.

Intents

P:quando a SINCRONIZAÇÃO acontece?

R: a SINCRONIZAÇÃO acontece imediatamente após a conclusão do OAuth e depois que uma chamada de sincronização de solicitação é feita.

P:por que a SYNC não está funcionando?

R:há vários motivos comuns para isso.

  • Você está enviando os tipos de dispositivo errados.

    • Por exemplo, esperamos action.devices.types.LIGHT, mas você envia action.devices.types.Light.

  • Você está enviando tipos de dispositivo sem suporte.

    • Por exemplo, você envia action.devices.types.FLASHLIGHT - isso não é um tipo de dispositivo com suporte.

  • Você está enviando campos inválidos/sem suporte.

    • Por exemplo, você tem um campo que não está na nossa especificação.

  • Há algum outro problema de formatação com sua resposta de SINCRONIZAÇÃO.

    • Verifique os colchetes.

  • Você está com um problema de vinculação de contas.

    • Verifique se você está recebendo um token de acesso válido no cabeçalho de autorização da solicitação de SINCRONIZAÇÃO.

  • Você está demorando muito para responder à solicitação de SINCRONIZAÇÃO.

    • Verifique se você está respondendo à solicitação de SINCRONIZAÇÃO em até 5 segundos.

P:uma resposta "pendente" está tudo bem?

R:preferimos uma resposta de sucesso/falha, em vez de pendente, se seus dispositivos estiverem disponíveis em tempo real. Entre em contato se você achar que precisa de uma resposta "pendente". Reconhecemos que alguns dispositivos de baixa potência e não em tempo real podem exigir uma resposta pendente e um modelo de execução assíncrono.

Teste e envio

P:podemos configurar um ambiente de nuvem de desenvolvimento?

R:sim, você pode testar um ambiente e uma configuração de nuvem não lançados.

P:minha ação não está visível na seção "Automação residencial" do app Google Home. O que está acontecendo?

R:confirme se você é um desenvolvedor desse projeto.

Informar estado

P:há pré-requisitos para implementar o recurso "Informar estado"?

R:o projeto precisa usar a API Smart Home, oferecer suporte ao OAuth2 e ter características com estados a serem informados.

P:com que frequência precisamos informar o estado de um dispositivo?

R:o Google está interessado na transição e no estado final. No entanto, se houver muitas mudanças de estado em um curto período de tempo (por exemplo, um usuário abre e fecha a geladeira três vezes em um minuto ou desliza um dimmer), só precisamos do estado final informado.

P:o estado completo do dispositivo precisa ser enviado ao fazer chamadas de "Informar estado"?

R: as atualizações de estado parciais não são aceitas. Portanto, as chamadas de Report State sempre precisam incluir todos os dados de uma característica específica que foi atualizada. Se duas características criarem uma inconsistência, elas precisarão ser informadas juntas.

P:o Google pode consultar meu dispositivo para receber o estado (ou seja, fazer uma pesquisa no dispositivo)?

R:esse é um mecanismo de fallback que não recomendamos. Se precisarmos fazer pesquisas frequentes em um dispositivo para esses usuários, não podemos garantir qual será a carga adicional. A necessidade vem das novas superfícies visuais. Além do problema de carga desconhecida, isso vai gerar uma experiência do usuário ruim. Acreditamos que Report State é essencial para a plataforma.

P:quais características oferecem suporte ao recurso "Informar estado" no momento?

R:todas as características públicas que têm estados associados são aceitas. Qualquer mudança no estado on-line do dispositivo também precisa ser informada.

As cenas não têm estados. No entanto, elas podem resultar em uma mudança de estado(s) de dispositivo(s). Se algum dispositivo em Google Home Graph tiver uma mudança de estado, isso precisará ser informado.

P:o recurso "Informar estado" exige que um carimbo de data/hora seja enviado?

R:não exigimos um carimbo de data/hora. O último estado enviado vai substituir as chamadas anteriores.

P:preciso informar o estado separadamente se já estiver enviando o estado na consulta e/ou execução?

R: Home Graph só armazena o estado enviado pelo recurso " Report State". O estado retornado como resposta às intents EXECUTE e QUERY é usado apenas para respostas de voz ao usuário e não é armazenado. Como resultado, Report State precisa ser chamado mesmo que o novo estado do dispositivo já tenha sido retornado como resposta a uma intent EXECUTE ou QUERY.

P:quais são as consequências de não implementar completamente o recurso "Informar estado" dentro do prazo determinado?

R: isso vai resultar em uma experiência do usuário ruim, por exemplo, no Google Home app (GHA) e nas superfícies visuais. Isso significa que muitas intents QUERY serão enviadas para pesquisar o estado, e não podemos garantir a carga adicional que isso vai gerar na nuvem do parceiro.

P:como posso testar nossa implementação do recurso "Informar estado"?

R: use o Home Graph Viewer, uma ferramenta de teste de autoatendimento que mostra os estados atuais dos dispositivos armazenados no Home Graph.

P:podemos usar um requestId aleatório para o recurso "Informar estado"?

R: recomendamos que os parceiros usem o mesmo requestId que receberam da solicitação EXECUTE se o Report State for acionado pela solicitação EXECUTE. Caso contrário, você pode usar um requestId aleatório.

P:se um usuário tiver vários dispositivos e um deles mudar de estado, precisamos informar o estado mais recente de todos os dispositivos?

R:não. Você só precisa informar o estado desse dispositivo específico.

Práticas recomendadas

P:qual tipo de latência é aceitável?

R:o ideal é menos de 1.000 ms, entre 2 e 5 segundos. Se a latência estiver em torno de 5 segundos, entre em contato conosco.

P:como faço para que meu alto-falante ativado por voz responda corretamente quando estiver off-line?

R:retorne o estado off-line para dispositivos off-line. Retornamos "não disponível no momento" como TTS para esse erro. Para mais informações, consulte Erros e exceções.