Bienvenue dans le Centre des développeurs Google Home, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque : Vous continuerez à créer des actions dans la console Actions.

Notifications pour les actions de maison connectée

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les notifications autorisent votre smart home Action to use Google Assistant to communicate with users about important device-related events or changes. You can implement notifications to alert users to timely device events, for example when someone is at the door, or to report on a requested device state change, such as when a door lock bolt has been successfully engaged or has jammed.

Votre action smart home permet d'envoyer les types de notifications suivants aux utilisateurs:

  • Notifications proactives: alerte l'utilisateur en cas d'événement sur l'appareil smart home sans qu'aucune requête préalable de l'utilisateur ne soit envoyée sur son appareil, telle que la sonnerie de la sonnette.

  • Réponses de suivi: confirmation de la réussite ou de l'échec d'une requête de commande de l'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 des requêtes de commande d'appareil sont envoyées depuis des enceintes intelligentes et des écrans connectés.

Assistant fournit ces notifications aux utilisateurs sous la forme d'annonces sur des enceintes intelligentes et des écrans connectés. Les notifications proactives sont désactivées par défaut. Les utilisateurs ont la possibilité d'activer ou de désactiver toutes les notifications proactives à partir du Google Home app (GHA) .

Événements déclenchant des notifications

Lorsque des événements liés à un appareil se produisent, votre traitement de l'action envoie une requête de notification à Google. Les caractéristiques d'appareil compatibles avec votre action smart home déterminent les types d'événements de notification disponibles et les données que vous pouvez y inclure.

Les caractéristiques suivantes sont compatibles avec les notifications proactives:

Trait de caractère Événements
Détection d'objets 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".
Cycle d'exécution L'appareil termine un cycle. Par exemple: "Le cycle de lavage est terminé."
SensorState L'appareil détecte un état de capteur compatible. Exemple : "Le détecteur de fumée détecte de la fumée."
Contrôle de la température L'appareil atteint une température de consigne. Exemple: "Le four a été préchauffé à 350 degrés."
ArmDisarm Le système passe à l'état pré-alarme avec un compte à rebours lors du retour, déclenché par une porte ouverte.
Caméra en streaming Lien vers le flux en direct de la caméra lorsqu'un objet ou un mouvement est détecté par l'appareil.
Détection de mouvement "Un mouvement a été détecté le 1er juillet 2020 à 12h."

Les caractéristiques suivantes permettent le suivi des réponses:

Trait de caractère Événements
ArmDisarm L'état d'avancement et le changement d'état après l'exécution de la commande d'appareil action.devices.commands.ArmDisarm Par exemple : "Le système de sécurité a été activé."
LockUnlock L'état d'avancement et le changement d'état après l'exécution de la commande d'appareil action.devices.commands.LockUnlock Par exemple: "La porte d'entrée a été verrouillée" ou "La porte d'entrée est bloquée".
NetworkControl L'état d'avancement et le changement d'état après l'exécution de la commande d'appareil action.devices.commands.TestNetworkSpeed Par exemple: "Votre test de débit réseau est terminé. La vitesse de téléchargement sur le routeur du bureau est actuellement de 80,2 Kbit/s, et la vitesse d'importation est de 9,3 Kbit/s."
OpenClose L'état d'avancement et le changement d'état après l'exécution de la commande d'appareil action.devices.commands.OpenClose Par exemple: "La porte d'entrée est ouverte" ou "Impossible d'ouvrir la porte d'entrée".
StartStop L'état d'avancement et le changement d'état après l'exécution de la commande d'appareil action.devices.commands.StartStop Exemple: "L'aspirateur a démarré."

Tous les types d'appareils acceptent les notifications pour les caractéristiques applicables.

Créez des notifications pour votre action de maison connectée

Ajoutez des notifications à votre smart home action dans les étapes suivantes:

  1. Indiquer à Google si les notifications sont activées depuis l'application smart home de l'appareil. 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 pertinent lié à l'appareil ou à un changement d'état déclenche une notification, envoyez une requête de notification en appelant Report State reportStateAndNotification API. If the device state changed, you can send both a state and notification payload together in your Report State and Notification call.

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 le GHA. Dans l'application de votre appareil smart home, vous pouvez également ajouter une option permettant aux utilisateurs d'activer ou de désactiver explicitement les notifications de l'appareil, par exemple à partir des paramètres de votre application.

Pour indiquer à Google que les notifications sont activées pour votre appareil, effectuez 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, 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 fulfillment envoie une charge utile de notification à Google Home Graph via a Report State and Notification API call..

Activer l'API Google HomeGraph

  1. Dans le Google Cloud Console , go to the HomeGraph API page.

    Accéder à la page de l'API HomeGraph
  2. Sélectionnez le projet correspondant à l'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: Veillez à 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 de compte de service, saisissez un ID.

  5. Dans la liste Rôle, sélectionnez Comptes de service > Créateur de jetons du 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 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 déclenchant la notification. eventId doit être un ID aléatoire différent chaque fois que vous envoyez une requête de notification.

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

Suivez l'un des chemins d'accès suivants pour définir la charge utile et appeler l'API:

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 page 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 Report State et Notification JSON, et le jeton de votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de requête dans la ligne de commande à l'aide de curl, à des fins 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 de Protocol Buffers pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC afin de générer des simulations de 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. Elle renvoie un Promise avec 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 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. Elle renvoie 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);
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, des codes d'erreur pour les échecs d'événement, le cas échéant, et le followUpToken valide, fourni lors de la requête d'intent EXECUTE. followUpToken doit être utilisé dans un délai de cinq minutes pour rester valide et associer correctement la réponse à la requête d'origine.

L'extrait suivant présente 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 le followUpToken pour afficher la notification uniquement sur l'appareil avec lequel l'utilisateur a initialement interagi, et non sur tous les appareils de l'utilisateur.

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 page 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 Report State et Notification JSON, et le jeton de votre requête HTTP POST au point de terminaison Google Home Graph. Voici un exemple d'envoi de requête dans la ligne de commande à l'aide de curl, à des fins 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 de Protocol Buffers pour l'API Home Graph.
  2. Suivez la documentation pour les développeurs gRPC afin de générer des simulations de 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. Elle 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 le HomeGraphApiService à l'aide des identifiants par défaut de l'application
  2. Appelez la méthode reportStateAndNotification avec ReportStateAndNotificationRequest. Elle renvoie 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();

// 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 Journaliser les événements d'accès avec Cloud Logging. 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 divers états pouvant indiquer des erreurs dans la charge utile de notification. Certaines d'entre elles peuvent n'être 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 obligatoire eventId est manquant.
PRIORITY_MISSING Indique qu'un champ priority est manquant.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Indique que la propriété de l'appareil notificationSupportedByAgent qui a été fournie dans SYNC est fausse.
NOTIFICATION_ENABLED_BY_USER_FALSE Indique que l'utilisateur n'a pas activé les notifications sur l'appareil concerné dans le GHA. Cet état n'est disponible que pour les actions qui n'ont pas encore été lancées en production.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Indique que l'utilisateur n'a pas attribué l'appareil notifiant à une maison/structure. Cet état n'est disponible que pour les actions qui n'ont pas encore é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 caractéristiques, le cas échéant (par exemple, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).

Précédent
Implémenter l'état du rapport
Suivant
Tester et partager des actions