Esta é a Central do desenvolvedor do Google Home, a nova plataforma para aprender a desenvolver ações de casa inteligente. Observação: você continua criando ações no Console do Actions.

Notificações de ações de casa inteligente

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

As notificações permitem que a ação de casa inteligente use o Google Assistente para se comunicar com os usuários sobre eventos ou mudanças importantes no dispositivo. Você pode implementar notificações para alertar usuários sobre eventos oportunos de dispositivos, por exemplo, quando alguém está na porta ou para informar sobre uma mudança de estado do dispositivo solicitada, como quando uma tranca de porta foi envolvida ou está presa.

Sua ação de casa inteligente pode enviar os seguintes tipos de notificação aos usuários:

  • Notificações proativas: alerta o usuário sobre um evento do dispositivo de casa inteligente sem solicitações de usuários anteriores, como a campainha tocando.

  • Respostas de acompanhamento: uma confirmação de que uma solicitação do comando do dispositivo foi bem-sucedida ou não, por exemplo, ao trancar uma porta. Use esses alertas para comandos de dispositivo que levam tempo para serem concluídos.

O Google Assistente fornece essas notificações aos usuários como avisos em alto-falantes inteligentes e smart displays. As notificações proativas são desativadas por padrão. Os usuários podem ativar ou desativar todas as notificações proativas no app Google Home.

Eventos que acionam notificações

Quando ocorrem eventos do dispositivo, a realização de ações envia uma solicitação de notificação ao Google. As características do dispositivo compatível com a ação de casa inteligente determinam quais tipos de eventos de notificação estão disponíveis e os dados que você pode incluir nessas notificações.

As seguintes características são compatíveis com notificações proativas:

Característica Eventos
Detecção de objetos Objetos detectados pelo dispositivo, como quando um rosto reconhecido é detectado na porta. Por exemplo: "Alice e Beto estão na porta da frente."
RunCycle. O dispositivo conclui um ciclo. Por exemplo: "O ciclo da máquina de lavar foi concluído.".
SensorState. O dispositivo detecta um estado de sensor compatível. Por exemplo: "O detector de fumaça detecta fumaça."
TemperatureControl (link em inglês) O dispositivo atinge uma temperatura programada. Por exemplo: "O forno foi pré-aquecido a 350 graus."
ArmDisarm (link em inglês) O sistema entra em um estado de pré-alarme com uma contagem regressiva de entrada, acionada por uma porta aberta.
CameraStream Link para a transmissão ao vivo da câmera após detectar um objeto ou movimento pelo dispositivo.
MotionDetection "O movimento foi detectado às 12h de 1o de julho de 2020."

As características a seguir são compatíveis com respostas de acompanhamento:

Característica Eventos
ArmDisarm (link em inglês) Mudança de status e conclusão do estado após a execução do comando do dispositivo action.devices.commands.ArmDisarm. Por exemplo: "O sistema de segurança foi ligado."
LockLock (link em inglês) Mudança de status e conclusão do estado após a execução do comando do dispositivo action.devices.commands.LockUnlock. Por exemplo, "A porta da frente foi trancada" ou "A porta da frente está emperrada."
NetworkControl (link em inglês) Mudança de status e conclusão do estado após a execução do comando do dispositivo action.devices.commands.TestNetworkSpeed. Por exemplo: "Seu teste de velocidade da rede foi concluído. A velocidade de download do roteador do escritório é de 80,2 Kbps e de 9,3 Kbps."
OpenClose (link em inglês) Mudança de status e conclusão do estado após a execução do comando do dispositivo action.devices.commands.OpenClose. Por exemplo: "A porta da frente foi aberta" ou "Não foi possível abrir a porta da frente".
StartStop (link em inglês) Mudança de status e conclusão do estado após a execução do comando do dispositivo action.devices.commands.StartStop. Por exemplo, "O aspirador foi iniciado".

Todos os tipos de dispositivo são compatíveis com notificações para as características aplicáveis.

Criar notificações para sua ação de casa inteligente

Adicione notificações à sua ação de casa inteligente nestas etapas:

  1. Indique ao Google se as notificações estão ativadas pelo app do dispositivo de casa inteligente. Se os usuários ativarem ou desativarem as notificações no app, envie uma solicitação SYNC para informar o Google sobre a mudança do dispositivo.
  2. Quando ocorrer um evento relevante do dispositivo ou uma mudança de estado que aciona uma notificação, envie uma solicitação de notificação chamando a API reportStateAndNotification do estado do relatório. Se o estado do dispositivo tiver mudado, você poderá enviar um payload de estado e de notificação juntos no estado do relatório e na chamada de notificação.

