Notifiche per le Azioni per la smart home

Le notifiche consentono all'integrazione di Cloud-to-cloud di utilizzare Google Assistant per comunicare agli utenti eventi o modifiche importanti relativi al dispositivo. Puoi implementare notifiche per avvisare gli utenti di eventi del dispositivo tempestivi, ad esempio quando c'è qualcuno alla porta, o per segnalare una modifica dello stato del dispositivo richiesta, ad esempio quando un chiavistello della serratura della porta è stato attivato o si è bloccato.

L'integrazione di Cloud-to-cloud può inviare agli utenti i seguenti tipi di notifiche:

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

  • Risposte di follow-up: una conferma che la richiesta di un comando del dispositivo è andata a buon fine o meno, ad esempio quando si chiude una porta. Utilizza questi avvisi per i comandi del dispositivo che richiedono 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 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, l'erogazione invia una richiesta di notifica a Google. Le caratteristiche del dispositivo supportate dall'integrazione di Cloud-to-cloud determinano i tipi di eventi di notifica disponibili e i dati che puoi includere in queste notifiche.

I seguenti tratti 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 di casa."
RunCycle Il dispositivo completa un ciclo. Ad esempio: "Il ciclo della lavatrice è stato completato."
SensorState Il dispositivo rileva uno stato del sensore supportato. Ad esempio: "Il rilevatore di fumo rileva fumo."

I seguenti tratti supportano le risposte di follow-up:

Tratto Eventi
LockUnlock Stato di completamento e modifica dello stato dopo l'esecuzione del action.devices.commands.LockUnlock comando del dispositivo. Ad esempio: "La porta principale è stata chiusa a chiave" o "La porta principale è bloccata".
NetworkControl Stato di completamento e modifica dello stato dopo l'esecuzione del action.devices.commands.TestNetworkSpeed comando del dispositivo. 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 upload è di 9,3 Kbps."
OpenClose Stato di completamento e modifica dello stato dopo l'esecuzione del action.devices.commands.OpenClose comando del dispositivo. Ad esempio: "La porta d'ingresso è stata aperta" o "Impossibile aprire la porta d'ingresso".

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

Crea notifiche per l'integrazione cloud-to-cloud

Aggiungi notifiche all'integrazione di Cloud-to-cloud nelle seguenti fasi:

  1. Indica a Google se le notifiche sono attivate 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 della modifica del dispositivo.
  2. Quando si verifica una modifica dello stato o un evento del dispositivo pertinente che attiva una notifica, invia una richiesta di notifica chiamando l'API Report State reportStateAndNotification. Se lo stato del dispositivo è cambiato, puoi inviare contemporaneamente un payload di stato e di notifica nella chiamata Report State e Notification.

Le sezioni seguenti descrivono questi passaggi in modo più dettagliato.

Indicare se le notifiche sono attive nell'app

Gli utenti possono scegliere se ricevere notifiche proattive attivando questa funzionalità in GHA. Nell'app per il tuo smart home, puoi anche aggiungere facoltativamente 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 attivate per il tuo dispositivo effettuando una chiamata Request SYNC 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 dispositivo, imposta la proprietà devices.notificationSupportedByAgent su false.

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

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

Inviare 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 all'API Report State e Notification.

Abilita l'API Google HomeGraph

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

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

Creare 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 Google Cloud corretto quando esegui questi passaggi. Questo è il progetto corrispondente al tuo ID progetto smart home.

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

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

  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

Esegui 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 all'API, includi un valore priority che definisce la modalità di presentazione della notifica. L'oggetto notifications può includere campi diversi a seconda del tratto del dispositivo.

Per impostare il payload e chiamare l'API, segui uno di questi percorsi:

Inviare 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 web JSON (JWT). Per maggiori informazioni, consulta 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
  3. Crea la richiesta JSON con agentUserId. Ecco una richiesta JSON di esempio 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 Report State e il JSON di notifica e il token nella richiesta POST HTTP 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 protocol buffers per l'Home Graph API.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per uno dei linguaggi supportati .
  3. Chiama il metodo ReportStateAndNotification .

Node.js

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

  1. Inizializza il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con il ReportStateAndNotificationRequest. Restituisce un Promise con il valore 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 le 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 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 followUpToken valido fornito durante la richiesta di intent EXECUTE. Il token 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 mostrare la notifica solo sul dispositivo con cui l'utente interagiva inizialmente e non 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 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
  3. Crea la richiesta JSON con agentUserId. Ecco una richiesta JSON di esempio 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 Report State e il JSON di notifica e il token nella richiesta POST HTTP 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. Ottieni la definizione del servizio Protocol Buffers per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per uno dei linguaggi supportati.
  3. Chiama il metodo ReportStateAndNotification.

Node.js

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

  1. Inizializza il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Chiama il metodo reportStateAndNotification con ReportStateAndNotificationRequest. Restituisce un Promise con il valore 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 le Credenziali predefinite dell'applicazione
  2. Chiama il metodo reportStateAndNotification con il valore ReportStateAndNotificationRequest. Restituisce un valore 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 la registrazione degli eventi come descritto in Cloud Logging per il trasferimento da cloud a cloud. Questi log sono utili per testare e mantenere la qualità delle notifiche all'interno della tua azione.

Di seguito è riportato lo schema di una voce notificationLog:

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

Il campo status include vari stati che potrebbero indicare errori nel payload della notifica. Alcune di queste potrebbero essere disponibili solo per le azioni che non sono state avviate in produzione.

Ecco alcuni esempi di stati:

Stato Descrizione
EVENT_ID_MISSING Indica che manca il campo obbligatorio eventId.
PRIORITY_MISSING Indica che manca un campo priority.
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 nel GHA. Questo stato è disponibile solo per le integrazioni 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 integrazioni che non sono state avviate in produzione.

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

Indietro
Implementare lo stato del report
Avanti
Testare un'integrazione cloud-to-cloud