Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per scoprire come sviluppare azioni per la smart home. Nota: continuerai a creare azioni nella console di Actions.

Notifiche per le azioni della smart home

Le notifiche consentono all'azione smart home di utilizzare Google Assistant per comunicare agli utenti informazioni su eventi o modifiche importanti relativi al dispositivo. Puoi implementare notifiche per avvisare gli utenti di eventi tempestivi del dispositivo, ad esempio quando c'è qualcuno alla porta, oppure per segnalare una modifica richiesta dello stato del dispositivo, ad esempio quando un chiavistello della serratura della porta è stato inserito correttamente o si è inceppato.

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

  • Notifiche proattive: avvisa l'utente di un evento relativo ai dispositivi smart home senza richieste precedenti da parte degli utenti ai suoi dispositivi, ad esempio il campanello.

  • Risposte di follow-up: una conferma che una richiesta di comando del dispositivo ha avuto esito positivo o negativo, ad esempio quando hai chiuso 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 comandi dei dispositivi vengono inviate da smart speaker e smart display.

Assistant fornisce queste notifiche agli utenti sotto forma di annunci su smart speaker e smart display. Le notifiche proattive sono disattivate per impostazione predefinita. Gli utenti hanno la possibilità di attivare o disattivare tutte le notifiche proattive da Google Home app (GHA).

Eventi che attivano le notifiche

Quando si verificano eventi del dispositivo, la tua distribuzione di azione invia a Google una richiesta di notifica. La caratteristica del dispositivo supportata dall'azione smart home determina quali tipi di eventi di notifica sono disponibili e i dati che puoi includere nelle notifiche.

I seguenti aspetti supportano le notifiche proattive:

Caratteristica Eventi
Rilevamento oggetti Oggetti rilevati dal dispositivo, ad esempio quando viene rilevato un volto riconosciuto alla porta. Ad esempio: "Alice e Roberto sono alla porta principale".
RunCycle Il dispositivo completa un ciclo. Ad esempio: "Il ciclo di lavatrice è terminato".
SensoreStato Il dispositivo rileva uno stato di sensore supportato. Ad esempio: "Il rilevatore di fumo rileva fumo".
Controllo della temperatura Il dispositivo raggiunge un set-point di temperatura. Ad esempio: "Il forno è stato preriscaldato a 350 gradi."
Disarmo Il sistema entra in uno stato di preallarme con un conto alla rovescia per l'ingresso attivato da una porta aperta.
Streaming videocamera Link al live streaming della videocamera in seguito al rilevamento di un oggetto o di un movimento da parte del dispositivo.
Rilevamento del movimento "Il movimento è stato rilevato alle 12:00 del 1° luglio 2020."

I seguenti tratti supportano le risposte di follow-up:

Caratteristica Eventi
Disarmo Lo stato di completamento e la modifica dello stato in seguito all'esecuzione del comando del dispositivo action.devices.commands.ArmDisarm. Ad esempio: "Il sistema di sicurezza è stato abilitato".
Sblocco con serratura Lo stato di completamento e la modifica dello stato in seguito all'esecuzione del comando del dispositivo action.devices.commands.LockUnlock. Ad esempio: "La porta d'ingresso è stata chiusa" o "La porta d'ingresso è bloccata".
Controllo rete Lo stato di completamento e la modifica dello stato in seguito all'esecuzione del comando del dispositivo action.devices.commands.TestNetworkSpeed. Ad esempio: "Il test della velocità della rete è terminato. La velocità di download sul router dell'ufficio è attualmente di 80,2 Kbps e la velocità di caricamento è di 9,3 Kbps."
Chiudi Lo stato di completamento e la modifica dello stato in seguito all'esecuzione del comando del dispositivo action.devices.commands.OpenClose. Ad esempio: "La porta d'ingresso è stata aperta" o "Impossibile aprire la porta d'ingresso".
Inizia Lo stato di completamento e la modifica dello stato in seguito all'esecuzione del comando del dispositivo action.devices.commands.StartStop. Ad esempio: "L'aspirapolvere è stato acceso".

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

Crea notifiche per la tua smart home Azione

Aggiungi notifiche all'azione smart home in queste fasi:

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

Nelle sezioni che seguono vengono descritti in dettaglio questi passaggi.

Indica se le notifiche sono attive nella tua app

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

Indica a Google che le notifiche sono attive per il 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 di 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 dispositivo, imposta la proprietà devices.notificationSupportedByAgent su false.

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

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

Inviare richieste di notifica a Google

Per attivare le notifiche su Assistant, l'evasione invia un payload di notifiche a Google Home Graph tramite una chiamata all'API Report State e di notifica.

Abilita l'API Google HomeGraph

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

    Vai alla pagina 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 da Google Cloud Console:

Nota: assicurati di utilizzare il progetto GCP 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. Nel campo Nome account di servizio, inserisci un nome.
  4. Inserisci un ID nel campo ID account di servizio.
  5. Dall'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

  6. Per il tipo di chiave, seleziona l'opzione JSON.

  7. Fai clic su Crea. Un file JSON contenente la chiave viene scaricato sul computer.

Invia la notifica

Effettuare 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 a ogni invio di una richiesta di notifica.

Nell'oggetto notifications passato nella chiamata API, includi un valore priority che definisce la modalità di presentazione della notifica. L'oggetto notifications potrebbe 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 notifiche proattive

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 web JSON (JWT), Per maggiori informazioni, consulta la pagina relativa all' autenticazione tramite un 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
    
  4. Crea la richiesta JSON con agentUserId. Ecco un esempio di richiesta JSON per Report State e notifica:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. Combina Report State e il JSON di notifica e il token nella richiesta HTTP POST con l'endpoint del grafico Google Home. Di seguito è riportato un esempio di come eseguire la richiesta nella riga di comando utilizzando curl come test:
  7. 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. Ottieni 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 uno dei lingue supportati.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

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

  1. Inizializzare il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Richiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce 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. Inizializzare HomeGraphApiService utilizzando le credenziali predefinite dell'applicazione.
  2. Richiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce 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 un payload di risposta di follow-up

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

Il seguente snippet mostra un esempio di payload della 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 emettere la notifica solo sul dispositivo con cui l'utente ha interagito originariamente e non per la trasmissione 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 web JSON (JWT), Per maggiori informazioni, consulta la pagina relativa all' autenticazione tramite un 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
    
  4. Crea la richiesta JSON con agentUserId. Ecco un esempio di richiesta JSON per Report State e notifica:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. Combina Report State e il JSON di notifica e il token nella richiesta HTTP POST con l'endpoint del grafico Google Home. Di seguito è riportato un esempio di come eseguire la richiesta nella riga di comando utilizzando curl come test:
  7. 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. Ottieni 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 uno dei lingue supportati.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

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

  1. Inizializzare il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Richiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce 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. Inizializzare HomeGraphApiService utilizzando le credenziali predefinite dell'applicazione
  2. Richiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce 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 in Accedere ai log eventi con Cloud Logging. Questi log sono utili per testare e gestire la qualità delle notifiche nella tua 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 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 è mancante.
PRIORITY_MISSING Indica che manca un campo priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indica che la proprietà notificationSupportedByAgent del dispositivo di notifica 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 soltanto 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 soltanto per le azioni che non sono state lanciate in produzione.

Oltre a questi stati generali che possono essere applicati a tutte le notifiche, il campo status può anche includere stati specifici per i tratti, se applicabili (ad esempio OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).