As seções a seguir abordam essas etapas em mais detalhes.

Indicar se as notificações estão ativadas no seu aplicativo

Os usuários podem escolher se querem receber notificações proativas ativando esse recurso no app Google Home. No app do seu dispositivo de casa inteligente, também é possível adicionar o recurso para que os usuários alternem explicitamente as notificações do dispositivo, por exemplo, nas configurações do app.

Indique ao Google que as notificações estão ativadas para seu dispositivo fazendo uma chamada Request SYNC para atualizar os dados do dispositivo. Envie uma solicitação SYNC como essa sempre que os usuários mudarem essa configuração no app.

Na resposta SYNC, envie uma destas atualizações:

  • Se o usuário ativou explicitamente as notificações no app do dispositivo ou se você não fornecer uma opção de alternância, defina a propriedade devices.notificationSupportedByAgent como true.
  • Se o usuário tiver desativado explicitamente as notificações no app do dispositivo, defina a propriedade devices.notificationSupportedByAgent como false.

O snippet a seguir mostra um exemplo de como configurar sua resposta do SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Enviar solicitações de notificação para o Google

Para acionar notificações no Assistente, o fulfillment envia um payload de notificação para o Google Home Graph por uma chamada da API Reporting State e Notification.

Ativar a API Google HomeGraph

  1. No Console do Google Cloud Platform, acesse a página API HomeGraph.

    Acessar a página da API HomeGraph
  2. Selecione o projeto que corresponde ao ID do seu projeto de casa inteligente.
  3. Clique em ATIVAR.

Criar uma chave de conta de serviço

Siga estas instruções para gerar uma chave de conta de serviço no Console do GCP:

Observação: verifique se você está usando o projeto correto do GCP ao realizar essas etapas. Este é o projeto que corresponde ao ID do seu projeto de casa inteligente.
  1. No Console do GCP, acesse a página Criar chave da conta de serviço.

    Acessar página "Criar chave da conta de serviço"
  2. Na lista Conta de serviço, selecione Nova conta de serviço.
  3. No campo Nome da conta de serviço, insira um nome.
  4. No campo ID da conta de serviço, insira um ID.
  5. Na lista Papel, selecione Contas de serviço > Criador do token da conta de serviço.

  6. Em Tipo de chave, selecione a opção JSON.

  7. Clique em Criar. Um arquivo JSON que contém a chave é transferido por download para o computador.

Enviar a notificação

Faça a chamada de solicitação de notificação usando a API devices.reportStateAndNotification. A solicitação JSON precisa incluir um eventId, que é um ID exclusivo gerado pela plataforma para o evento que aciona a notificação. O eventId precisa ser um código aleatório que seja diferente sempre que você envia uma solicitação de notificação.

No objeto notifications transmitido na chamada de API, inclua um valor priority que defina como a notificação será apresentada. O objeto notifications pode incluir campos diferentes, dependendo da característica do dispositivo.

Siga um destes caminhos para definir o payload e chamar a API:

Enviar um payload de notificação proativo

Para chamar a API, selecione uma opção em uma destas guias:

HTTP

