As notificações permitem que a ação smart home use Google Assistant para se comunicar com os usuários sobre informações aos eventos ou mudanças relacionados ao dispositivo. É possível implementar notificações para alertar os usuários a eventos oportunos do dispositivo, por exemplo, quando alguém está na porta ou informa sobre uma mudança de estado solicitada no dispositivo, como quando uma fechadura de porta foi engajado com sucesso ou ficou emperrado.
Sua ação smart home pode enviar os seguintes tipos de notificações aos usuários:
Notificações proativas: alertam o usuário sobre um smart home. evento do dispositivo sem nenhuma solicitação anterior do usuário aos dispositivos dele, como campainha.
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 de comandos do dispositivo que levam tempo para serem concluídos. As respostas de acompanhamento são apenas compatível quando solicitações de comando do dispositivo são enviadas de alto-falantes e inteligentes é exibido.
Assistant fornece essas notificações aos usuários como do Google em alto-falantes inteligentes e smart displays. 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 do dispositivo, o cumprimento da Ação envia uma solicitação de notificação para o Google. As características do dispositivo que a Ação smart home oferece determina quais tipos de eventos de notificação estão disponíveis e dados que você pode incluir nessas notificações.
As seguintes características são compatíveis com as notificações proativas:
Características | 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ída." |
SensorState | O dispositivo detecta um estado de sensor compatível. Por exemplo: "O detector de fumaça está detectando fumaça." |
As seguintes características são compatíveis com as respostas de acompanhamento:
Características | Eventos |
---|---|
LockUnlock | Status de conclusão e alteração de estado após a execução do
Comando do dispositivo action.devices.commands.LockUnlock . Para
exemplo: "A porta da frente foi trancada ou "A porta da frente está emperrada."
|
NetworkControl | Status de conclusão e alteração de estado após a execução do
Comando do dispositivo action.devices.commands.TestNetworkSpeed . Para
exemplo: "O teste de velocidade da sua rede foi concluído. A velocidade de download em
o roteador do escritório tem 80,2 Kbps e a velocidade de upload é de 9,3 Kbps."
|
OpenClose | Status de conclusão e alteração de estado após a execução do
Comando do dispositivo action.devices.commands.OpenClose . Para
Exemplo: "A porta da frente se abriu" ou "Não foi possível abrir a porta da frente."
|
Todos os tipos de dispositivos são compatíveis com as notificações das características aplicáveis.
Criar notificações para a ação de casa inteligente
Adicione notificações à sua ação smart home nestas etapas:
- Indicar ao Google se as notificações estão ativadas no seu
App do dispositivo smart home. Se os usuários ativarem ou desativarem as notificações
no seu app, envie uma solicitação
SYNC
para informar o Google sobre a mudança do dispositivo. - Quando ocorre um evento relevante ou mudança de estado do dispositivo que aciona uma
envie uma solicitação de notificação chamando o método
API Report State
reportStateAndNotification
. Se o estado do dispositivo alterado, é possível enviar um payload de estado e de notificação na chamada Report State e de notificação.
As seções abaixo apresentam essas etapas em mais detalhes.
Indicar se as notificações estão ativadas no app
Os usuários podem escolher se querem receber notificações proativas ativar esse recurso no GHA. No app da sua smart home dispositivo. Também é possível adicionar a capacidade de que os usuários alternem explicitamente as notificações do dispositivo, por exemplo, de as configurações do app.
Para indicar ao Google que as notificações estão ativadas no seu dispositivo,
uma chamada Request SYNC
para atualizar os dados do dispositivo. Envie uma solicitação SYNC
como esta sempre que
os usuários mudem
essa configuração no app.
Na sua resposta a SYNC
, envie uma destas atualizações:
- Se o usuário tiver ativado as notificações explicitamente no app do dispositivo ou se você
não fornecem uma opção de alternância, defina o
a propriedade
devices.notificationSupportedByAgent
comotrue
. - Se o usuário desativou as notificações explicitamente no app do dispositivo, defina o
a propriedade
devices.notificationSupportedByAgent
comofalse
.
O snippet a seguir mostra um exemplo de como configurar a resposta SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Enviar solicitações de notificação ao Google
Para acionar notificações no Assistant, seu O fulfillment envia um payload de notificação para o Google Home Graph usando um Report State e uma chamada da API Notification.
Ativar a API Google HomeGraph
-
No Google Cloud Console, acesse a página API HomeGraph.
Acessar a página da API HomeGraph - Selecione o projeto que corresponde ao ID do seu projeto do smart home.
- Clique em ATIVAR.
Criar uma chave de conta de serviço
Siga estas instruções para gerar uma chave da conta de serviço do Google Cloud Console:
-
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" - 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, insira um ID.
Na lista Papel, selecione Contas de serviço > Criador de token da conta de serviço.
Em Tipo de chave, selecione a opção JSON.
- Clique em Criar. Um arquivo JSON que contém a chave para o seu computador.
Enviar a notificação
Faça a chamada de solicitação de notificação usando o método
API devices.reportStateAndNotification
.
Sua solicitação JSON precisa incluir um eventId
, que é um ID exclusivo gerado pelo
sua plataforma para o evento que aciona a notificação. O eventId
precisa
ser um ID aleatório que é diferente toda vez que você envia 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. Seu
O objeto notifications
pode incluir campos diferentes, dependendo do dispositivo.
característica.
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 salvo 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 a
escopo
https://www.googleapis.com/auth/homegraph
usando oauth2l: - Crie a solicitação JSON com o
agentUserId
. Este é um exemplo de solicitação JSON para Report State e notificação: - Combine o Report State e o JSON de notificação com o token no HTTP POST
para o endpoint do Google Home Graph. Aqui está um exemplo de como
para fazer a solicitação na linha de comando usando
curl
, conforme um 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 uma Endpoint do gRPC
- Confira a definição do serviço de 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 Node.js das APIs do Google fornece vinculações para a API Home Graph.
- Inicialize o serviço
google.homegraph
com 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 à API Home Graph.
- Inicialize o
HomeGraphApiService
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com oReportStateAndNotificationRequest
. Ele 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, erro
códigos para falhas de evento, se aplicável, e os followUpToken
válidos,
fornecidos durante a solicitação de intent EXECUTE
. O followUpToken
precisa ser usado
em até cinco minutos para permanecerem válidos e associarem a resposta
à solicitação original.
O snippet a seguir mostra um exemplo de payload de solicitação EXECUTE
com um
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 a qual o usuário estava interagindo originalmente e não transmitiu para todos os
dispositivos do usuário.
Para chamar a API, selecione uma opção nestas guias:
HTTP
A API Home Graph fornece um endpoint HTTP.
- 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.
- Consiga um token de acesso do OAuth 2.0 com a
escopo
https://www.googleapis.com/auth/homegraph
usando oauth2l: - Crie a solicitação JSON com o
agentUserId
. Este é um exemplo de solicitação JSON para Report State e notificação: - Combine o Report State e o JSON de notificação com o token no HTTP POST
para o endpoint do Google Home Graph. Aqui está um exemplo de como
para fazer a solicitação na linha de comando usando
curl
, conforme um 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 gRPC.
- Confira a definição do serviço de 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 Node.js das APIs do Google fornece vinculações para a API Home Graph.
- Inicialize o serviço
google.homegraph
com 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 à API Home Graph.
- Inicialize o
HomeGraphApiService
usando o Application Default Credentials - Chame o método
reportStateAndNotification
com oReportStateAndNotificationRequest
. Ele 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);
Logging
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 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 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 na
payload de notificação. Algumas delas podem estar disponíveis somente em ações
que não foram lançados para produção.
Confira 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 de notificação no 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 notificante 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
).