Questions fréquentes sur la maison connectée

Général

Q : Où et dans quelle langue devons-nous implémenter notre infrastructure de traitement cloud à cloud ?

A : Tant qu'elle est compatible avec les protocoles SSL (TLS) et OAuth 2.0 modernes, vous pouvez implémenter votre infrastructure sur la plate-forme et dans la langue de votre choix. Nous vous recommandons de déployer votre infrastructure le plus près possible du reste de votre infrastructure afin d'améliorer la fiabilité et de réduire la latence d'exécution sur les appareils des utilisateurs.

Q : Les ID d'appareil doivent-ils être uniques ?

A : Oui, les ID doivent être uniques. Si vous n'avez pas d'ID uniques dans votre service, ils doivent au moins être uniques au niveau de l'utilisateur. Imaginez un utilisateur possédant plusieurs maisons, dans lesquelles des intégrations sont associées au même utilisateur. Demander d'allumer une lumière dans une maison ne doit pas allumer une lumière avec le même ID dans une autre maison.

Q : Les noms d'appareil doivent-ils être uniques ?

A : Les noms ne doivent pas nécessairement être uniques, mais nous pouvons encourager les utilisateurs à améliorer les noms incorrects après la configuration pour une meilleure expérience utilisateur.

Voici un guide rapide pour nommer vos appareils :

  • Les noms doivent être des éléments que les utilisateurs peuvent réellement prononcer.
  • Nous reconnaissons les sous-ensembles de chaînes. Par conséquent, si vous avez "acme color light", nous répondrons également à "acme light".
  • Nous vous recommandons d'utiliser un nom descriptif pour le produit, ainsi qu'un ou plusieurs noms définis par l'utilisateur.
  • Les utilisateurs n'ont pas besoin d'attribuer de nom de pièce aux lumières, car nous avons des pièces pour cela. Les lumières doivent avoir des noms uniques par pièce, mais les utilisateurs peuvent toujours utiliser le pluriel pour tout commander (par exemple, les deux ampoules des appliques du bureau sont "lumière nord" et "lumière est", mais peuvent être commandées simplement comme "lumières").

Q : À quelle fréquence l'état de l'appareil est-il mis à jour ?

A : L'état éphémère est récupéré lors d'une requête QUERY ou EXECUTE, qui sont des actions initiées par l'utilisateur. Si l'utilisateur demande "La lumière est-elle allumée ?" ou souhaite éclairer une lumière, nous devons effectuer une requête pour déterminer l'état actuel.

Q : Est-il possible de mettre à jour Home Graph directement avec l'état actuel d'un appareil ?

A : Oui, utilisez l'appel d'API Report State.

Association de comptes et OAuth

A : Oui, l'association de comptes est requise pour connecter les appareils d'un utilisateur aux services cloud du fournisseur.

Q : Pour OAuth, nous faisons expirer les jetons d'accès toutes les 15, 213 heures.Est-ce correct ?

A : Oui, mais veuillez effectuer des tests avec un délai d'expiration assez court, par exemple de 10 à 20 minutes. Notre client OAuth doit actualiser les jetons si nécessaire, et les tests avec un délai d'expiration court prouveront que cela fonctionne.

Intents

Q : Quand la synchronisation a-t-elle lieu ?

A : La synchronisation a lieu immédiatement après la fin de l'authentification OAuth et après un appel Request Sync.

Q : Pourquoi SYNC ne fonctionne-t-il pas ?

A : Il existe plusieurs raisons courantes pour lesquelles cela peut échouer.

  • Vous envoyez les mauvais types d'appareils.

    • Par exemple, nous attendons action.devices.types.LIGHT, mais vous envoyez action.devices.types.Light.

  • Vous envoyez des types d'appareils non compatibles.

    • Par exemple, vous envoyez action.devices.types.FLASHLIGHT. Nous ne prenons pas en charge ce type d'appareil.

  • Vous envoyez des champs non valides/non compatibles.

    • Par exemple, vous avez un champ qui ne figure pas dans nos spécifications.

  • Il existe un autre problème de mise en forme avec votre réponse SYNC.

    • Vérifiez vos crochets.

  • Vous rencontrez un problème d'association de comptes.

    • Veuillez vérifier que vous recevez un jeton d'accès valide dans l'en-tête Auth de la requête SYNC.

  • Vous mettez trop de temps à répondre à la requête SYNC.

    • Veuillez vérifier que vous répondez à la requête SYNC dans les cinq secondes.

Q : Une réponse "en attente" est-elle acceptable ?

A : Nous préférons une réponse de réussite/échec plutôt qu'une réponse en attente si vos appareils sont disponibles en temps réel. Veuillez nous contacter si vous pensez avoir besoin d'une réponse "en attente". Nous reconnaissons que certains appareils à faible consommation et non en temps réel peuvent nécessiter une réponse en attente et un modèle d'exécution asynchrone.

