Notifiche per le Azioni per la smart home

Le notifiche consentono all'Azione smart home di utilizzare Google Assistant per comunicare con gli utenti in merito a cambiamenti o eventi importanti relativi al dispositivo. Puoi implementare le notifiche per avvisare gli utenti di eventi del dispositivo tempestivi, ad esempio quando c'è qualcuno alla porta, o per segnalare la richiesta di modifica dello stato del dispositivo, ad esempio quando la serratura di una porta è stata azionata correttamente o si è bloccata.

L'Azione smart home può inviare i seguenti tipi di notifiche agli utenti:

  • Notifiche proattive: avvisa l'utente di un evento del dispositivo smart home senza alcuna richiesta precedente da parte dell'utente ai suoi dispositivi, ad esempio il campanello che suona.

  • Risposte di follow-up: la conferma che una richiesta di comando del dispositivo è riuscita o non è riuscita, ad esempio quando è stata chiusa una porta. Utilizza questi avvisi per i comandi del dispositivo che richiedono del tempo per essere completati. Le risposte di follow-up sono supportate solo quando le richieste di comando del dispositivo vengono inviate da smart speaker e smart display.

Assistant fornisce queste notifiche agli utenti come annunci su smart speaker e smart display. Le notifiche proattive sono disattivate per impostazione predefinita. Gli utenti possono attivare o disattivare tutte le notifiche proattive da Google Home app (GHA).

Eventi che attivano le notifiche

Quando si verificano eventi relativi ai dispositivi, l'evasione delle azioni invia una richiesta di notifica a Google. I trait del dispositivo supportati dall'Azione smart home determinano i tipi di eventi di notifica disponibili e i dati che puoi includere nelle notifiche.

Le seguenti caratteristiche supportano le notifiche proattive:

Tratto Eventi
ObjectDetection Oggetti rilevati dal dispositivo, ad esempio quando viene rilevato un volto riconosciuto alla porta. Ad esempio: "Alice e Bob sono alla porta d'ingresso".
RunCycle Il dispositivo completa un ciclo. Ad esempio: "Il ciclo di lavatrice è terminato."
SensorState Il dispositivo rileva uno stato del sensore supportato. Ad esempio: "Il rilevatore di fumo rileva fumo".
TemperatureControl Il dispositivo raggiunge un set-point di temperatura. Ad esempio: "Il forno è stato preriscaldato a 350 gradi".
ArmDisarm Il sistema entra in uno stato di pre-allarme con un conto alla rovescia per l'ingresso, attivato da una porta aperta.
CameraStream Link al live streaming della videocamera dopo che il dispositivo rileva un oggetto o un movimento.
MotionDetection "È stato rilevato un movimento alle 12:00 del 1° luglio 2020."

Le seguenti caratteristiche supportano le risposte di follow-up:

Tratto Eventi
ArmDisarm Lo stato di completamento e la modifica dello stato dopo l'esecuzione del comando del dispositivo action.devices.commands.ArmDisarm. Ad esempio: "Il sistema di sicurezza è stato abilitato."
LockUnlock Lo stato di completamento e la modifica dello stato dopo l'esecuzione del comando del dispositivo action.devices.commands.LockUnlock. Ad esempio: "La porta principale è stata chiusa" o "La porta principale è bloccata".
NetworkControl Lo stato di completamento e la modifica dello stato dopo l'esecuzione del comando del dispositivo action.devices.commands.TestNetworkSpeed. Ad esempio: "Il test di velocità della rete è terminato. Al momento, la velocità di download del router dell'ufficio è di 80,2 Kbps, mentre la velocità di caricamento è di 9,3 Kbps."
OpenClose Lo stato di completamento e la modifica dello stato dopo l'esecuzione del comando del dispositivo action.devices.commands.OpenClose. Ad esempio: "La porta principale è stata aperta" o "Impossibile aprire la porta d'ingresso".
StartStop Lo stato di completamento e la modifica dello stato dopo l'esecuzione del comando del dispositivo action.devices.commands.StartStop. Ad esempio: "L'aspirapolvere è stato avviato".

Tutti i tipi di dispositivi supportano le notifiche per i trait applicabili.

Crea notifiche per la tua azione per la smart home

