As notificações permitem que a ação smart home use 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 pontuais do dispositivo, por exemplo, quando alguém está na porta ou para informar uma mudança de estado solicitada, como quando uma fechadura foi engajada ou está destrancada.
Sua ação smart home pode enviar os seguintes tipos de notificação aos usuários:
Notificações proativas: alerta o usuário sobre um evento de dispositivo smart home sem nenhuma solicitação anterior do usuário, como a campainha.
Respostas de acompanhamento: uma confirmação de que uma solicitação de comando do dispositivo foi bem-sucedida ou não, por exemplo, ao trancar uma porta. Use esses alertas nos comandos do dispositivo que levam algum tempo para serem concluídos.
O Assistant 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 Google Home app (GHA).
Eventos que acionam notificações
Quando os eventos do dispositivo ocorrem, a realização da ação envia uma solicitação de notificação ao Google. O dispositivo que as ações smart home oferecem determina determina os tipos de eventos de notificaçã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 |
---|---|
ObjectDetection | 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 (em inglês) | O dispositivo detecta um estado de sensor compatível. Por exemplo: "O detector de fumaça detecta fumaça". |
TemperatureControl (em inglês) | O dispositivo atinge um ponto de temperatura definido. Por exemplo: "O forno foi pré-aquecido em 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 | Vincule à transmissão ao vivo da câmera depois que um objeto ou movimento for detectado pelo dispositivo. |
MotionDetection | "Um movimento foi detectado às 12h do dia 1o de julho de 2020." |
As seguintes características são compatíveis com respostas de acompanhamento:
Característica | Eventos |
---|---|
ArmDisarm (link em inglês) | Mudança do status e do estado de conclusão após a execução do
comando do dispositivo action.devices.commands.ArmDisarm . Por exemplo:
"O sistema de segurança foi ligado".
|
LockUnlock (em inglês) | Mudança do status e do estado de conclusão 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 (em inglês) | Mudança do status e do estado de conclusão após a execução do
comando do dispositivo action.devices.commands.TestNetworkSpeed . Por
exemplo: "Seu teste de velocidade da rede terminou. A velocidade de
download do roteador do escritório é de 80,2 Kbps e a de upload é de 9,3 Kbps."
|
OpenClose. | Mudança do status e do estado de conclusão após a execução do
comando do dispositivo action.devices.commands.OpenClose . Por
exemplo: "Não foi possível abrir a porta da frente" ou "Não foi possível abrir a porta da frente".
|
StartStop | Mudança do status e do estado de conclusão 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 de características aplicáveis.
Criar notificações para sua ação de casa inteligente
Adicione notificações à sua ação smart home nestes estágios:
- Indique ao Google se as notificações estão ativadas no seu
dispositivo smart home. 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 no dispositivo. - Quando ocorrer um evento de dispositivo ou estado de dispositivo relevante 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 notificação em Report State e na chamada de notificação.
As seções a seguir abordam essas etapas com mais detalhes.
Indique se as notificações estão ativadas no seu app
Os usuários podem escolher se querem receber notificações proativas ativando esse recurso na GHA. No app para o dispositivo smart home, você também pode adicionar a possibilidade de os usuários alternarem explicitamente as notificações do dispositivo, por exemplo, das 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 as notificações explicitamente no app do dispositivo ou se você
não fornecer uma opção de alternância, defina a
propriedade
devices.notificationSupportedByAgent
comotrue
. - Se o usuário desativar explicitamente as notificações no app do dispositivo, defina a
propriedade
devices.notificationSupportedByAgent
comofalse
.
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, o fulfillment envia um payload de notificação para o Google Home Graph usando uma Report State e uma chamada da API Notification.
Ativar a API Google HomeGraph
-
No Google Cloud Platform Console, acesse a página da API HomeGraph.
Acessar a página da API HomeGraph - Selecione o projeto que corresponde ao ID do seu projeto smart home.
- 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 GCP Console:
-
No GCP Console, acesse a página Criar chave da conta de serviço.
Acessar página "Criar chave da conta de serviço" - Na lista Conta de serviço, selecione Nova conta de serviço.
- No campo Nome da conta de serviço, insira um nome.
- No campo ID da conta de serviço, digite um ID.
Na lista Papel, selecione Contas de serviço > Criador do token da conta de serviço.
Em Tipo de chave, selecione a opção JSON.
- Clique em Criar. O download de um arquivo JSON com a chave vai ser 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. Seu
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.
- Use o arquivo JSON da conta de serviço salva para criar um JSON Web Token (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
- Consiga um token de acesso do OAuth 2.0 com o
escopo
https://www.googleapis.com/auth/homegraph
usando oauth2l: - Crie a solicitação JSON com
agentUserId
. Veja um exemplo de solicitação JSON para Report State e notificação: - Combine o Report State, o JSON de notificação e o token na solicitação POST HTTP
para o endpoint do Google Home Graph. Veja um exemplo de como
fazer a solicitação na linha de comando usando
curl
como teste:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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 do gRPC.
- Encontre a definição de serviço dos buffers de protocolo para a API Home Graph.
- Siga a documentação do desenvolvedor do gRPC para gerar stubs de cliente para uma das linguagens compatíveis.
- Chame o método ReportStateAndNotification.
Node.js
O cliente de APIs do Google para Node.js fornece vinculações para a API Home Graph.
- Inicialize o serviço do
google.homegraph
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com o ReportStateAndNotificationRequest. Ele retorna umPromise
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 Home Graph.
- Inicialize o
HomeGraphApiService
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com oReportStateAndNotificationRequest
. Ela retorna umReportStateAndNotificationResponse
.
// 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, os códigos de erro das falhas de eventos, se aplicável, e o followUpToken
válido, fornecido durante a solicitação de intent EXECUTE
. O followUpToken
precisa ser usado
dentro de 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 a followUpToken
para gerar a notificação apenas no dispositivo com que o usuário estava interagindo originalmente e não para transmissã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.
- Use o arquivo JSON da conta de serviço salva para criar um JSON Web Token (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
- Consiga um token de acesso do OAuth 2.0 com o
escopo
https://www.googleapis.com/auth/homegraph
usando oauth2l: - Crie a solicitação JSON com
agentUserId
. Veja um exemplo de solicitação JSON para Report State e notificação: - Combine o Report State, o JSON de notificação e o token na solicitação POST HTTP
para o endpoint do Google Home Graph. Veja um exemplo de como
fazer a solicitação na linha de comando usando
curl
como teste:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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 do gRPC.
- Encontre a definição de serviço dos buffers de protocolo para a API Home Graph.
- Siga a documentação do desenvolvedor do gRPC para gerar stubs de cliente para uma das linguagens compatíveis.
- Chame o método ReportStateAndNotification.
Node.js
O cliente de APIs do Google para Node.js fornece vinculações para a API Home Graph.
- Inicialize o serviço do
google.homegraph
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com o ReportStateAndNotificationRequest. Ele retorna umPromise
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 Home Graph.
- Inicialize o
HomeGraphApiService
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com oReportStateAndNotificationRequest
. Retorna umReportStateAndNotificationResponse
// 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 em Acessar logs de eventos com o Cloud Logging. Esses registros são úteis para testar e manter a qualidade das notificações na 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 de notificação. Alguns deles podem estar disponíveis apenas em ações que
não foram lançadas para produção.
Veja alguns exemplos de status:
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 do GHA. Esse status só está disponível em Açõ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/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 da característica, quando aplicável (por exemplo, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).