Google Home Vitals (Cloud)

Esse conjunto de painéis e alertas ajuda você a manter proativamente uma integração de alta qualidade com o ecossistema do Google Home. O Google tem o compromisso de apoiar os parceiros no desenvolvimento de um ecossistema de alta qualidade para todos os clientes.

O painel tem três seções, cada uma abordando uma parte fundamental que contribui para a qualidade de uma integração geral.

1. Métricas do Google para parceiro: medem a integridade das chamadas do Google para seu back-end da nuvem.

2. Integridade do sistema: métricas de parceiro para o Google: mede a integridade das chamadas do seu sistema para o Google.

3. Integridade do dispositivo: precisão do estado: mede a precisão dos estados armazenados nos sistemas do Google, que são usados para atender às consultas dos usuários.

Quando as métricas não atingem os valores desejados, elas são destacadas em vermelho para indicar um problema que pode afetar a experiência do usuário. As informações a seguir fornecem detalhes sobre cada meta e por que ela é importante para seus usuários.

Se o botão a seguir não levar você diretamente ao painel, acesse a página Visão geral, selecione Painéis e, na lista Meus painéis, escolha Painel do Google Home Vitals (Cloud) para conferir seu painel.

Ir para o painel

Métricas do Google para o parceiro

A métrica Taxa de sucesso de consulta/execução >= 99,5% mede a frequência com que os comandos dos usuários são executados corretamente, o que ajuda a evitar respostas do Google Assistente como "Não consigo acessar o dispositivo" ou a confirmação incorreta de um comando que não foi executado.

O que define um "sucesso"?

Uma transação é marcada como bem-sucedida se a plataforma Google Home receber uma resposta válida indicando que a ação pretendida foi concluída ou que o estado solicitado foi recuperado.

As respostas que incluem exceções sem bloqueio (por exemplo, um status SUCCESS acompanhado de uma exceção lowBattery) são contadas como transações bem-sucedidas. O comando chegou ao dispositivo e a intent foi atendida apesar do aviso.

O que define uma "falha"?

Os erros encontrados em Códigos de erro comuns da plataforma, marcados como Ação do parceiro necessária, são considerados "Falhas" ao calcular as taxas de sucesso de QUERY e EXECUTE. Além disso, os erros encontrados em Erros e exceções também são "Falhas", com as seguintes exceções:

A métrica Latência de consulta/execução (p90) <= 1.000 ms mede o tempo de espera da ação solicitada e ajuda a garantir que os usuários não precisem esperar muito tempo, por exemplo, alguns segundos para que a luz se apague.

Métricas de latência

A latência é um indicador essencial de como sua integração responde ao usuário final. O painel acompanha a latência do 90º percentil (P90), que representa a experiência dos usuários "mais lentos". Por exemplo, um P90 de 800 ms significa que 90% das solicitações são reconhecidas em 800 ms ou menos.

O Google mede a latência de maneira diferente para verificações de status e comandos de dispositivo para garantir a precisão técnica.

1. Latência da CONSULTA (interrogativa)

Isso mede o tempo de ida e volta Cloud-to-cloud quando o Google pede o estado atual de um dispositivo.

• Início: o Google envia uma solicitação action.devices.QUERY para o URL de fulfillment.
• Janela de medição: o tempo necessário para que sua nuvem receba, processe e transmita a resposta HTTP completa de volta ao Google.
• Fim: o Google recebe e confirma o payload da resposta final do seu serviço.

2. Latência de EXECUTE (ação)

Isso mede o tempo de confirmação do comando quando o Google envia uma solicitação de controle a um dispositivo.

• Início: o Google envia uma solicitação action.devices.EXECUTE para o URL de fulfillment.
• Janela de medição: o tempo necessário para que sua nuvem receba o comando e retorne uma resposta de confirmação.
• Fim: o Google recebe a resposta de status SUCCESS, PENDING ou OFFLINE.
• Escopo técnico: essa métrica mede o tempo de "confirmação de resposta" entre a nuvem do Google e a sua. Ele não mede o tempo necessário para que o hardware físico (por exemplo, uma lâmpada) conclua a mudança de estado físico, já que isso geralmente envolve a latência da rede mesh local fora do caminho de nuvem para nuvem.

Opções de redução de latência

Recomendações de arquitetura para georroteamento

