Notifications d'actions pour la maison connectée

Les notifications permettent à votre intégration Cloud-to-cloud d'utiliser Google Assistant pour communiquer avec les utilisateurs sur des événements ou des modifications importants liés à l'appareil. Vous pouvez implémenter des notifications pour alerter les utilisateurs des événements de l'appareil en temps opportun, par exemple lorsqu'une personne se trouve à la porte, ou pour signaler un changement d'état de l'appareil demandé, par exemple lorsqu'un pêne de serrure de porte a été engagé ou s'est bloqué.

Votre intégration Cloud-to-cloud peut envoyer les types de notifications suivants aux utilisateurs:

  • Notifications proactives: avertissent l'utilisateur d'un événement d'appareil smart home sans aucune demande préalable de l'utilisateur à ses appareils, comme la sonnerie de la sonnette.

  • Réponses de suivi: confirmation qu'une requête de commande d'appareil a réussi ou échoué, par exemple lors du verrouillage d'une porte. Utilisez ces alertes pour les commandes de l'appareil qui prennent du temps à être exécutées. Les réponses de suivi ne sont acceptées que lorsque des requêtes de commande d'appareil sont envoyées depuis des enceintes et des écrans connectés.

Assistant envoie ces notifications aux utilisateurs sous forme d'annonces sur les enceintes et écrans connectés. Les notifications proactives sont désactivées par défaut. Les utilisateurs peuvent activer ou désactiver toutes les notifications proactives depuis Google Home app (GHA).

Événements qui déclenchent des notifications

Lorsque des événements d'appareil se produisent, votre traitement envoie une requête de notification à Google. Les caractéristiques de l'appareil compatibles avec votre intégration Cloud-to-cloud déterminent les types d'événements de notification disponibles et les données que vous pouvez inclure dans ces notifications.

Les traits suivants sont compatibles avec les notifications proactives:

Trait Événements
ObjectDetection Objets détectés par l'appareil, par exemple lorsqu'un visage reconnu est détecté à la porte. Par exemple: "Alice et Bob sont à la porte d'entrée."
RunCycle L'appareil termine un cycle. Par exemple: "Le cycle de la machine à laver est terminé."
SensorState L'appareil détecte un état de capteur compatible. Par exemple : "Le détecteur de fumée détecte de la fumée."

Les caractéristiques suivantes sont compatibles avec les réponses de suivi:

Trait Événements
LockUnlock L'état de l'exécution et l'état changent après l'exécution de la commande de l'appareil action.devices.commands.LockUnlock. Par exemple: "La porte d'entrée est verrouillée" ou "La porte d'entrée est bloquée."
NetworkControl L'état de l'exécution et l'état changent après l'exécution de la commande de l'appareil action.devices.commands.TestNetworkSpeed. Exemple: "Le test de débit de votre réseau est terminé. Le débit descendant sur le routeur du bureau est actuellement de 80,2 kbit/s, et le débit ascendant de 9,3 kbit/s."
OpenClose L'état de l'exécution et l'état changent après l'exécution de la commande de l'appareil action.devices.commands.OpenClose. Par exemple: "La porte d'entrée s'est ouverte" ou "Impossible d'ouvrir la porte d'entrée".

Tous les types d'appareils sont compatibles avec les notifications pour les caractéristiques applicables.

Créer des notifications pour votre intégration cloud à cloud

Ajoutez des notifications à votre intégration Cloud-to-cloud aux étapes suivantes:

  1. Indiquez à Google si les notifications sont activées à partir de votre application d'appareil smart home. Si les utilisateurs activent ou désactivent les notifications dans votre application, envoyez une requête SYNC pour informer Google du changement d'appareil.
  2. Lorsqu'un événement ou un changement d'état de l'appareil déclenche une notification, envoyez une requête de notification en appelant l'API reportStateAndNotification Report State. Si l'état de l'appareil a changé, vous pouvez envoyer à la fois une charge utile d'état et de notification dans votre appel Report State et Notification.

