Google Home Vitals (Cloud)

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

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

1. Métricas do Google para parceiros : mede a integridade das chamadas do Google para o back-end da nuvem.

2. Integridade do sistema: métricas de parceiros 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 do usuário.

Quando as métricas não atendem aos valores de destino, 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 os usuários.

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

Ir para o painel

Métricas do Google para parceiros

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 atendidos 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 ainda não foi atendido.

O que define um "sucesso"?

Uma transação é marcada como bem-sucedida se a plataforma do 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 que são marcados como Ação do parceiro necessária são considerados "falhas" ao calcular as taxas de sucesso de CONSULTA e EXECUÇÃO. 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 a 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 dispositivos para garantir a precisão técnica.

1. Latência de 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 atendimento.
• Janela de medição: o tempo gasto pela nuvem para receber, processar e transmitir a resposta HTTP completa de volta ao Google.
• Fim: o Google recebe e reconhece o payload de resposta final do seu serviço.

2. Latência de EXECUÇÃO (ação)

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

• Início: o Google envia uma solicitação action.devices.EXECUTE para o URL de atendimento.
• Janela de medição: o tempo gasto pela nuvem para receber o comando e retornar uma resposta de reconhecimento.
• Fim: o Google recebe a resposta de status SUCCESS, PENDING ou OFFLINE.
• Escopo técnico: essa métrica mede o tempo de "reconhecimento de resposta" entre a nuvem do Google e a sua. Ela 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 de malha local fora do caminho da nuvem para a nuvem.

Detalhes da linha do tempo de latência de EXECUÇÃO/CONSULTA

Ao analisar carimbos de data/hora para uma latência EXECUTE ou QUERY, o tempo de retorno total pode ser dividido no seguinte fluxo sequencial:

Como essa análise compara os carimbos de data/hora do Google e do parceiro, os servidores do parceiro precisam ser sincronizados com o NTP (Network Time Protocol). Mesmo um pequeno desvio de relógio (50 a 100 ms) vai distorcer os tempos de trânsito calculados (t2 - t1 e t4 - t3), o que pode levar a métricas logicamente impossíveis, como latências de trânsito negativas.

[t1] Solicitação enviada (saída do Google) : o Google inicia a solicitação de intent. Como t1 não é exposto diretamente, ele é calculado aproximadamente subtraindo a latência total do carimbo de data/hora de entrada final.

Trânsito de rede (t1 a t2): o trânsito de rede estimado e o tempo de fila antes de chegar ao endpoint de atendimento.

[t2] Solicitação recebida (entrada do parceiro) : o carimbo de data/hora exato em que a solicitação chega ao gateway da API ou ao servidor de entrada do seu ambiente.

Processamento do parceiro (t2 a t3): a execução interna, o roteamento, e a latência de tratamento de dispositivos totalmente dentro do seu ambiente de nuvem.

[t3] Resposta enviada (saída do parceiro) : o carimbo de data/hora em que o serviço envia a resposta de atendimento de volta ao Google.

Trânsito de retorno (t3 a t4): o roteamento de rede de retorno e o tempo de conclusão da conexão de volta ao Google.

[t4] Solicitação finalizada (entrada do Google) : o Google recebe e processa a resposta final. Esse carimbo de data/hora é registrado explicitamente nos Google Cloud registros como receiveTimestamp.

Para ilustrar como essas métricas estão vinculadas, considere uma amostra EXECUTE solicitação com uma latência total registrada (latencyMsec) de 1700 ms e um Google Cloud receiveTimestamp (t4) de 2026-05-25T15:25:00.550Z.

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

Recomendações arquitetônicas para georroteamento

Se a implementação de 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, na sigla em inglês)

   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:isso oferece o desempenho do Anycast com complexidade e custo de configuração significativamente menores.

2. DNS com reconhecimento de localização geográfica (GeoDNS, na sigla em inglês)

   • Como funciona:configure o provedor de DNS para resolver o URL de atendimento 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 de atendimento regionais 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, você pode 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 "Trampolim"

   Se você precisar manter um data center principal, use servidores proxy regionais leves (Trampolins) para lidar com 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 rede de backbone 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 de 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 residencial 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 rotear 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 do dispositivo 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 a nuvem envia 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 são encontradas na referência da API HomeGraph.

O que define um "sucesso"?

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