Se a implementação do IP Anycast não for viável, recomendamos as seguintes alternativas econômicas para garantir que os usuários sejam atendidos pelo data center regional mais próximo.

1. Balanceamento de carga global (GLB)

   Em vez de roteamento estático, use um balanceador de carga de aplicativo global, disponível na maioria dos principais provedores de nuvem.

   • Como funciona:você configura um único ponto de entrada global (URL) que fica na borda da rede. O balanceador de carga detecta automaticamente a origem geográfica da solicitação dos clusters de atendimento do Google e roteia o tráfego para o back-end regional íntegro mais próximo.

   • Benefício:oferece o desempenho do Anycast com complexidade e custo de configuração significativamente menores.

2. DNS com reconhecimento de geolocalização (GeoDNS)

   • Como funciona:configure seu provedor de DNS para resolver o URL de fulfillment em diferentes endereços IP com base na localização geográfica da consulta de DNS.

   • Implementação:verifique se o provedor de DNS está otimizado para os pontos de saída do Google. Quando os serviços regionais de atendimento do Google (por exemplo, nos EUA, na UE ou na Ásia) resolvem seu domínio, eles recebem o endereço IP do data center nessa região específica.

Estratégias de otimização na camada de aplicativo

Além do roteamento no nível da infraestrutura, é possível implementar as seguintes estratégias na camada de aplicativo para reduzir a latência no processamento de solicitações.

1. O método de proxy "Trampoline"

   Se você precisar manter um data center principal, use servidores proxy leves regionais (Trampolines) para processar o handshake inicial.

   1. O Google acessa seu URL global.

   2. Um proxy regional (por exemplo, uma função Nginx ou Lambda leve) recebe a solicitação.

   3. O proxy encaminha o payload pela sua rede interna de alta velocidade para o banco de dados principal.

   Benefício:isso reduz o tempo de "handshake TCP", que geralmente é o maior contribuinte para a latência em solicitações de longa distância.

2. Dicas de região do token de acesso

   Durante o processo de vinculação de contas (OAuth), seu sistema pode identificar a região de residência do usuário.

   Implementação:codifique um identificador de região no access_token emitido para o Google. Quando o Google envia uma solicitação de atendimento, seu gateway pode inspecionar imediatamente o token e encaminhar a solicitação para o cluster regional correto sem precisar de uma pesquisa no banco de dados.

Integridade do sistema: métricas de parceiros para o Google

Manter uma taxa de sucesso >= 99, 5% ajuda a garantir que os estados dos dispositivos estejam corretos no Google Home, que os dispositivos sejam adicionados e removidos, que as automações sejam acionadas e que os eventos de histórico apareçam na guia "Atividade" do Google Home app (GHA).

A taxa de sucesso é calculada com base nos códigos de resposta HTTP retornados pelo Google quando seus pushs na nuvem enviam atualizações de estado. Para garantir que os parceiros não sejam penalizados por problemas de infraestrutura do Google, a métrica exclui erros internos do Google da contagem de falhas. As chamadas de API incluídas no cálculo podem ser encontradas na referência da API HomeGraph.

O que define um "sucesso"?

2xx (sucesso): a atualização de estado foi recebida e processada pelo HomeGraph.

O que define uma "falha"?

Os erros 4xx (erro do parceiro) representam falhas e indicam um problema com a solicitação enviada da sua nuvem. Os códigos comuns incluem:

400 Solicitação inválida

Causa:o servidor não conseguiu processar a solicitação devido a uma sintaxe inválida. As causas comuns incluem JSON malformado ou o uso de "null" em vez de "" para um valor de string.

Solução:verifique se o corpo da solicitação é um JSON válido (sem estrutura malformada ou valores nulos para campos de string) e se agentUserId corresponde ao valor da resposta SYNC.

404 Não encontrado

Causa:deviceId ou agentUserId não encontrado no HomeGraph (ainda não sincronizado, já desvinculado ou IDs diferentes).

Solução:

1. Verifique se o agentUserId corresponde ao valor fornecido na sua resposta SYNC.
2. Use a API Home Graph SYNC para determinar se o erro 404 Not Found é causado por um dispositivo ou usuário ausente no HomeGraph.
3. Não se esqueça de acionar requestSync depois de adicionar, remover, renomear ou atualizar um dispositivo ou uma conta para garantir que o estado permaneça atualizado.
4. Processar corretamente intents de DISCONNECT para parar de informar dispositivos desatualizados. Depois de receber a intent DISCONNECT, seu serviço de nuvem precisa parar de publicar mudanças no Google com Solicitar sincronização e Informar estado.