A API Home Graph fornece um endpoint HTTP

  1. Use o arquivo JSON da conta de serviço salvo para criar um JSON Web Token (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
  2. Consiga um token de acesso do OAuth 2.0 com o escopo https://www.googleapis.com/auth/homegraph usando oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crie a solicitação JSON com agentUserId. Veja um exemplo de solicitação JSON para estado e notificação do relatório:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "ObjectDetection": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
    
  6. Combine o estado do relatório e a notificação JSON e o token na sua solicitação HTTP POST para o endpoint do Google Home Graph. Veja um exemplo de como fazer a solicitação na linha de comando usando curl como teste:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

A API Home Graph fornece um endpoint gRPC

  1. Veja a definição de serviço de buffers de protocolo da API Home Graph.
  2. Siga a documentação do desenvolvedor do gRPC para gerar stubs de clientes para uma das linguagens compatíveis.
  3. Chame o método ReportStateAndNotification.

Node.js

O cliente Node.js das APIs do Google fornece vinculações para a API Home Graph.

  1. Inicialize o serviço google.homegraph usando o Application Default Credentials.
  2. Chame o método reportStateAndNotification com ReportStateAndNotificationRequest. Ele retorna um Promise com o ReportStateAndNotificationResponse.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

Java

A biblioteca de cliente da API HomeGraph para Java fornece vinculações para a API do Home Graph.

  1. Inicialize o HomeGraphApiService usando o Application Default Credentials.
  2. Chame o método reportStateAndNotification usando ReportStateAndNotificationRequest. Ele retorna um ReportStateAndNotificationResponse.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    
Envie um payload de resposta de acompanhamento

O payload de uma resposta de acompanhamento contém o status da solicitação, códigos de erro para falhas de eventos, se aplicável, e o followUpToken válido, fornecido durante a solicitação de intent EXECUTE. O followUpToken precisa ser usado em cinco minutos para permanecer válido e associar corretamente a resposta à solicitação original.

O snippet a seguir mostra um exemplo de payload de solicitação EXECUTE com um campo followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

O Google usa o followUpToken para enviar a notificação apenas no dispositivo com que o usuário estava interagindo, e não para transmitir em todos os dispositivos dele.

Para chamar a API, selecione uma opção em uma destas guias:

HTTP

A API Home Graph fornece um endpoint HTTP

  1. Use o arquivo JSON da conta de serviço salvo para criar um JSON Web Token (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
  2. Consiga um token de acesso do OAuth 2.0 com o escopo https://www.googleapis.com/auth/homegraph usando oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crie a solicitação JSON com agentUserId. Veja um exemplo de solicitação JSON para estado e notificação do relatório:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "NetworkControl": {
                "priority": 0,
                "followUpResponse": {
                  "status": "SUCCESS",
                  "followUpToken": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. Combine o estado do relatório e a notificação JSON e o token na sua solicitação HTTP POST para o endpoint do Google Home Graph. Veja um exemplo de como fazer a solicitação na linha de comando usando curl como teste:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

A API Home Graph fornece um endpoint gRPC

  1. Veja a definição de serviço de buffers de protocolo da API Home Graph.
  2. Siga a documentação do desenvolvedor do gRPC para gerar stubs de clientes para uma das linguagens compatíveis.
  3. Chame o método ReportStateAndNotification.

Node.js

O cliente Node.js das APIs do Google fornece vinculações para a API Home Graph.

  1. Inicialize o serviço google.homegraph usando o Application Default Credentials.
  2. Chame o método reportStateAndNotification com ReportStateAndNotificationRequest. Ele retorna um Promise com o ReportStateAndNotificationResponse.
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

Java

A biblioteca de cliente da API HomeGraph para Java fornece vinculações para a API do Home Graph.

  1. Inicialize o HomeGraphApiService usando o Application Default Credentials
  2. Chame o método reportStateAndNotification usando ReportStateAndNotificationRequest. Ele retorna um ReportStateAndNotificationResponse.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

Geração de registros

As notificações são compatíveis com a geração de registros de eventos, conforme descrito na documentação sobre monitoramento e geração de registros de casas inteligentes. Esses registros são úteis para testar e manter a qualidade das notificações em sua ação.

Veja a seguir o esquema de uma entrada notificationLog:

Propriedade Descrição
requestId ID da solicitação de notificação.
structName Nome do struct de notificação, como "ObjectDetection".
status Indica o status da notificação.

O campo status inclui vários status que podem indicar erros no payload da notificação. Alguns deles podem estar disponíveis apenas em ações que não foram lançadas para produção.

Estes são exemplos de status:

Status Descrição
EVENT_ID_MISSING Indica que o campo obrigatório eventId está ausente.
PRIORITY_MISSING Indica que falta um campo priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indica que a propriedade notificationSupportedByAgent do dispositivo de notificação fornecida em SYNC é falsa.
NOTIFICATION_ENABLED_BY_USER_FALSE Indica que o usuário não ativou as notificações no dispositivo de notificação no app Google Home. Esse status só está disponível em Ações que não foram iniciadas para produção.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indica que o usuário não atribuiu o dispositivo de notificação a uma casa/estrutura. Esse status só está disponível em Ações que não foram lançadas para produção.

Além desses status gerais que podem ser aplicados a todas as notificações, o campo status também pode incluir status específicos de características, quando aplicável (por exemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).