Notifiche per le Azioni per la smart home

Le notifiche consentono all'azione smart home di utilizzare Google Assistant per comunicare agli utenti di importanti eventi o modifiche correlati al dispositivo. Puoi implementare le notifiche per agli utenti di mostrare tempestivamente eventi del dispositivo, ad esempio quando c'è qualcuno alla porta o per invia un report su una richiesta di modifica dello stato del dispositivo, ad esempio quando un chiavistello della serratura è stato coinvolto correttamente o si è bloccato.

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

• Notifiche proattive: avvisa l'utente di un smart home dispositivo senza precedenti richieste dell'utente ai propri dispositivi, ad esempio del campanello che suona.

• Risposte di follow-up: una conferma che una richiesta di comando del dispositivo riusciti o non riusciti, ad esempio durante la chiusura di una porta. Utilizza questi avvisi per il cui completamento richiede tempo. Le risposte di follow-up sono Funzionalità supportata quando le richieste di comando del dispositivo vengono inviate da smart speaker e smart vengono visualizzati i video.

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

Eventi che attivano le notifiche

Quando si verificano eventi del dispositivo, l'evasione ordini dell'azione invia una richiesta di notifica a Google. Le caratteristiche del dispositivo che l'azione smart home determina quali tipi di eventi di notifica sono disponibili e dati che puoi includere nelle notifiche.

Le notifiche proattive sono supportate dai seguenti tratti:

Le seguenti caratteristiche supportano le risposte di follow-up:

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

Crea notifiche per la tua azione smart home

Aggiungi notifiche all'azione smart home in queste fasi:

1. Indica a Google se le notifiche sono attivate dal tuo smart home app del 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 evento o un cambiamento di stato pertinente del dispositivo che attiva una notifica, invia una richiesta di notifica chiamando il API reportStateAndNotification Report State. Se stato del dispositivo modificato, puoi inviare sia uno stato sia un payload di notifica nella tua Report State e nella chiamata di notifica.

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

Indica se le notifiche sono attivate nella tua app

Gli utenti possono scegliere se ricevere o meno notifiche proattive attivazione di questa funzionalità in GHA. Nell'app del tuo smart home dispositivo, puoi anche aggiungere la funzionalità agli utenti di attivare/disattivare in modo esplicito le notifiche dal dispositivo, ad esempio da le 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. Dovresti inviare una richiesta SYNC come questa ogni volta Gli utenti possono modificare 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 tuo dispositivo o se per non fornire un'opzione di attivazione/disattivazione, devices.notificationSupportedByAgent a true.
• Se l'utente ha disattivato esplicitamente le notifiche nell'app del dispositivo, imposta il devices.notificationSupportedByAgent a false.

Il seguente snippet 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, i tuoi Il completamento invia un payload di notifica a Google Home Graph tramite una chiamata all'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.

Creare una chiave dell'account di servizio

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

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

   Vai alla pagina Crea chiave dell'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. 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. Un file JSON contenente la chiave vengono scaricati sul computer.

Invia la notifica

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

Nell'oggetto notifications che passi nella chiamata API, includi un oggetto Valore priority che definisce il modo in cui deve essere presentata la notifica. Il tuo L'oggetto notifications potrebbe includere campi diversi a seconda del dispositivo tratto distintivo.

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

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

Invia un payload di notifica proattiva

Per chiamare l'API, seleziona un'opzione da una delle seguenti 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);
    

Invia un payload di risposta di follow-up

Il payload per una risposta di follow-up contiene lo stato della richiesta, l’errore per gli errori di evento, se applicabile, e il valore followUpToken valido, forniti durante la richiesta di intent di EXECUTE. È necessario utilizzare followUpToken entro cinque minuti per rimanere valido e associare correttamente la risposta. con la richiesta originale.

Il seguente snippet mostra un esempio di payload EXECUTE di richiesta con un 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 l'utente stava interagendo inizialmente e non ha trasmesso dai dispositivi degli utenti.

Per chiamare l'API, seleziona un'opzione da una delle seguenti 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 il logging degli eventi come descritto in Accedere ai log eventi con Cloud Logging. Questi log sono utili per testare e mantenere la qualità delle notifiche l'Azione.

Di seguito è riportato lo schema di una voce notificationLog:

Il campo status include diversi stati che possono indicare errori nella di notifica. Alcune di queste potrebbero essere disponibili solo nelle Azioni con non è stato avviato in produzione.

Ecco alcuni esempi di stati:

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