FAQs zu Smart Homes

Allgemein

F:Wo und in welcher Sprache sollten wir unsere Cloud-to-Cloud-Infrastruktur für die Auftragsabwicklung implementieren?

A:Solange sie modernes SSL (TLS) und OAuth 2.0 unterstützt, können Sie Ihre Infrastruktur auf jeder beliebigen Plattform und in jeder beliebigen Sprache implementieren. Wir empfehlen, die Bereitstellung so nah wie möglich an der übrigen Infrastruktur vorzunehmen, um die Zuverlässigkeit zu verbessern und die Latenz für die Ausführung auf den tatsächlichen Nutzergeräten zu verringern.

F:Müssen Geräte-IDs eindeutig sein?

A:Ja, die IDs sollten eindeutig sein. Wenn Sie keine eindeutigen IDs für Ihren Dienst haben, müssen sie zumindest auf Nutzerebene eindeutig sein. Stellen Sie sich einen Nutzer mit mehreren Häusern vor, wobei beide Häuser in denselben Nutzer eingebunden sind. Wenn Sie in einem Haus das Licht einschalten möchten, sollte nicht das Licht mit derselben ID in einem anderen Haus eingeschaltet werden.

F:Müssen Gerätenamen eindeutig sein?

A:Namen müssen nicht eindeutig sein. Im Laufe der Zeit empfehlen wir Nutzern jedoch möglicherweise, schlechte Namen nach der Einrichtung zu verbessern, um die Nutzererfahrung zu optimieren.

Hier eine kurze Anleitung zur Namensgebung:

  • Namen sollten Dinge sein, die Nutzer tatsächlich sagen können.
  • Wir erkennen Teilmengen von Strings. Wenn Sie also „acme color light“ haben, antworten wir auch auf „acme light“.
  • Wir empfehlen sowohl einen beschreibenden Namen für das Produkt als auch einen oder mehrere nutzerdefinierte Namen.
  • Nutzer müssen Lampen keine Raumnamen geben, da wir Räume dafür haben. Sie sollten eindeutige Namen pro Raum haben, können aber immer Plurale verwenden, um alles zu steuern (z. B. sind die beiden Lampen in den Wandleuchten im Büro „Nordlicht“ und „Ostlicht“, können aber einfach als „Lichter“ bezeichnet werden).

F:Wie oft wird der Gerätestatus aktualisiert?

A:Der kurzlebige Status wird entweder bei QUERY oder EXECUTE abgerufen, die von Nutzern initiierte Aktionen sind. Wenn der Nutzer fragt, ob das Licht an ist, oder eine Lampe heller machen möchte, müssen wir eine Abfrage durchführen, um den aktuellen Status zu ermitteln.

F:Ist es möglich, Home Graph direkt mit dem aktuellen Status eines Geräts zu aktualisieren?

A: Ja, verwenden Sie den Report State API-Aufruf.

Kontoverknüpfung und OAuth

A:Ja, die Kontoverknüpfung ist erforderlich, um die Geräte eines Nutzers mit den Cloud-Diensten des Anbieters zu verbinden.

F:Bei OAuth lassen wir Zugriffstokens alle 15,213 Stunden ablaufen.Ist das in Ordnung?

A:Ja, aber testen Sie mit einer relativ kurzen Ablaufzeit, z. B. 10 bis 20 Minuten. Unser OAuth-Client sollte Tokens nach Bedarf aktualisieren. Wenn Sie mit einer kurzen Ablaufzeit testen, können Sie prüfen, ob das funktioniert.

Intents

F:Wann erfolgt die Synchronisierung?

A: Die Synchronisierung erfolgt sofort nach Abschluss von OAuth und nachdem ein „Request Sync“-Aufruf erfolgt ist.

F:Warum funktioniert SYNC nicht?

A:Es gibt eine Reihe häufiger Gründe, warum dies fehlschlagen kann.

  • Sie senden die falschen Gerätetypen.

    • Wir erwarten beispielsweise action.devices.types.LIGHT, aber Sie senden action.devices.types.Light.

  • Sie senden nicht unterstützte Gerätetypen.

    • Sie senden beispielsweise action.devices.types.FLASHLIGHT. Das wird von uns nicht unterstützt.

  • Sie senden ungültige/nicht unterstützte Felder.

    • Sie haben beispielsweise ein Feld, das nicht in unserer Spezifikation enthalten ist.

  • Es gibt ein anderes Formatierungsproblem mit Ihrer SYNC-Antwort.

    • Prüfen Sie Ihre Klammern.

  • Es gibt ein Problem mit der Kontoverknüpfung.

    • Prüfen Sie, ob Sie im Auth-Header der SYNC-Anfrage ein gültiges Zugriffstoken erhalten.

  • Sie brauchen zu lange, um auf die SYNC-Anfrage zu antworten.

    • Prüfen Sie, ob Sie innerhalb von 5 Sekunden auf die SYNC-Anfrage antworten.

F:Ist eine Antwort mit dem Status „pending“ in Ordnung?

A:Wir bevorzugen eine Antwort mit dem Status „success“ oder „fail“ anstelle von „pending“, wenn Ihre Geräte in Echtzeit verfügbar sind. Bitte setzen Sie sich mit uns in Verbindung, wenn Sie eine Antwort mit dem Status „pending“ benötigen. Wir wissen, dass für einige Geräte mit geringem Stromverbrauch, die nicht in Echtzeit funktionieren, möglicherweise eine Antwort mit dem Status „pending“ und ein asynchrones Ausführungsmodell erforderlich sind.