Tests et envoi

Q : Pouvons-nous configurer un environnement cloud de développement ?

A : Oui, vous pouvez tester un environnement cloud et une configuration non lancés.

Q : Mon action n'est pas visible dans la section "Contrôle de la maison" de l'application Google Home. Que se passe-t-il ?

A : Vérifiez que vous êtes un développeur pour ce projet.

État du rapport

Q : Existe-t-il des prérequis pour implémenter l'état du rapport ?

A : Le projet doit utiliser l'API Smart Home, être compatible avec OAuth2 et comporter des caractéristiques dont l'état doit être signalé.

Q : À quelle fréquence devons-nous signaler l'état d'un appareil ?

A : Google s'intéresse à la transition et à l'état final. Toutefois, si l'état change fréquemment en peu de temps (par exemple, un utilisateur ouvre et ferme le réfrigérateur trois fois en une minute ou fait glisser un variateur), nous n'avons besoin que de l'état final.

Q : L'état complet de l'appareil doit-il être envoyé lors des appels Report State ?

A : Les mises à jour d'état partielles ne sont pas compatibles. Par conséquent, les appels Report State doivent toujours inclure toutes les données d'une caractéristique particulière qui a été mise à jour. Si deux caractéristiques créent une incohérence, elles doivent être signalées ensemble.

Q : Google peut-il interroger mon appareil pour obtenir l'état (c'est-à-dire interroger l'appareil) ?

A : Il s'agit d'un mécanisme de secours que nous ne recommandons pas. Si nous devons fréquemment interroger un appareil pour ces utilisateurs, nous ne pouvons pas garantir la charge supplémentaire. Ce besoin provient des nouvelles surfaces visuelles. En plus du problème de charge inconnue, l'expérience utilisateur sera dégradée. Nous pensons que Report State est essentiel pour la plate-forme.

Q : Quelles caractéristiques sont compatibles avec l'état du rapport pour le moment ?

A : Toutes les caractéristiques publiques associées à des états sont compatibles. Tout changement d'état en ligne de l'appareil doit également être signalé.

Notez que les scènes n'ont pas d'état. Toutefois, elles peuvent entraîner un changement d'état d'un ou plusieurs appareils. Si l'état d'un appareil dans Google Home Graph a un changement d'état, cela doit être signalé.

Q : L'état du rapport nécessite-t-il l'envoi d'un code temporel ?

A : Nous n'exigeons pas de code temporel. Le dernier état envoyé remplace les appels précédents.

Q : Dois-je signaler l'état séparément si je l'envoie déjà dans Query et/ou Execute ?

A : Home Graph ne stocke que l'état envoyé via Report State. L'état renvoyé en réponse aux intents EXECUTE et QUERY n'est utilisé que pour les réponses vocales à l'utilisateur et n'est pas stocké. Par conséquent, Report State doit être appelé même si le nouvel état de l'appareil a déjà été renvoyé en réponse à un intent EXECUTE ou QUERY.

Q : Quelles sont les conséquences si l'état du rapport n'est pas complètement implémenté dans le délai imparti ?

A : L'expérience utilisateur sera dégradée, par exemple dans Google Home app (GHA) et sur les surfaces visuelles. Cela signifie que de nombreux intents QUERY seront envoyés pour interroger l'état, et nous ne pouvons pas garantir la charge supplémentaire que cela représentera pour le cloud partenaire.

Q : Comment tester notre implémentation de l'état du rapport ?

A : Utilisez l’outil de test en libre-service Home Graph Viewer pour afficher les états actuels de vos appareils stockés dans Home Graph.

Q : Pouvons-nous utiliser un requestId aléatoire pour l'état du rapport ?

A: Nous recommandons aux partenaires d'utiliser le même requestId que celui qu'ils ont reçu de la requête EXECUTE si le Report State est déclenché par la requête EXECUTE. Sinon, vous pouvez simplement utiliser un requestId aléatoire.

Q : Si un utilisateur possède plusieurs appareils et que l'état de l'un d'eux change, devons-nous signaler le dernier état de tous les appareils ?

A : Non. Vous n'avez qu'à signaler l'état de cet appareil spécifique.

Bonnes pratiques

Q : Quel type de latence est acceptable ?

A : L'idéal est une latence inférieure à 1 000 ms, mais une latence comprise entre 2 et 5 secondes est acceptable. Si votre latence avoisine les cinq secondes, contactez-nous.

Q : Comment faire en sorte que mon enceinte à commande vocale réponde correctement lorsqu'elle est hors connexion ?

A : Renvoyez l'état hors connexion pour les appareils hors connexion. Nous renvoyons "Non disponible pour le moment" en tant que synthèse vocale pour cette erreur. Pour en savoir plus, consultez la page Erreurs et exceptions.