Aggiungi notifiche all'Azione smart home in queste fasi:

  1. Indica a Google se sono attive le notifiche dall'app del tuo dispositivo smart home. Se gli utenti attivano o disattivano le notifiche nella tua app, invia una richiesta SYNC per informare Google del cambio di dispositivo.
  2. Quando si verifica un evento del dispositivo o un cambio di stato pertinente che attiva una notifica, invia una richiesta di notifica chiamando l'API Report State reportStateAndNotification. Se lo stato del dispositivo è cambiato, puoi inviare sia uno stato sia un payload di notifica nella chiamata Report State e nella chiamata di notifica.

Questi passaggi vengono trattati nelle sezioni seguenti in modo più dettagliato.

Indicare se le notifiche sono attive nella tua app

Gli utenti possono scegliere se ricevere notifiche proattive attivando questa funzionalità in GHA. Nell'app per il tuo dispositivo smart home, puoi anche aggiungere facoltativamente la possibilità per gli utenti di attivare o disattivare le notifiche dal dispositivo in modo esplicito, ad esempio dalle impostazioni dell'app.

Indica a Google che le notifiche sono attive per il tuo dispositivo effettuando una chiamata Richiedi SINCRONIZZAZIONE per aggiornare i dati del dispositivo. Devi inviare una richiesta SYNC come questa ogni volta che gli utenti modificano questa impostazione nella tua app.

Nella risposta SYNC, invia uno di questi aggiornamenti:

  • Se l'utente ha attivato esplicitamente le notifiche nell'app del dispositivo o se non fornisci un'opzione di attivazione/disattivazione, imposta la proprietà devices.notificationSupportedByAgent su true.
  • Se l'utente ha disattivato esplicitamente le notifiche nell'app del tuo dispositivo, imposta la proprietà devices.notificationSupportedByAgent su false.

Lo snippet seguente mostra un esempio di come impostare la risposta SYNC:

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

Invia richieste di notifica a Google

Per attivare le notifiche su Assistant, il tuo fulfillment invia un payload di notifica a Google Home Graph tramite una chiamata API Report State e Notification.

Attiva l'API Google HomeGraph

  1. In Google Cloud Console, vai alla pagina dell'API HomeGraph.

    Vai alla pagina dell'API HomeGraph
  2. Seleziona il progetto che corrisponde al tuo ID progetto smart home.
  3. Fai clic su ABILITA.

Crea una chiave dell'account di servizio

Segui queste istruzioni per generare una chiave dell'account di servizio dal Google Cloud Console:

Nota: assicurati di utilizzare il progetto Google Cloud corretto quando esegui questi passaggi. Questo è il progetto che corrisponde al tuo ID progetto smart home.

  1. In Google Cloud Console, vai alla pagina Crea chiave account di servizio.

    Vai alla pagina Crea chiave account di servizio
  2. Dall'elenco Account di servizio, seleziona Nuovo account di servizio.
  3. Inserisci un nome nel campo Nome account di servizio.
  4. Inserisci un ID nel campo ID account di servizio.

  5. Nell'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

  6. In Tipo di chiave, seleziona l'opzione JSON.

  7. Fai clic su Crea. Sul computer viene scaricato un file JSON contenente la chiave.

Invia la notifica

Effettua la chiamata di richiesta di notifica utilizzando l'API devices.reportStateAndNotification. La richiesta JSON deve includere un eventId, ovvero un ID univoco generato dalla tua piattaforma per l'evento che attiva la notifica. eventId deve essere un ID casuale diverso ogni volta che invii una richiesta di notifica.

Nell'oggetto notifications che passi nella chiamata API, includi un valore priority che definisce il modo in cui deve essere presentata la notifica. L'oggetto notifications può includere campi diversi a seconda della caratteristica del dispositivo.

Segui uno di questi percorsi per impostare il payload e chiamare l'API:

Invia un payload di notifica proattiva

Per chiamare l'API, seleziona un'opzione da una di queste schede:

HTTP

L'API Home Graph fornisce un endpoint HTTP

  1. Utilizza il file JSON dell'account di servizio scaricato per creare un token JWT (JSON Web Token). Per maggiori informazioni, consulta la pagina relativa all' autenticazione tramite account di servizio.
  2. Ottieni un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/homegraph utilizzando oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Crea la richiesta JSON con l'elemento agentUserId. Ecco un esempio di richiesta JSON per Report State e Notification:
    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. Combina i valori JSON Report State e Notification e il token nella richiesta HTTP POST all'endpoint di Google Home Graph. Ecco un esempio di come effettuare la richiesta nella riga di comando utilizzando curl, come test:
    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