Testen und Einreichen

F:Können wir eine Cloud-Entwicklungsumgebung einrichten?

A:Ja, Sie können eine noch nicht gestartete Cloud-Umgebung und -Konfiguration testen.

F:Meine Action ist in der Google Home App im Bereich „Smart-Home-Steuerung“ nicht sichtbar. Was ist los?

A:Prüfen Sie, ob Sie Entwickler für dieses Projekt sind.

Status melden

F:Gibt es Voraussetzungen für die Implementierung von „Status melden“?

A:Das Projekt muss die Smart Home API verwenden, OAuth2 unterstützen und Merkmale haben, für die Status gemeldet werden müssen.

F:Wie oft müssen wir den Status eines Geräts melden?

A:Google interessiert sich für den Übergangs- und den Endstatus. Wenn sich der Status jedoch innerhalb kurzer Zeit häufig ändert (z. B. wenn ein Nutzer den Kühlschrank dreimal pro Minute öffnet und schließt oder einen Dimmer verschiebt), müssen wir nur den Endstatus melden.

F:Muss der vollständige Gerätestatus gesendet werden, wenn „Status melden“-Aufrufe erfolgen?

A: Teilweise Statusaktualisierungen werden nicht unterstützt. Daher sollten Report State Aufrufe immer alle Daten für ein bestimmtes Merkmal enthalten, das aktualisiert wurde. Wenn zwei Merkmale zu einer Inkonsistenz führen würden, sollten sie zusammen gemeldet werden.

F:Kann Google meinen Gerätestatus abfragen (d. h. das Gerät abrufen)?

A:Das ist ein Fallback-Mechanismus, den wir nicht empfehlen. Wenn wir für diese Nutzer häufig auf das Abrufen eines Geräts zurückgreifen müssen, können wir nicht garantieren, wie hoch die zusätzliche Last sein wird. Der Bedarf ergibt sich aus den neuen visuellen Oberflächen. Neben dem Problem der unbekannten Last führt dies zu einer schlechteren Nutzererfahrung. Wir sind der Meinung, dass Report State für die Plattform von entscheidender Bedeutung ist.

F:Welche Merkmale unterstützen derzeit „Status melden“?

A:Alle öffentlichen Merkmale mit zugehörigen Status werden unterstützt. Jede Änderung des Onlinestatus des Geräts sollte ebenfalls gemeldet werden.

Szenen haben keine Status. Sie können jedoch zu einer Änderung des Status von Geräten führen. Wenn sich der Status eines Geräts in Google Home Graph ändert, muss dies gemeldet werden.

F:Ist für „Status melden“ ein Zeitstempel erforderlich?

A:Wir benötigen keinen Zeitstempel. Der zuletzt gesendete Status überschreibt frühere Aufrufe.

F:Muss ich den Status separat melden, wenn ich ihn bereits in „Abfrage“ und/oder „Ausführen“ sende?

A: Home Graph speichert nur den Status, der über Report State gesendet wird. Der Status, der als Antwort auf die Intents „Ausführen“ und „Abfrage“ zurückgegeben wird, wird nur für Sprachantworten an den Nutzer verwendet und nicht gespeichert. Daher sollte Report State aufgerufen werden auch wenn der neue Status des Geräts bereits als Antwort auf einen „Ausführen“- oder „Abfrage“-Intent zurückgegeben wurde.

F:Welche Folgen hat es, wenn „Status melden“ nicht vollständig innerhalb der angegebenen Frist implementiert wird?

A: Dies führt zu einer schlechteren Nutzererfahrung, z. B. in der Google Home app (GHA) und auf visuellen Oberflächen. Das bedeutet, dass viele „Abfrage“-Intents gesendet werden, um den Status abzurufen. Wir können nicht garantieren, wie hoch die zusätzliche Last für die Partner-Cloud sein wird.

F:Wie kann ich unsere „Status melden“-Implementierung testen?

A: Verwenden Sie den Home Graph Viewer. Das ist ein Self-Service-Testtool, mit dem Sie Ihre aktuellen Gerätestatus sehen können, die in Home Graph gespeichert sind.

F:Können wir für „Status melden“ eine zufällige Anfrage-ID verwenden?

A: Wir empfehlen Partnern, dieselbe Anfrage-ID zu verwenden, die sie von der „Ausführen“-Anfrage erhalten haben, wenn Report State durch die „Ausführen“-Anfrage ausgelöst wird. Andernfalls können Sie einfach eine zufällige Anfrage-ID verwenden.

F:Wenn ein Nutzer mehrere Geräte hat und sich der Status eines Geräts ändert, müssen wir dann den neuesten Status aller Geräte melden?

A:Nein. Sie müssen nur den Status des jeweiligen Geräts melden.

Best Practices

F:Welche Latenz ist akzeptabel?

A:Weniger als 1.000 ms sind ideal, zwischen 2 und 5 Sekunden sind in Ordnung. Wenn Ihre Latenz bei etwa 5 Sekunden liegt, setzen Sie sich mit uns in Verbindung.

F:Wie kann ich dafür sorgen, dass mein sprachaktivierter Lautsprecher richtig reagiert, wenn er offline ist?

A:Geben Sie für Offline-Geräte den Status „offline“ zurück. Für diesen Fehler geben wir „Derzeit nicht verfügbar“ als TTS zurück. Weitere Informationen finden Sie unter Fehler und Ausnahmen.