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 SSL (TLS) et OAuth 2.0 modernes, vous pouvez implémenter votre infrastructure sur n'importe quelle plate-forme et dans n'importe quelle 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 ?
A: Les ID doivent être uniques. Si vous ne disposez pas d'ID uniques pour l'ensemble de votre service, ils doivent être uniques au moins au niveau de l'utilisateur. Imaginons un utilisateur qui possède plusieurs maisons, dont les deux sont intégrées au même utilisateur. Demander à allumer une ampoule dans une maison ne doit pas allumer une ampoule portant le même ID dans une autre maison.
Q: Les noms des appareils doivent-ils être uniques ?
A: Les noms ne doivent pas nécessairement être uniques, mais nous pouvons encourager les utilisateurs à améliorer les mauvais noms après la configuration pour améliorer l'expérience utilisateur.
Voici un guide rapide sur la dénomination:
- Les noms doivent être des mots que les utilisateurs peuvent prononcer.
- Nous reconnaissons des sous-ensembles de chaînes. Par conséquent, si vous dites "ampoule de couleur acme", nous répondrons également à "ampoule acme".
- Nous vous recommandons d'attribuer un nom descriptif au produit, ainsi qu'un ou plusieurs noms définis par l'utilisateur.
- Les utilisateurs n'ont pas besoin de donner aux lumières des noms de pièce, car nous avons des pièces à cet effet. Ils doivent avoir des noms uniques par pièce, mais peuvent toujours utiliser des noms au pluriel pour tout commander (par exemple, les deux ampoules des appliques de bureau sont "lumière nord" et "lumière est", mais peuvent être commandées simplement sous la forme "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 de QUERY ou EXECUTE, qui sont des actions déclenché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 déterminer l'état actuel.
Q: Est-il possible de mettre à jour directement Home Graph avec l'état actuel d'un appareil ?
A: Oui, utilisez l'appel d'API Report State.
Association de comptes et OAuth
Q: Dois-je associer des comptes ?
A: Oui, l'association de comptes est nécessaire 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 tester avec un délai d'expiration assez court, par exemple 10 à 20 minutes. Notre client OAuth doit actualiser les jetons si nécessaire. Un test avec une durée d'expiration courte prouvera que cela fonctionne.
Intents
Q: Quand la synchronisation a-t-elle lieu ?
A: La synchronisation se produit immédiatement après la fin d'OAuth et après un appel de Request Sync (Demander la synchronisation).
Q: Pourquoi SYNC ne fonctionne-t-il pas ?
A: 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 envoyezaction.devices.types.Light.
- Par exemple, nous attendons
Vous envoyez des types d'appareils non compatibles.
- Par exemple, vous envoyez
action.devices.types.FLASHLIGHT, ce qui n'est pas accepté.
- Par exemple, vous envoyez
Vous envoyez des champs non valides ou non acceptés.
- Par exemple, vous avez un champ qui ne figure pas dans nos spécifications.
Un autre problème de formatage est survenu avec votre réponse SYNC.
- Vérifiez vos crochets.
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 requête 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 ?
A: Nous préférons vivement une réponse "success/fail" (réussite/échec) plutôt qu'une réponse "pending" (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 sommes conscients que certains appareils à faible consommation d'énergie 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:Ma commande n'est pas visible dans la section "Contrôle de la maison" de l'application Google Home. Que se passe-t-il ?
A: Confirmer que vous êtes 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 envoyer un rapport sur l'état d'un appareil ?
A: Google s'intéresse à la transition et à l'état final. Toutefois, si de nombreux changements d'état se produisent en peu de temps (par exemple, si 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é lorsque vous effectuez des appels d'état de rapport ?
A: Les mises à jour d'état partielles ne sont pas prises en charge. Par conséquent, les appels Report State doivent toujours inclure toutes les données d'un trait particulier qui a été mis à jour. Si deux traits créent une incohérence, ils doivent être signalés ensemble.
Q:Google peut-il interroger mon appareil pour obtenir son état (c'est-à-dire interroger l'appareil) ?
A: Il s'agit d'un mécanisme de remplacement que nous ne recommandons pas. Si nous devons recourir à 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 chargement inconnu, l'expérience utilisateur sera dégradée. Nous pensons que Report State est essentiel à 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 acceptées. Tout changement d'état en ligne de l'appareil doit également être signalé.
Notez que les scènes n'ont pas d'états. Toutefois, elles peuvent entraîner un changement d'état de l'appareil ou des appareils. Si l'état d'un appareil dans Google Home Graph change, 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 tant que réponse à un intent EXECUTE ou QUERY.
Q: Quelles sont les conséquences d'une implémentation incomplète de l'état du rapport avant la date limite ?
A: Cela dégradera l'expérience utilisateur, par exemple dans les surfaces Google Home app (GHA) et visuelles. Cela signifie que de nombreux intents QUERY seront envoyés pour interroger l'état, et 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 du rapport ?
A: Utiliser le Visualiseur Home Graph, un outil de test en libre-service qui affiche les états actuels de vos appareils stockés dans le 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 qu'ils ont reçu de la requête EXECUTE si 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 est modifié, devons-nous signaler le dernier état de tous les appareils ?
A: Non. Vous devez uniquement indiquer l'état de cet appareil spécifique.
Bonnes pratiques
Q: Quel type de latence est acceptable ?
A:Idéalement, elle doit être inférieure à 200 ms. Entre 2 et 5 secondes, c'est acceptable. Si votre latence se situe autour de cinq secondes, contactez-nous.
Q: Comment faire en sorte que mon enceinte à commande vocale réponde correctement lorsqu'elle est hors connexion ?
A: Renvoyer l'état hors connexion pour les appareils hors connexion. Nous renvoyons "non disponible pour le moment" comme synthèse vocale pour cette erreur. Pour en savoir plus, consultez la section Erreurs et exceptions.