Notifications d'actions pour la maison connectée

Les notifications permettent à votre action smart home d'utiliser Google Assistant pour communiquer avec les utilisateurs sur les sujets importants les événements ou les modifications liés aux appareils. Vous pouvez implémenter des notifications les utilisateurs à des événements en temps opportun sur l'appareil, par exemple lorsqu'il y a quelqu'un à la porte, ou signaler un changement demandé de l'état d'un appareil, par exemple lorsqu'un verrou de serrure de porte a avec succès ou brouillage.

Votre action smart home peut envoyer les types suivants de notifications aux utilisateurs:

• Notifications proactives: alerte l'utilisateur d'un smart home. l'événement d'appareil sans qu'aucune requête utilisateur précédente ne soit adressée à ses appareils, comme le de votre sonnette.

• Réponses de suivi: une 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 des commandes d'appareil qui prennent du temps à s'exécuter. Les réponses de suivi ne sont que compatible lorsque des demandes de commande d'appareil sont envoyées depuis des enceintes intelligentes s'affiche.

Assistant fournit ces notifications aux utilisateurs en tant que sur les enceintes intelligentes et les écrans connectés. Notifications proactives sont désactivés 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 surviennent sur l'appareil, le traitement des actions envoie une demande de notification à Google. Caractéristiques d'appareil que votre action smart home détermine les types d'événements de notification disponibles et que vous pouvez inclure dans ces notifications.

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

Les caractéristiques suivantes soutiennent 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 action de maison connectée

Ajoutez des notifications à votre action smart home lors de ces étapes:

1. Indiquer à Google si les notifications sont activées depuis votre Application de l'appareil smart home. Si les utilisateurs activent ou désactivent les notifications dans votre application, envoyez une demande SYNC pour informer Google du changement d'appareil.
2. Lorsqu'un événement ou un changement d'état pertinent se produit et qu'il déclenche une alerte notification, envoyez une demande de notification en appelant la API reportStateAndNotification Report State. Si le l'état d'un appareil a été modifié, vous pouvez envoyer à la fois un état et une charge utile de notification dans votre Report State et l'appel de 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 ou non des notifications proactives en activer cette fonctionnalité dans GHA. Dans l'application de votre smart home, vous pouvez aussi ajouter la fonctionnalité aux utilisateurs d'activer ou de désactiver explicitement les notifications depuis l'appareil, par exemple de les paramètres de votre application.

Indiquez à Google que les notifications sont activées pour votre appareil en effectuant un appel Request SYNC (Demander une synchronisation) pour mettre à jour les données de l'appareil. Vous devez envoyer une requête SYNC comme celle-ci à chaque fois les utilisateurs de modifier 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 n'offrent pas d'option d'activation, définissez Propriété devices.notificationSupportedByAgent sur true.
• Si l'utilisateur a explicitement désactivé les notifications dans l'application de votre appareil, définissez le paramètre 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 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 qui correspond à l'ID de votre 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:

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 > <ph type="x-smartling-placeholder"></ph> Créateur de jetons du compte de service

6. Dans le champ Type de clé, sélectionnez l'option JSON.

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

Envoyer la notification

Effectuez l'appel de demande de notification à l'aide de la méthode 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. Le eventId doit 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 L'objet notifications peut inclure des champs différents selon l'appareil trait de caractère.

Suivez l'un des chemins suivants 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 des onglets suivants:

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 erreurs les codes pour les échecs d'événements, le cas échéant, et le followUpToken valide, fournies lors de la requête d'intent EXECUTE. Vous devez utiliser followUpToken dans les cinq minutes pour rester valide et associer correctement la réponse. avec la requête initiale.

L'extrait de code suivant montre un exemple de charge utile de requête EXECUTE avec une 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 afficher la notification uniquement sur l'appareil avec lequel l'utilisateur intervenait initialement, et non sur toutes les plates-formes appareils de l'utilisateur.

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

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 décrit dans Accéder aux journaux des événements avec Cloud Logging. Ces journaux sont utiles pour tester et maintenir la qualité des notifications au sein votre action.

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

Le champ status inclut différents états pouvant indiquer des erreurs dans le de notification. Il est possible que certaines ne soient disponibles que pour les actions ayant n'ont pas été lancées en production.

Voici quelques exemples d'états:

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