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

As notificações permitem que sua integração do Cloud-to-cloud use o Google Assistant para comunicar aos 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 solicitada no estado do dispositivo, como quando um ferrolho de porta foi travado ou emperrado.

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

• Notificações proativas: alerta o usuário sobre um evento de dispositivo smart home sem solicitações anteriores 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 dispositivo que levam tempo para serem concluídos. As respostas de acompanhamento só são compatíveis quando as solicitações de comando do dispositivo são enviadas de alto-falantes inteligentes e smart displays.

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

Eventos que acionam notificações

Quando ocorrem eventos no dispositivo, seu fulfillment envia uma solicitação de notificação ao Google. As características do dispositivo compatíveis com sua integração do 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 atributos são compatíveis com as notificações proativas:

Os seguintes atributos são compatíveis com respostas de acompanhamento:

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

Criar notificações para sua integração de nuvem para nuvem

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

1. Indique ao Google se as notificações estão ativadas no smart home app do dispositivo. Se os usuários ativarem ou desativarem as notificações no app, envie uma solicitação SYNC para informar ao Google sobre a mudança no dispositivo.
2. Quando ocorre um evento ou uma mudança de estado relevante no dispositivo que aciona uma notificação, envie uma solicitação de notificação chamando a API Report State reportStateAndNotification. 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 abaixo trazem mais detalhes sobre essas etapas.

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 do dispositivo smart home, você também pode adicionar a opção para que os usuários ativem ou desativem 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 tiver ativado as notificações no app do dispositivo ou se você não oferecer uma opção ativar/desativar, defina a propriedade devices.notificationSupportedByAgent como true.
• Se o usuário desativou explicitamente as notificações no app do dispositivo, defina a propriedade devices.notificationSupportedByAgent como false.

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

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

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

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

Ativar a API Google HomeGraph

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

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

1. No Google Cloud Console, acesse a página Contas de serviço.

   Acesse a página Contas de serviço.

   Talvez seja necessário selecionar um projeto antes de acessar a página "Contas de serviço".

2. Clique em addCriar 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. No campo Descrição da conta de serviço, insira uma descrição.

6. Clique em Criar e continuar.

7. No menu suspenso Papel, selecione Contas de serviço > Criador de token de identidade do OpenID Connect da conta de serviço.

8. Clique em Continuar.

9. Clique em Concluído.

10. Selecione a conta de serviço que você acabou de criar na lista de contas de serviço e selecione Gerenciar chaves no menu more_vert Ações.

11. Selecione Adicionar chave > Criar nova chave.

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

13. Clique em Criar. Um arquivo JSON com sua chave será salvo 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 que você transmite na chamada de API, inclua um valor priority que define como a notificação deve 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
• Enviar um payload de resposta de acompanhamento

Enviar um payload de notificação proativa

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

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
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 do 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 enviar a notificação apenas ao dispositivo com que o usuário estava interagindo originalmente, e não para todos os dispositivos do usuário.

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

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,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 são compatíveis com o registro de eventos, conforme descrito em Cloud Logging 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:

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:

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 atributos, quando aplicável (por exemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).