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

Com as notificações, sua integração do Cloud-to-cloud pode usar o Google Assistant para se comunicar com os usuários sobre eventos ou mudanças importantes relacionados ao dispositivo. Você pode 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 solicitada, como quando uma trava de porta foi engatada ou travada.

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

• Notificações proativas: alertam o usuário sobre um evento de dispositivo smart home sem solicitações anteriores aos dispositivos, como o toque da campainha.

• Respostas de acompanhamento: uma confirmação de que uma solicitação de comando de dispositivo foi bem-sucedida ou falhou, por exemplo, ao trancar uma porta. Use esses alertas para comandos de dispositivos que levam tempo para serem concluídos. As respostas complementares só são compatíveis quando os comandos do dispositivo são enviados de alto-falantes e smart displays.

O Assistant envia essas notificações aos usuários como anúncios em alto-falantes 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 eventos de dispositivo ocorrem, 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 os tipos de eventos de notificação disponíveis e os dados que podem ser incluídos nessas notificações.

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

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

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

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

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

1. Indique ao Google se as notificações estão ativadas no app smart home 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 um evento ou uma mudança de estado relevante do dispositivo acionar uma notificação, envie uma solicitação de notificação chamando a API Report State reportStateAndNotification. Se o estado do dispositivo mudou, você pode enviar um estado e uma carga útil de notificação juntos na sua chamada de Report State e 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 nas GHA. No app do seu dispositivo smart home, você também pode adicionar a opção de os usuários ativarem ou desativarem as notificações do dispositivo, por exemplo, nas configurações do app.

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

Na sua 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/desativação, 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 definir sua resposta SYNC:

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

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

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

Ativar a API Google HomeGraph

1. No Google Cloud Console, acesse a página da 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 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 do 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 escolha 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. O download de um arquivo JSON com sua 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 a cada solicitação de notificação.

No objeto notifications transmitido 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 da característica 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 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 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 mostrar a notificação apenas no dispositivo com que o usuário estava interagindo originalmente, e não em todos os dispositivos dele.

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 oferecem suporte ao 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 traços, quando aplicável (por exemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).