Les sections suivantes décrivent ces étapes plus en détail.

Indiquer si les notifications sont activées dans votre application

Les utilisateurs peuvent choisir de recevoir des notifications proactives en activant cette fonctionnalité dans GHA. Dans l'application de votre appareil smart home, vous pouvez également ajouter la possibilité pour les utilisateurs d'activer ou de désactiver explicitement les notifications depuis l'appareil, par exemple depuis les paramètres de votre application.

Indiquez à Google que les notifications sont activées pour votre appareil en effectuant un appel Request SYNC (Demander la synchronisation) pour mettre à jour les données de l'appareil. Vous devez envoyer une requête SYNC comme celle-ci chaque fois que les utilisateurs modifient ce paramètre dans votre application.

Dans votre réponse SYNC, envoyez l'une des mises à jour suivantes:

  • Si l'utilisateur a explicitement activé les notifications dans l'application de votre appareil ou si vous ne fournissez pas d'option d'activation/de désactivation, définissez la propriété devices.notificationSupportedByAgent sur true.
  • Si l'utilisateur a explicitement désactivé les notifications dans l'application de votre appareil, définissez la propriété devices.notificationSupportedByAgent sur false.

L'extrait de code suivant montre comment définir votre réponse SYNC:

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

Envoyer des requêtes de notification à Google

Pour déclencher des notifications sur le Assistant, votre traitement envoie une charge utile de notification au Google Home Graph via un appel d'API Report State et Notification.

Activer l'API Google HomeGraph

  1. Dans Google Cloud Console, accédez à la page API HomeGraph.

    Accéder à la page de l'API HomeGraph
  2. Sélectionnez le projet correspondant à votre ID de projet smart home.
  3. Cliquez sur ENABLE (ACTIVER).

Créer une clé de compte de service

Suivez ces instructions pour générer une clé de compte de service à partir de Google Cloud Console:

Remarque: Assurez-vous d'utiliser le bon projet GCP lorsque vous effectuez ces étapes. Il s'agit du projet correspondant à votre ID de projet smart home.

  1. Dans Google Cloud Console, accédez à la page Créer une clé de compte de service.

    Accéder à la page Créer une clé de compte de service
  2. Dans la liste Compte de service, sélectionnez Nouveau compte de service.
  3. Dans le champ Nom du compte de service, saisissez un nom.
  4. Dans le champ ID du compte de service, saisissez un ID.

  5. Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons de compte de service.

  6. Pour Type de clé, sélectionnez l'option JSON.

  7. Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.

Envoyer la notification

Effectuez l'appel de la requête de notification à l'aide de l'API devices.reportStateAndNotification. Votre requête JSON doit inclure un eventId, qui est un ID unique généré par votre plate-forme pour l'événement déclenchant la notification. eventId doit être un ID aléatoire différent à chaque fois que vous envoyez une demande de notification.

Dans l'objet notifications que vous transmettez dans votre appel d'API, incluez une valeur priority qui définit la présentation de la notification. Votre objet notifications peut inclure différents champs en fonction du trait de l'appareil.

Pour définir la charge utile et appeler l'API, suivez l'un des chemins suivants:

Envoyer une charge utile de notification proactive

Pour appeler l'API, sélectionnez une option dans l'un des onglets suivants:

HTTP

L'API Home Graph fournit un point de terminaison HTTP.

  1. Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la section S'authentifier à l'aide d'un compte de service.
  2. Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/homegraph à l'aide de oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Créez la requête JSON avec agentUserId. Voici un exemple de requête JSON pour Report State et 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. Combinez les fichiers JSON Report State et Notification, ainsi que le jeton dans votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de la requête dans la ligne de commande à l'aide de curl, à titre de 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 fournit un point de terminaison gRPC.

  1. Obtenez la définition de service Protocol Buffers pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC pour générer des bouchons client pour l'un des langages compatibles .
  3. Appelez la méthode ReportStateAndNotification .

