Notifiche per le Azioni per la smart home

Le notifiche consentono all'integrazione Cloud-to-cloud di utilizzare Google Assistant per comunicare con gli utenti in merito a eventi o modifiche importanti relativi al dispositivo. Puoi implementare le notifiche per avvisare gli utenti di eventi tempestivi del dispositivo, ad esempio quando qualcuno è alla porta, o per segnalare una modifica dello stato del dispositivo richiesta, ad esempio quando il chiavistello di una serratura è stato inserito correttamente o si è bloccato.

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

• Notifiche proattive: avvisano l'utente di un evento del dispositivo smart home senza richieste precedenti dell'utente ai propri dispositivi, ad esempio il suono del campanello.

• Risposte di follow-up: una conferma che una richiesta di comando del dispositivo è riuscita o non è riuscita, 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 comandi 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 dal Google Home app (GHA).

Eventi che attivano le notifiche

Quando si verificano eventi del dispositivo, l'intent di fulfillment 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:

I seguenti tratti supportano le risposte di follow-up:

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

Creare notifiche per l'integrazione da cloud a cloud

Aggiungi notifiche all'integrazione Cloud-to-cloud in queste fasi:

1. Indica a Google se le notifiche sono attivate dall'app del tuo smart home dispositivo. Se gli utenti attivano o disattivano le notifiche nella tua app, invia una richiesta SYNC per comunicare a Google la modifica del dispositivo.
2. Quando si verifica un evento o una modifica dello stato 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 sia un payload di stato che di notifica insieme nella chiamata Report State e di notifica.

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

Indicare se le notifiche sono attive nell'app

Gli utenti possono scegliere se ricevere o meno notifiche proattive attivando questa funzionalità nelle GHA. Nell'app per il tuo dispositivo 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 attive 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 sul Assistant, il tuo fulfillment invia un payload di notifica al Google Home Graph tramite una chiamata all'API di notifica.Report State

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 che corrisponde al tuo ID progetto smart home.
3. Fai clic su ABILITA.

Crea una chiave del service account

Segui queste istruzioni per generare una chiave del service account da Google Cloud Console:

1. In Google Cloud Console, vai alla pagina Service account.

   Vai alla pagina Service account.

   Potresti dover selezionare un progetto prima di accedere alla pagina Service Account.

2. Fai clic su addCrea service account.

3. Nel campo Nome account di servizio, inserisci un nome.

4. Nel campo ID account di servizio, inserisci un ID.

5. Nel campo Descrizione service account, inserisci una descrizione.

6. Fai clic su Crea e continua.

7. Dal menu a discesa Ruolo, seleziona Account di servizio > Service Account OpenID Connect Identity Token Creator.

8. Fai clic su Continua.

9. Fai clic su Fine.

10. Seleziona il service account appena creato dall'elenco dei service account e seleziona Gestisci chiavi dal menu Azioni more_vert.

11. Seleziona Aggiungi chiave > Crea nuova chiave.

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

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

Inviare 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 trasmetti nella chiamata API, includi un valore priority che definisce la modalità di presentazione della 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:

• Inviare un payload di notifica proattiva
• Inviare un payload di risposta di follow-up

Inviare un payload di notifica proattiva

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

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
              }
            }
          }
        }
      }
    }
  }
});
    

// 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);
    

Inviare 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 degli eventi, 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 per 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 stava interagendo originariamente e non per trasmetterla a tutti i dispositivi dell'utente.

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

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,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 Cloud-to-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:

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

Ecco alcuni esempi di stati:

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