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 ajudar os parceiros a desenvolver um ecossistema de alta qualidade para todos os clientes.

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

1. Métricas do Google para o parceiro: mede a integridade das chamadas do Google para seu back-end na nuvem.

2. Integridade do sistema: métricas do 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 os 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, selecione 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 atendidos corretamente, o que ajuda a evitar respostas do Assistente como "Não consigo acessar o dispositivo" ou a confirmação incorreta de um comando que ainda não foi atendido.

A métrica Taxa de sucesso da sincronização >= 99,5% mede a frequência com que as solicitações de sincronização são atendidas corretamente, o que garante que os dispositivos mostrados no Google Home estejam em sincronia com os dispositivos conectados à sua infraestrutura em nuvem.

O que define um "sucesso"?

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

As respostas que incluem exceções não bloqueantes (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 são considerados "Falhas" ao calcular as taxas de sucesso de QUERY, EXECUTE e SYNC. Além disso, os erros encontrados em Erros e exceções também são "Falhas", com as seguintes exceções:

Paridade do estado de resposta da execução

Ao retornar um status SUCCESS em uma resposta EXECUTE, o objeto states do payload da resposta precisa conter todos os campos de estado ativos e atualizados definidos pelos atributos que você está executando. Omitir campos de estado obrigatórios ou retornar um objeto states vazio para atributos complexos fará com que a plataforma do Google Home não consiga analisar o resultado da execução, registrando-o como uma falha de AGENT_ISSUE ou INVALID_RESPONSE, o que reduz sua taxa de sucesso de consulta e execução.

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, por exemplo, esperar 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 monitora 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 confirmadas em 800 ms ou menos.

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

1. Latência de CONSULTA (interrogativa)

Mede o tempo de retorno de Cloud-to-cloud quando o Google solicita o estado atual de um dispositivo.

• Início: o Google envia uma solicitação action.devices.QUERY ao seu URL de fulfillment.
• Janela de medição: o tempo que sua nuvem leva para receber, processar e transmitir a resposta HTTP completa de volta ao Google.
• Fim: o Google recebe e confirma o payload de resposta final do seu serviço.

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

Mede o tempo de confirmação 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 ao seu URL de fulfillment.
• Janela de medição: o tempo que a nuvem leva para receber o comando e retornar 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. Ela não mede o tempo que o hardware físico (por exemplo, uma lâmpada) leva para concluir 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.

Detalhamento da linha do tempo de latência de EXECUTE/QUERY

Ao analisar os carimbos de data/hora de uma latência de 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) distorce os tempos em 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 (Google Outbound): 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 tempo estimado de trânsito de rede e fila antes de chegar ao endpoint de fulfillment.

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

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

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

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

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

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

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

Recomendações de arquitetura para roteamento geográfico

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 fulfillment do Google e encaminha o tráfego para o back-end íntegro regional mais próximo.

   • Benefício:oferece o desempenho do Anycast com complexidade de configuração e custo 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 DNS.

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

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

Além do roteamento no nível da infraestrutura, é possível implementar as estratégias a seguir na camada do 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 lidar com o handshake inicial.

   1. O Google acessa seu URL global.

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

   3. O proxy encaminha o payload pelo backbone interno 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 fulfillment, 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 do parceiro 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 do 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 sua 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 os erros internos do Google da contagem de falhas. As chamadas de API incluídas no cálculo estão 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. Alguns códigos comuns são:

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 foi encontrado no HomeGraph (ainda não sincronizado, já desvinculado ou ID incompatível).

Solução:

1. Verifique se o agentUserId corresponde ao valor fornecido na resposta de 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 Home Graph.
3. Acione requestSync depois de adicionar, remover, renomear ou atualizar um dispositivo ou uma conta para garantir que o estado permaneça atualizado.
4. Processar corretamente as intents DISCONNECT para interromper a geração de relatórios de dispositivos desatualizados. Depois de receber a intent DISCONNECT, seu 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 de gerenciamento de cotas. Consulte também as cotas e limites de casa inteligente para mais informações.

Integridade do dispositivo: precisão do estado

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 Pergunte ao Home. Se a precisão do estado for baixa, as automações podem não ser acionadas, e as entradas do histórico podem não aparecer na guia "Atividade" do GHA no momento certo. Para mais informações, consulte Estado do relatório. Observação:a meta de precisão de estado precisa ser atingida em TODOS os atributos 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 consulta ativamente o status atual de um dispositivo.
• Precisão baseada em EXECUTE:verificada pela avaliação do 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 as 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 atributo e dispositivo acumular menos de 100 amostras em uma janela contínua de cinco dias, a precisão será considerada estatisticamente insignificante e definida como N/A.

Quando uma hora tem volume de amostra suficiente nos dois caminhos, a precisão de referência por hora de um estado específico é calculada como a média das duas porcentagens independentes:

Precisão do estado por hora = (% de precisão da consulta + % de precisão da execução) / 2

Em que cada caminho é definido como:

• %de Precisão da Consulta = (Amostras Precisas de Consultas por Hora) / (Total de Amostras de Consultas por Hora)
• %de precisão da execução = (amostras precisas de execução por hora) / (total de amostras de execução por hora)

Pontuação de precisão do atributo (calculada por atributo) = SOMA(amostras precisas de consulta + amostras precisas de execução) / SOMA(amostras totais de consulta + amostras totais de execução)

Como o Índice de Qualidade avalia o desempenho mínimo estrito em todo o ecossistema, cada atributo compatível e qualificado precisa atender individualmente à meta de precisão de estado >= 99,5% (não é uma média entre os atributos).

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 que se preocupam com a possibilidade de características pouco utilizadas reduzirem 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 baixos, a menos que atinja o limite de amostra necessário.

3. Como melhorar a precisão do estado e da integridade 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 é diferente entre a resposta QUERY e a solicitação Report State para o mesmo dispositivo.

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

Erros de "imprecisão"

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 QUERY e o último valor de Report State.

Solução:verifique se o Report State é acionado sempre que o status de um dispositivo muda e se o Report State e a QUERY 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, 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 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 de relatório 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 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 HomeGraph do Google e garante que o dispositivo sincronize o estado de forma consistente para manter a interface do usuário e o mecanismo de automação precisos.