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

As notificações permitem que a integração da Cloud-to-cloud use Google Assistant para se comunicar com os usuários sobre eventos ou mudanças importantes relacionados ao dispositivo. É possível implementar notificações para alertar os usuários sobre eventos oportunos do dispositivo, por exemplo, quando alguém está na porta, ou para informar sobre uma mudança de estado do dispositivo solicitada, como quando uma fechadura de porta foi ativada ou travada.

A integração Cloud-to-cloud pode enviar os seguintes tipos de notificações aos usuários:

  • Notificações proativas: alertam o usuário sobre um evento do dispositivo smart home sem nenhuma solicitação anterior do usuário para os dispositivos, como a campainha tocando.

  • Respostas de acompanhamento: uma confirmação de que uma solicitação de comando do dispositivo foi bem-sucedida ou falhou, por exemplo, ao trancar uma porta. Use esses alertas para comandos de dispositivos que demoram para ser concluídos. As respostas complementares só são compatíveis quando as solicitações de comando do dispositivo são enviadas de alto-falantes e telas inteligentes.

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

Eventos que acionam notificações

Quando eventos do dispositivo ocorrem, o fulfillment envia uma solicitação de notificação ao Google. As características do dispositivo com suporte à integração Cloud-to-cloud determinam quais tipos de eventos de notificação estão disponíveis e os dados que podem ser incluídos nessas notificações.

Os seguintes traços oferecem suporte a notificações proativas:

Traço Eventos
ObjectDetection Objetos detectados pelo dispositivo, como quando um rosto reconhecido é detectado na porta. Por exemplo: "Alice e Bob estão na porta da frente".
RunCycle O dispositivo conclui um ciclo. Por exemplo: "O ciclo da máquina de lavar roupa foi concluído."
SensorState O dispositivo detecta um estado de sensor compatível. Por exemplo: "O detector de fumaça está detectando fumaça."

As características a seguir oferecem suporte a respostas de acompanhamento:

Traço Eventos
LockUnlock O status de conclusão e a mudança de 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á travada".
NetworkControl O status de conclusão e a mudança de estado após a execução do comando do dispositivo action.devices.commands.TestNetworkSpeed. Por exemplo: "Seu teste de velocidade de rede foi concluído. A velocidade de download no roteador do escritório é de 80,2 Kbps, e a de upload é de 9,3 Kbps."
OpenClose O status de conclusão e a mudança de 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".

Todos os tipos de dispositivo oferecem suporte a notificações para os traços aplicáveis.

Criar notificações para a integração entre nuvens

Adicione notificações à integração Cloud-to-cloud nestas etapas:

  1. Indique ao Google se as notificações estão ativadas no app do dispositivo smart home. Se os usuários ativarem ou desativar notificações no app, envie uma solicitação SYNC para informar o Google sobre a mudança no dispositivo.
  2. Quando um evento ou mudança de estado relevante do dispositivo ocorre e aciona uma notificação, envie uma solicitação de notificação chamando a API reportStateAndNotification Report State. Se o estado do dispositivo mudar, você poderá enviar um payload de estado e de notificação juntos na chamada Report State e de notificação.

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

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

Os usuários podem escolher se querem receber notificações proativas ativando esse recurso no GHA. No app para o dispositivo smart home, também é possível adicionar a capacidade de os usuários alternarem 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 ativar explicitamente as notificações no app do dispositivo ou se você não oferecer uma opção de ativação, defina a propriedade devices.notificationSupportedByAgent como true.
  • Se o usuário tiver desativado as notificações no app do dispositivo, defina a propriedade devices.notificationSupportedByAgent como false.

O snippet abaixo mostra um exemplo de como definir a resposta SYNC:

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

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

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

Ativar a API Google HomeGraph

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

    Acessar a página da API HomeGraph
  2. Selecione o projeto que corresponde ao ID do projeto smart home.
  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 do Google Cloud Console:

Observação: verifique se você está usando o projeto correto do GCP ao realizar estas etapas. Este é o projeto que corresponde ao ID do projeto smart home.

  1. No Google Cloud Console, 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 de token de conta de serviço.

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

  7. Clique em Criar. O download de um arquivo JSON com a chave é feito no 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 ID aleatório diferente sempre que você enviar 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 do atributo do dispositivo.

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

Enviar um payload de notificação proativa

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 baixado para criar um token da Web JSON (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
  2. Receba 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
  3. Crie a solicitação JSON com o agentUserId. Confira um exemplo de solicitação JSON para Report State e notificação:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Combine o Report State e o JSON de notificação e o token na sua solicitação HTTP POST com o endpoint do Google Home Graph. Confira um exemplo de como fazer a solicitação na linha de comando usando curl, como teste:
    5. 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. Receba a definição de serviço de Buffers de protocolo para a API Home Graph.
  2. Siga a documentação para desenvolvedores do gRPC e gere stubs de cliente para uma das linguagens aceitas .
  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 credenciais padrão do aplicativo.
  2. Chame o método reportStateAndNotification com o 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 oferece vinculações para a API Home Graph.

  1. Inicialize o HomeGraphApiService usando Application Default Credentials.
  2. Chame o método reportStateAndNotification com o 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);
Enviar 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 evento, se aplicável, e o followUpToken válido, fornecido durante a solicitação de intent EXECUTE. O followUpToken precisa ser usado em até 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 exibir a notificação apenas no dispositivo com que o usuário estava interagindo originalmente, e não em todos os dispositivos do usuário.

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 baixado para criar um token da Web JSON (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
  2. Receba 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
  3. Crie a solicitação JSON com o agentUserId. Confira um exemplo de solicitação JSON para Report State e notificação:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Combine o Report State e o JSON de notificação e o token na sua solicitação HTTP POST com o endpoint do Google Home Graph. Confira um exemplo de como fazer a solicitação na linha de comando usando curl, como teste:
    5. 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. Receba a definição de serviço de Buffers de protocolo para a API Home Graph.
  2. Siga a documentação para desenvolvedores do gRPC e gere stubs de cliente para uma das linguagens aceitas.
  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 credenciais padrão do aplicativo.
  2. Chame o método reportStateAndNotification com o 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 oferece vinculações para a API Home Graph.

  1. Inicializar o HomeGraphApiService usando Application Default Credentials
  2. Chame o método reportStateAndNotification com o 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);

Logging

As notificações oferecem suporte ao registro de eventos, conforme descrito em Registro do Cloud para Cloud-to-Cloud. Esses registros são úteis para testar e manter a qualidade das notificações na sua ação.

Confira a seguir o esquema de uma entrada notificationLog:

Propriedade Descrição
requestId ID da solicitação de notificação.
structName Nome da estrutura 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. Algumas delas podem estar disponíveis apenas em ações que não foram lançadas para produção.

Exemplos de status incluem:

Status Descrição
EVENT_ID_MISSING Indica que o campo obrigatório eventId está ausente.
PRIORITY_MISSING Indica que um campo priority está ausente.
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 que envia notificações no GHA. Esse status está disponível apenas em integrações que não foram lançadas para produção.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indica que o usuário não atribuiu o dispositivo de notificação a uma casa ou estrutura. Esse status está disponível apenas para integrações que ainda 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).

Anterior
Implementar estado do relatório
Próxima
Testar uma integração entre nuvens