Questions fréquentes sur la maison connectée

Général

Q : Où et dans quelle langue devons-nous implémenter notre infrastructure d'exécution cloud à cloud ?

R : 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 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 ?

R : Les ID doivent être uniques. Si vous n'avez pas d'ID uniques pour votre service, ils doivent au moins être uniques au niveau de chaque utilisateur. Imaginez un utilisateur avec plusieurs maisons, où les deux maisons 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'appareils doivent-ils être uniques ?

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

Voici un guide rapide pour nommer vos fichiers :

  • Les noms doivent être prononçables.
  • Nous reconnaissons les sous-ensembles de chaînes. Par exemple, si vous avez "acme color light", nous répondrons également à "acme light".
  • Nous vous encourageons à fournir un nom descriptif pour le produit, ainsi qu'un ou plusieurs noms définis par l'utilisateur.
  • Les utilisateurs n'ont pas besoin de donner un nom de pièce aux lumières, car nous avons déjà des pièces pour cela. Ils doivent leur donner un nom unique par pièce, mais 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 en disant "lumières").

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

R : 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 augmenter la luminosité d'une lumière, nous devons effectuer une requête pour connaître l'état actuel.

Q : Est-il possible de mettre à jour directement le graphique de la maison avec l'état actuel d'un appareil ?

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

Association de comptes et OAuth

R : Oui, l'association de compte 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 acceptable ?

R : Oui, mais veuillez effectuer le test avec un délai d'expiration assez court, par exemple 10 à 20 minutes. Notre client OAuth doit actualiser les jetons selon les besoins. Tester avec un délai d'expiration court permettra de vérifier que cela fonctionne.

Intents

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

R : La synchronisation a lieu immédiatement après la fin de l'authentification OAuth et après l'appel d'une synchronisation des requêtes.

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

R : Plusieurs raisons courantes peuvent expliquer ce problème.

  • 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 cette opération.

  • Vous envoyez des champs non valides/non acceptés.

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

  • Un autre problème de formatage a été détecté dans votre réponse SYNC.

    • Consultez vos tableaux !

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

    • 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 demande SYNC.

    • Veuillez vérifier que vous répondez à la requête SYNC dans un délai de cinq secondes.

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

R : Nous préférons une réponse de type "réussite/échec" plutôt que "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 savons que certains appareils à faible consommation et non 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 ?

R : 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 ?

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

État du rapport

Q : Existe-t-il des prérequis pour implémenter Report State ?

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

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

R : Google s'intéresse à la transition et à l'état final. Toutefois, s'il y a de nombreux changements d'état 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 ?

R : Les mises à jour partielles de l'état ne sont pas acceptées. Les appels Report State doivent donc toujours inclure toutes les données d'un trait spécifique qui a été mis à 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 son état (c'est-à-dire l'interroger) ?

R : Il s'agit d'un mécanisme de secours que nous ne recommandons pas. Si nous devons revenir à l'interrogation fréquente d'un appareil pour ces utilisateurs, nous ne pouvons pas garantir la charge supplémentaire. Ce besoin découle 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 actuellement compatibles avec l'état du rapport ?

R : Toutes les caractéristiques publiques associées à des états sont acceptées. Tout changement d'état de connexion de l'appareil doit également être signalé.

Notez que les scènes n'ont pas d'états. Toutefois, ils peuvent entraîner un changement d'état des appareils. Si l'état d'un appareil dans Google Home Graph change, vous devez le signaler.

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

R : Nous n'exigeons pas d'horodatage. Le dernier état envoyé remplacera 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 ?

R : 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 à une intention EXECUTE ou QUERY.

Q : Quelles sont les conséquences si je n'implémente pas complètement Report State d'ici la date limite indiquée ?

R : Cela dégradera l'expérience utilisateur, par exemple dans les surfaces Google Home app (GHA) et visuelles. Cela signifie que de nombreuses intentions QUERY seront envoyées pour interroger l'état. Nous ne pouvons pas garantir que cela correspondra à une charge supplémentaire sur le cloud du partenaire.

Q : Comment puis-je tester l'implémentation de l'état des rapports ?

R : Utilisez l'outil de visualisation HomeGraph, un outil de test en libre-service qui vous montre l'état actuel de vos appareils stockés dans Home Graph.

Q : Pouvons-nous utiliser un requestId aléatoire pour Report State ?

R : Nous recommandons aux partenaires d'utiliser le même requestId que celui 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 ?

R : Non. Vous ne devez signaler que l'état de cet appareil spécifique.

Bonnes pratiques

Q : Quelle latence est acceptable ?

R : Idéalement, moins de 200 ms. Entre 2 et 5 s, c'est acceptable. Si votre latence est d'environ cinq secondes, contactez-nous.

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

R : renvoie l'état hors connexion pour les appareils hors connexion. Nous renvoyons "non disponible pour le moment" en TTS pour cette erreur. Pour en savoir plus, consultez Erreurs et exceptions.