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 au sujet d'événements ou de modifications importants liés aux appareils. Vous pouvez implémenter des notifications pour alerter les utilisateurs d'événements ponctuels sur l'appareil (par exemple, lorsque quelqu'un est à la porte) ou pour signaler un changement d'état demandé de l'appareil (par exemple, lorsque le pêne d'une serrure de porte a été correctement enclenché ou s'est coincé).

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

• Notifications proactives : alertent l'utilisateur d'un événement sur un appareil smart home sans qu'il ait envoyé de requête préalable à ses appareils (par exemple, la sonnette retentit).

• Réponses de suivi : confirmation de la réussite ou de l'échec d'une demande de commande d'appareil, par exemple lors du verrouillage d'une porte. Utilisez ces alertes pour les commandes d'appareil qui prennent du temps. Les réponses de suivi ne sont acceptées que lorsque les requêtes de commande de l'appareil sont envoyées depuis des enceintes intelligentes et des écrans connectés.

Assistant fournit ces notifications aux utilisateurs sous forme d'annonces sur les enceintes intelligentes et les é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 l'Google Home app (GHA).

Événements qui déclenchent des notifications

Lorsque des événements se produisent sur l'appareil, votre traitement envoie une demande 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 caractéristiques suivantes sont compatibles avec les notifications proactives :

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

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 en procédant comme suit :

1. Indiquez à Google si les notifications sont activées dans l'application de votre appareil smart home. Si les utilisateurs activent ou désactivent les notifications dans votre application, envoyez une requête SYNC pour informer Google de la modification de l'appareil.
2. Lorsqu'un événement ou un changement d'état d'un appareil déclenche une notification, envoyez une requête de notification en appelant l'API Report State reportStateAndNotification. Si l'état de l'appareil a changé, vous pouvez envoyer à la fois une charge utile d'état et une charge utile 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 l'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 de l'appareil, par exemple, dans les paramètres de votre application.

Indiquez à Google que les notifications sont activées pour votre appareil en effectuant un appel Request SYNC 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 proposez 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 demandes 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 de l'API HomeGraph.

   Accéder à la page de l'API HomeGraph
2. Sélectionnez le projet qui correspond à votre ID de projet smart home.
3. Cliquez sur 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 :

1. Dans la Google Cloud Console, accédez à la page Comptes de service.

   Accéder à la page "Comptes de service"

   Vous devrez peut-être sélectionner un projet avant d'accéder à la page "Comptes de service".

2. Cliquez sur addCréer un 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 le champ Description du compte de service, saisissez une description.

6. Cliquez sur Créer et continuer.

7. Dans le menu déroulant Rôle, sélectionnez Comptes de service > Créateur de jetons d'identité OpenID Connect du compte de service.

8. Cliquez sur Continuer.

9. Cliquez sur OK.

10. Sélectionnez le compte de service que vous venez de créer dans la liste des comptes de service, puis sélectionnez Gérer les clés dans le menu more_vert Actions.

11. Sélectionnez Ajouter une clé > Créer une clé.

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

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

Envoyer la notification

Effectuez l'appel de requête de notification à l'aide de l'API devices.reportStateAndNotification. Votre requête JSON doit inclure un eventId, qui est un identifiant unique généré par votre plate-forme pour l'événement qui déclenche 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 manière dont la notification doit être présentée. Votre objet notifications peut inclure différents champs en fonction du trait de l'appareil.

Suivez l'une de ces procédures pour définir la charge utile et appeler l'API :

• Envoyer une charge utile de notification proactive
• Envoyer une charge utile de réponse de suivi

Envoyer une charge utile de notification proactive

Pour appeler l'API, sélectionnez une option dans l'un de ces onglets :

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

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 pour les échecs d'événements, le cas échéant, et le followUpToken valide, fourni lors de la requête d'intent EXECUTE. Le followUpToken doit être utilisé dans les cinq minutes pour rester valide et associer correctement la réponse à la requête d'origine.

L'extrait de code 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 l'followUpToken pour n'envoyer la notification que sur l'appareil avec lequel l'utilisateur interagissait initialement, et non sur tous ses appareils.

Pour appeler l'API, sélectionnez une option dans l'un de ces onglets :

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

Journalisation

Les notifications sont compatibles avec la journalisation des événements, comme indiqué dans Cloud Logging pour le cloud-to-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 :

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

Voici quelques exemples d'états :

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 à un trait, le cas échéant (par exemple, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).