429 Recurso esgotado

Causa:sua integração excedeu a cota atribuída.

Solução:consulte as instruções na seção "Etapa 2a: depurar problemas de cota" no painel de controle para gerenciamento de cotas. Consulte também Cotas e limites da casa inteligente para mais informações.

Integridade do dispositivo: precisão do estado

Atender ou exceder uma Precisão de estado >= 99,5% ajuda a garantir que os usuários vejam resultados corretos ao visualizar estados de dispositivos ou usar recursos de IA, como o Perguntar ao Home. Se a precisão do estado for baixa, as automações poderão não ser acionadas, e as entradas do histórico poderão não aparecer na guia "Atividade" do GHA no momento certo. Para mais informações, consulte Report State.

O painel de qualidade acompanha isso a cada hora usando duas métricas distintas: Acurácia geral e Combinação de tipo/característica mais baixa.

1. Componentes de acurácia

A métrica é derivada de "amostras" em que o Google pode verificar o estado informado em relação a um resultado de intenção conhecido.

2. Métricas do painel (cálculo por hora)

O painel calcula a acurácia com base em um intervalo de uma hora. Se uma hora tiver menos de 100 amostras totais (S_Total < 100), a acurácia dessa hora será definida como N/A.

Visualização 1: acurácia geral (média global)

Isso representa a acurácia total da sua integração em todos os tipos de dispositivos e características combinadas. Ele fornece uma média ponderada da integridade de todo o seu ecossistema.

• Cálculo: total de acurácia de estado em todos os dispositivos / total de estado em todos os dispositivos.

Visualização 2: combinação de tipo/característica mais baixa

Isso identifica a categoria específica menos confiável na sua integração. Isso evita que dispositivos de alto volume e alta qualidade ocultem dispositivos de baixo volume e baixa qualidade. Por exemplo, se você tiver um volume alto de luzes com precisão de estado acima de 99,5%, mas um volume baixo de interruptores com precisão de estado baixa, isso vai destacar a melhoria necessária nos interruptores, que pode ser perdida em um valor médio.

• Cálculo: mínimo de acurácia do estado / total do estado para todas as combinações de traço/dispositivo.

3. Melhorar a integridade e a precisão do estado do dispositivo

As discrepâncias ocorrem quando o estado armazenado no Home Graph não corresponde aos resultados de uma QUERY em tempo real.

Erros de "Campo ausente"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

Causa:com o erro DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD ou DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, o conjunto de campos de payload difere entre a resposta da consulta e a solicitação de estado do relatório para o mesmo dispositivo.

Solução:verifique se a estrutura de dados é idêntica nos dois caminhos. Se um traço for incluído em SYNC, os campos correspondentes precisarão estar presentes e consistentes nos relatórios proativos e nas consultas reativas.

Erros "Impreciso"

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

Causa:para o erro DETAILED_ACCURACY_RESULT_INACCURATE, há uma discrepância entre o valor retornado na resposta da consulta e o último valor do estado do relatório.

Solução:garanta que o Report State seja acionado sempre que o status de um dispositivo mudar e que o Report State e a QUERY sempre forneçam os mesmos valores exatos e atualizados e todos os campos obrigatórios para manter a consistência dos dados.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

Causa:com o erro DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, o parceiro executou o comando com sucesso, mas não informou o estado atualizado do dispositivo ao Google.

Solução:sempre envie uma atualização de Report State após a execução do comando para que o HomeGraph receba o novo estado do dispositivo.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

Causa:para o erro DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, nenhum Report State foi recebido para este dispositivo (o estado está vazio e o carimbo de data/hora informado está na época), apesar de os resultados da QUERY fornecerem o status atual. Isso indica que as atualizações de estado não estão sendo acionadas, não estão chegando ao HomeGraph ou o dispositivo não está informando as transições no status de conectividade ou operacional.

Solução:verifique se o Report State é acionado e enviado com sucesso para todas as mudanças de estado. Verifique se a lógica de back-end processa corretamente as atualizações de status, confirma o sucesso da entrega ao Google HomeGraph e garante que o dispositivo sincronize consistentemente o estado para manter a interface do usuário e o mecanismo de automação precisos.