O que define uma "falha"?

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 nulo 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 incompatibilidade de ID).

Solução :

1. Verifique se o agentUserId corresponde ao valor fornecido na sua resposta SYNC.
2. Use a API SYNC do Home Graph para determinar se o erro "404 Não encontrado" é causado por um dispositivo ou usuário ausente no HomeGraph.
3. Acione requestSync após adicionar, remover, renomear ou atualizar o dispositivo ou a conta para garantir que o estado permaneça atualizado.
4. Trate corretamente as intents DISCONNECT para interromper a geração de relatórios de dispositivos desatualizados. Depois de receber a intent DISCONNECT, o serviço de nuvem precisa parar de publicar mudanças no Google com Request Sync e Report State.

429 Recurso esgotado

Causa:sua integração excedeu a cota alocada.

Solução:consulte as instruções na seção "Etapa 2a: depurar problemas de cota" no painel para gerenciamento de cotas. Você também pode consultar 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 os estados do dispositivo ou usar recursos de IA, como o Ask Home. Se a precisão do estado for baixa, as automações poderão não ser acionadas e as entradas de histórico poderão não aparecer na guia "Atividade" do GHA no momento certo. Para mais informações, consulte Report State. Observação:a meta de acurácia do estado precisa ser atendida em TODAS as características compatíveis.

1. Componentes de precisão

A métrica é derivada de "amostras" em que o Google pode verificar o estado informado em relação a um resultado de intent conhecido. Para precisão técnica, a acurácia é avaliada em dois caminhos distintos:

• Precisão baseada em CONSULTA:verificada quando um usuário ou sistema interroga ativamente o status atual de um dispositivo.
• Precisão baseada em EXECUÇÃO:verificada avaliando o estado do dispositivo pós-comando informado após uma solicitação de controle.

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

O painel calcula a precisão com base em um intervalo de 1 hora. Para garantir a confiança estatística e evitar penalizar integrações em ruídos de sinal baixo, o Google aplica um limite mínimo de volume de tráfego. Se uma combinação específica de característica e dispositivo acumular menos de 100 amostras totais em uma janela de 5 dias, a precisão será considerada estatisticamente insignificante e será definida como N/D.

Quando uma hora tem volume de amostra suficiente em ambos os caminhos, a precisão horária de referência para um estado específico é calculada como a média das duas porcentagens independentes:

Acurácia de estado por hora = (Acurácia da consulta % + Acurácia da execução %) / 2

Em que cada caminho é definido como:

• Precisão da consulta % = (amostras precisas de consulta por hora) / (amostras totais de consulta por hora)
• Precisão da execução % = (amostras precisas de execução por hora) / (amostras totais de execução por hora)

Pontuação de acurácia da característica (calculada por característica) = SOMA(amostras precisas de consulta + amostras precisas de execução) / SOMA(amostras totais de consulta + amostras totais de execução)

Como a pontuação de qualidade avalia o desempenho mínimo estrito em todo o ecossistema, cada característica compatível e qualificada precisa atender individualmente à meta de precisão de estado >= 99,5% (não é uma média entre as características).

Essa visualização impede que dispositivos de alto volume com excelente precisão mascarem problemas de precisão em dispositivos de menor volume. Os parceiros preocupados com características subutilizadas que diminuem a pontuação podem ter certeza de que uma característica raramente usada é protegida automaticamente pela verificação de volume mínimo de tráfego e não será considerada na pontuação de tipo e característica mais baixa, a menos que atenda ao limite de amostra necessário.

3. Como melhorar a integridade do dispositivo e a precisão do estado

As discrepâncias ocorrem quando o estado armazenado no Home Graph não corresponde aos resultados de uma CONSULTA 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 em ambos os caminhos. Se uma característica estiver incluída na SYNC, os campos correspondentes precisarão estar presentes e consistentes em relatórios proativos e consultas reativas.

Erros "imprecisos"

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 de estado do relatório.

Solução:verifique se o estado do relatório é acionado sempre que um status do dispositivo muda e se o estado do relatório e a CONSULTA sempre fornecem os mesmos valores atualizados e todos os campos necessá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 estado do relatório após a execução do comando para que o Home Graph 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 estado do relatório foi recebido para esse dispositivo (o estado está vazio e o carimbo de data/hora informado está na época), apesar de os resultados da CONSULTA 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 estado do relatório é acionado e enviado 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.