Benachrichtigungen für Smart-Home-Aktionen

Durch Benachrichtigungen kann deine smart home-Aktion Folgendes nutzen: Google Assistant, um mit Nutzern über wichtige gerätebezogene Ereignisse oder Änderungen. Sie können Benachrichtigungen einrichten, rechtzeitig über Geräteereignisse informieren, z. B. wenn jemand an der Tür ist, Bericht über eine angeforderte Änderung des Gerätestatus, z. B. wenn ein Türschloss erfolgreich beteiligt oder klemmt.

Deine smart home-Aktion kann folgende Arten von Benachrichtigungen an Nutzer:

• Proaktive Benachrichtigungen: Benachrichtigt den Nutzer über smart home Geräteereignis ohne vorherige Nutzeranfrage an ihre Geräte, z. B. es klingelt.

• Folgeantworten: Eine Bestätigung, dass eine Gerätebefehlsanfrage erfolgreich war oder fehlgeschlagen ist, z. B. beim Verriegeln einer Tür. Verwenden Sie diese Benachrichtigungen für Gerätebefehle, deren Ausführung einige Zeit in Anspruch nimmt. Follow-up-Antworten sind nur wird unterstützt, wenn Gerätebefehlsanfragen von intelligenten Lautsprechern und Smart-Home-Geräten gesendet werden. angezeigt wird.

Assistant stellt Nutzern diese Benachrichtigungen zur Verfügung als Ankündigungen auf intelligenten Lautsprechern und Smart Displays. Proaktive Benachrichtigungen sind standardmäßig deaktiviert. Nutzer können alle proaktiven Benachrichtigungen über die Google Home app (GHA)

Ereignisse, die Benachrichtigungen auslösen

Bei Geräteereignissen wird über die Auftragsausführung für Aktionen eine Benachrichtigungsanfrage gesendet an Google senden. Die Geräteeigenschaften, die deine smart home-Aktion bestimmt, welche Arten von Benachrichtigungsereignissen verfügbar sind. Daten, die Sie in diese Benachrichtigungen aufnehmen können.

Bei den folgenden Merkmalen werden proaktive Benachrichtigungen unterstützt:

Die folgenden Eigenschaften unterstützen Folgeantworten:

Alle Gerätetypen unterstützen Benachrichtigungen für die jeweiligen Traits.

Benachrichtigungen für deine Smart-Home-Aktion erstellen

Füge deiner smart home-Aktion in den folgenden Phasen Benachrichtigungen hinzu:

1. Teile Google mit, ob Benachrichtigungen für deine Geräte-App „smart home“. Ob Nutzer Benachrichtigungen aktivieren oder deaktivieren in deiner App eine SYNC-Anfrage senden, um Google über die Geräteänderung zu informieren.
2. Wenn ein relevantes Geräteereignis oder eine relevante Statusänderung auftritt, die eine senden Sie eine Benachrichtigungsanfrage, indem Sie die Report State reportStateAndNotification API. Wenn die Gerätestatus geändert hat, kannst du sowohl einen Status als auch eine Benachrichtigungsnutzlast senden in Ihrem Report State- und Benachrichtigungsaufruf zusammen.

In den folgenden Abschnitten werden diese Schritte ausführlicher beschrieben.

Angeben, ob Benachrichtigungen in deiner App aktiviert sind

Nutzer können festlegen, ob sie proaktive Benachrichtigungen erhalten möchten, indem sie Aktivieren dieser Funktion in GHA. In der App für Ihr smart home-Gerät haben, können Sie auch optional die Möglichkeit hinzufügen, können Nutzer Benachrichtigungen auf dem Gerät explizit ein- oder ausschalten, z. B. von App-Einstellungen.

Teile Google mit, dass Benachrichtigungen für dein Gerät aktiviert sind, indem du einen Request SYNC-Aufruf Gerätedaten zu aktualisieren. Sie sollten eine SYNC-Anfrage wie diese immer Nutzer diese Einstellung in Ihrer App ändern.

Senden Sie in Ihrer SYNC-Antwort eine der folgenden Aktualisierungen:

• Wenn der Nutzer die Benachrichtigungen in der Geräte-App explizit aktiviert hat oder wenn Sie keine Ein/Aus-Schaltfläche bereitstellen, devices.notificationSupportedByAgent-Property zu true.
• Wenn der Nutzer Benachrichtigungen in der App Ihres Geräts explizit deaktiviert hat, legen Sie devices.notificationSupportedByAgent-Property zu false.