L'API Home Graph fornisce un endpoint gRPC

  1. Recupera la definizione del servizio di buffer di protocollo per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per una delle lingue supportate.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

Il client Node.js delle API di Google fornisce associazioni per l'API Home Graph.

  1. Inizializza il servizio google.homegraph utilizzando Credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce un valore Promise con 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

La libreria client dell'API HomeGraph per Java fornisce associazioni per l'API Home Graph.

  1. Inizializza HomeGraphApiService utilizzando Credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce un 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);
Invia payload di risposta di follow-up

Il payload per una risposta di follow-up contiene lo stato della richiesta, i codici di errore per gli errori dell'evento, se applicabile, e il valore followUpToken valido, fornito durante la richiesta di intent EXECUTE. followUpToken deve essere utilizzato entro cinque minuti per rimanere valido e associare correttamente la risposta alla richiesta originale.

Lo snippet seguente mostra un payload di esempio di richiesta EXECUTE con un 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"
          }
        }]
      }]
    }
  }]
};

Google utilizza followUpToken per inviare la notifica solo sul dispositivo con cui l'utente ha interagito inizialmente e non per trasmettere la notifica su tutti i dispositivi dell'utente.

Per chiamare l'API, seleziona un'opzione da una di queste schede:

HTTP

L'API Home Graph fornisce un endpoint HTTP

  1. Utilizza il file JSON dell'account di servizio scaricato per creare un token JWT (JSON Web Token). Per maggiori informazioni, consulta la pagina relativa all' autenticazione tramite account di servizio.
  2. Ottieni un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/homegraph utilizzando oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Crea la richiesta JSON con l'elemento agentUserId. Ecco un esempio di richiesta JSON per Report State e Notification:
    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. Combina i valori JSON Report State e Notification e il token nella richiesta HTTP POST all'endpoint di Google Home Graph. Ecco un esempio di come effettuare la richiesta nella riga di comando utilizzando curl, come test:
    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

L'API Home Graph fornisce un endpoint gRPC

  1. Recupera la definizione del servizio di buffer di protocollo per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per una delle lingue supportate.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

Il client Node.js delle API di Google fornisce associazioni per l'API Home Graph.

  1. Inizializza il servizio google.homegraph utilizzando Credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce un valore Promise con 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

La libreria client dell'API HomeGraph per Java fornisce associazioni per l'API Home Graph.

  1. Inizializza HomeGraphApiService utilizzando Credenziali predefinite dell'applicazione
  2. Chiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce un 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

Le notifiche supportano il logging degli eventi, come descritto nell'articolo Accedere ai log eventi con Cloud Logging. Questi log sono utili per testare e mantenere la qualità delle notifiche nell'Azione.

Di seguito è riportato lo schema di una voce notificationLog:

Proprietà Descrizione
requestId ID richiesta di notifica.
structName Nome dello struct di notifica, ad esempio "ObjectDetection".
status Indica lo stato della notifica.

Il campo status include vari stati che possono indicare errori nel payload delle notifiche. Alcune di queste azioni potrebbero essere disponibili solo per le azioni che non sono state lanciate in produzione.

Gli stati di esempio includono:

Stato Descrizione
EVENT_ID_MISSING Indica che il campo obbligatorio eventId non è presente.
PRIORITY_MISSING Indica che un campo priority non è presente.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indica che la proprietà notificationSupportedByAgent del dispositivo di notifica fornita in SYNC è falsa.
NOTIFICATION_ENABLED_BY_USER_FALSE Indica che l'utente non ha attivato le notifiche sul dispositivo di notifica in GHA. Questo stato è disponibile solo per le azioni che non sono state lanciate in produzione.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indica che l'utente non ha assegnato il dispositivo di notifica a una Casa/Struttura. Questo stato è disponibile solo per le azioni che non sono state lanciate in produzione.

Oltre a questi stati generali applicabili a tutte le notifiche, il campo status può anche includere stati specifici del trait (ad es. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING), ove applicabile.

Indietro
Implementare lo stato del report
Avanti
Prova e condividi azioni