Node.js

Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.

  1. Initialisez le service google.homegraph à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Il renvoie un Promise avec la Réponse de l'état et de la notification du rapport.
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 bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.

  1. Initialisez HomeGraphApiService à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Il renvoie un objet 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);
Envoyer une charge utile de réponse de suivi

La charge utile d'une réponse de suivi contient l'état de la requête, les codes d'erreur en cas d'échec de l'événement, le cas échéant, et l'followUpToken valide, fournie lors de la requête d'intent EXECUTE. L'followUpToken doit être utilisé dans les cinq minutes pour rester valide et associer correctement la réponse à la requête d'origine.

L'extrait suivant montre un exemple de charge utile de requête EXECUTE avec un champ 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 utilise followUpToken pour diffuser la notification uniquement sur l'appareil avec lequel l'utilisateur interagit à l'origine, et non sur tous ses appareils.

Pour appeler l'API, sélectionnez une option dans l'un des onglets suivants:

HTTP

L'API Home Graph fournit un point de terminaison HTTP.

  1. Utilisez le fichier JSON du compte de service téléchargé pour créer un jeton Web JSON (JWT). Pour en savoir plus, consultez la section S'authentifier à l'aide d'un compte de service.
  2. Obtenez un jeton d'accès OAuth 2.0 avec le champ d'application https://www.googleapis.com/auth/homegraph à l'aide de oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Créez la requête JSON avec agentUserId. Voici un exemple de requête JSON pour Report State et 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. Combinez les fichiers JSON Report State et Notification, ainsi que le jeton dans votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de la requête dans la ligne de commande à l'aide de curl, à titre de 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 fournit un point de terminaison gRPC.

  1. Obtenez la définition de service Protocol Buffers pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC pour générer des bouchons client dans l'un des langages compatibles.
  3. Appelez la méthode ReportStateAndNotification.

Node.js

Le client Node.js des API Google fournit des liaisons pour l'API Home Graph.

  1. Initialisez le service google.homegraph à l'aide des identifiants par défaut de l'application.
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Il renvoie un Promise avec 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 bibliothèque cliente de l'API HomeGraph pour Java fournit des liaisons pour l'API Home Graph.

  1. Initialiser HomeGraphApiService à l'aide des identifiants par défaut de l'application
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Il renvoie un objet 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);

Journalisation

Les notifications sont compatibles avec la journalisation des événements, comme indiqué dans la section Journalisation dans le cloud pour le cloud à cloud. Ces journaux sont utiles pour tester et maintenir la qualité des notifications dans votre action.

Voici le schéma d'une entrée notificationLog:

Propriété Description
requestId ID de la demande de notification.
structName Nom de la structure de notification, par exemple "ObjectDetection".
status Indique l'état de la notification.

Le champ status inclut différents états qui peuvent indiquer des erreurs dans la charge utile de la notification. Il est possible que certaines d'entre elles ne soient disponibles que pour les actions qui n'ont pas été lancées en production.

Voici quelques exemples d'états:

État Description
EVENT_ID_MISSING Indique que le champ eventId obligatoire est manquant.
PRIORITY_MISSING Indique qu'un champ priority est manquant.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indique que la propriété notificationSupportedByAgent de l'appareil notifiant fournie dans SYNC est définie sur "false".
NOTIFICATION_ENABLED_BY_USER_FALSE Indique que l'utilisateur n'a pas activé les notifications sur l'appareil qui envoie les notifications dans GHA. Cet état n'est disponible que pour les intégrations qui n'ont pas été lancées en production.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indique que l'utilisateur n'a pas attribué l'appareil de notification à une maison/structure. Cet état n'est disponible que pour les intégrations qui n'ont pas été lancées en production.

En plus de ces états généraux qui peuvent s'appliquer à toutes les notifications, le champ status peut également inclure des états spécifiques aux traits, le cas échéant (par exemple, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).

Précédent
Implémenter l'état du rapport
Suivant
Tester une intégration cloud à cloud