Das folgende Snippet zeigt ein Beispiel, wie Sie Ihre SYNC-Antwort festlegen:

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

Benachrichtigungsanfragen an Google senden

Um Benachrichtigungen auf Assistant auszulösen, müssen deine Die Auftragsausführung sendet eine Benachrichtigungsnutzlast an Google Home Graph über einen Report State- und einen Notification API-Aufruf.

Google HomeGraph API aktivieren

1. Rufen Sie in der Google Cloud Console die Seite HomeGraph API auf.

   Zur Seite „HomeGraph API“
2. Wählen Sie das Projekt aus, das Ihrer smart home-Projekt-ID entspricht.
3. Klicken Sie auf AKTIVIEREN.

Dienstkontoschlüssel erstellen

Folgen Sie dieser Anleitung, um einen Dienstkontoschlüssel aus Google Cloud Console zu generieren:

1. Rufen Sie in der Google Cloud Console die Seite Dienstkontoschlüssel erstellen auf.

   Zur Seite Dienstkontoschlüssel erstellen
2. Wählen Sie in der Liste Dienstkonto Neues Dienstkonto.
3. Geben Sie im Feld Dienstkontoname einen Namen ein.
4. Geben Sie im Feld Dienstkonto-ID eine ID ein.

5. Wählen Sie in der Liste Rolle die Option Dienstkonten aus. <ph type="x-smartling-placeholder"></ph> Ersteller von Dienstkonto-Token.

6. Wählen Sie als Schlüsseltyp die Option JSON aus.

7. Klicken Sie auf Erstellen. Eine JSON-Datei, die Ihren Schlüssel enthält auf Ihren Computer herunterladen.

Benachrichtigung senden

Tätigen Sie die Benachrichtigungsanfrage mithilfe der devices.reportStateAndNotification API Ihre JSON-Anfrage muss eine eventId enthalten. Dies ist eine eindeutige ID, die von Ihre Plattform für das Ereignis, das die Benachrichtigung auslöst. Der eventId sollte eine zufällige ID sein, die sich jedes Mal ändert, wenn Sie eine Benachrichtigungsanfrage senden.

Fügen Sie in das notifications-Objekt, das Sie im API-Aufruf übergeben, Folgendes ein: priority-Wert, der definiert, wie die Benachrichtigung dargestellt wird. Ihr Das Objekt notifications kann je nach Gerät unterschiedliche Felder enthalten Eigenschaft ist.

Folgen Sie einem der folgenden Pfade, um die Nutzlast festzulegen und die API aufzurufen:

• Proaktive Benachrichtigungsnutzlast senden
• Nutzlast einer Folgeantwort senden

Proaktive Benachrichtigungsnutzlast senden

Wählen Sie eine Option auf einem der folgenden Tabs aus, um die API aufzurufen:

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

Nutzlast einer Folgeantwort senden

Die Nutzlast für eine Folgeantwort enthält den Status der Anfrage, Fehler gegebenenfalls Codes für Ereignisfehler sowie die gültige followUpToken, während der EXECUTE-Intent-Anfrage angegeben wurde. followUpToken muss verwendet werden damit die Antwort gültig bleibt und die Antwort richtig durch die ursprüngliche Anfrage.

Das folgende Snippet zeigt ein Beispiel für eine EXECUTE-Anfragenutzlast mit einem 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 verwendet das followUpToken, um die Benachrichtigung nur auf dem Gerät auszugeben. mit dem der Nutzer ursprünglich interagiert hat, nicht an alle die Geräte der Nutzer.

Wählen Sie eine Option auf einem der folgenden Tabs aus, um die API aufzurufen:

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

Benachrichtigungen unterstützen die Ereignisprotokollierung, wie unter Mit Cloud Logging auf Ereignislogs zugreifen beschrieben. Diese Protokolle sind nützlich zum Testen und Aufrechterhalten der Benachrichtigungsqualität in deine Aktion.

Hier das Schema eines notificationLog-Eintrags:

Das Feld status enthält verschiedene Status, die auf Fehler in der Benachrichtigungsnutzlast. Einige davon sind möglicherweise nur für Aktionen verfügbar, nicht für die Produktion freigegeben wurde.

Beispiele für Status:

Zusätzlich zu diesen allgemeinen Status, die für alle Benachrichtigungen gelten können, kann das Feld „status“ gegebenenfalls auch charakterspezifische Statuswerte enthalten (z.B. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).