1. Avant de commencer
Cet atelier de programmation est conçu pour les partenaires et développeurs Google Home avec intégrations Cloud afin d'améliorer la qualité de l'écosystème et l'expérience utilisateur.
Points abordés
Le tableau de bord Google Home Vitals sert de source de vérité centrale aux développeurs et partenaires pour surveiller l'état opérationnel de leurs intégrations Google Home. Dans un écosystème où l'expérience utilisateur est définie par la latence et la fiabilité, Google Home Vitals est le portail en libre-service qui contient toutes les analyses approfondies nécessaires pour passer du dépannage réactif à la gestion proactive de la qualité.
- Comment le score de qualité de votre intégration est-il calculé ?
- Lire et utiliser le tableau de bord
- Déboguer les métriques de mauvaise qualité
Prérequis
- Disposer d'une intégration Google Home Cloud
Configuration
Pour accéder au tableau de bord Google Home Vitals :
- Ouvrir Google Cloud Platform
- Monitoring > Tableau de bord
- Cliquez sur le tableau de bord "Google Home Vitals (Cloud)".
2. Lire le tableau de bord
Calcul du niveau de qualité : norme "Bon" vs norme "Mauvais"
Le tableau de bord explique la répartition de la note de qualité. Les niveaux de qualité sont attribués en fonction du type d'appareil. Pour qu'une intégration de type d'appareil soit considérée comme BONNE, elle doit répondre à quatre critères simultanément :
- Taux de réussite global : le taux de réussite global des appels entre le partenaire et Google doit être supérieur ou égal à 99,5%.
Remarque : Si le taux de réussite global n'est pas atteint (supérieur ou égal à 99,5%), la note MAUVAISE est automatiquement attribuée à l'ensemble du projet, quelle que soit la performance de chaque appareil. - Fiabilité des commandes : les taux de réussite des commandes QUERY et EXECUTE doivent être supérieurs ou égaux à 99,5% pour chaque type d'appareil.
- Latence de réponse : la latence au 90e centile pour QUERY et EXECUTE doit être inférieure ou égale à 1 000 ms pour chaque type d'appareil.
- Intégrité de l'état : la précision de l'état doit être supérieure ou égale à 99,5%.
Pourquoi ces métriques sont-elles importantes ?
- Taux de réussite global : les appels partenaire-Google au niveau de l'intégration mesurent l'état des appels de votre cloud vers Google. Un taux de réussite supérieur ou égal à 99,5% garantit que Google Home utilise les états d'appareil corrects. Par exemple, vous pouvez vérifier que des appareils sont ajoutés et supprimés, que des automatisations se déclenchent et que des événements de l'historique s'affichent dans l'onglet "Activité" de l'application Google Home.
- Fiabilité des commandes : les taux de réussite des commandes QUERY et EXECUTE sont mesurés au niveau du type d'appareil. Un taux de réussite supérieur ou égal à 99, 5% garantit que les commandes de vos utilisateurs sont exécutées correctement (c'est-à-dire qu'il évite les réponses de l'Assistant telles que "Je n'arrive pas à accéder à l'appareil" ou la confirmation incorrecte d'une commande qui n'a pas été exécutée).
- Latence de réponse : les latences QUERY et EXECUTE sont également mesurées au niveau du type d'appareil. Une latence inférieure ou égale à 1 000 ms par type d'appareil garantit que votre utilisateur n'a pas à attendre trop longtemps pour effectuer l'action souhaitée (par exemple, quelques secondes pour que sa lumière s'éteigne).
- Intégrité de l'état : la précision de l'état stocké dans les systèmes Google et utilisé pour répondre aux requêtes des utilisateurs. Si ces nombres sont faibles, les utilisateurs peuvent voir des résultats incorrects pour vos appareils lorsqu'ils consultent leur état ou utilisent des fonctionnalités d'IA comme Demander à Home. Il est possible que les automatisations ne se déclenchent pas et que les entrées d'historique ne s'affichent pas dans l'activité au bon moment.
Lire le tableau de bord
Commencez par la section "Métriques du niveau de qualité", qui sert d'indicateur principal de l'état de votre intégration. Pour qu'un appareil soit considéré comme BON, toutes les métriques de cette section doivent répondre aux critères de réussite VERTS. Vous trouverez des informations techniques détaillées et des définitions de métriques dans la documentation du Developer Center.
La section "Score des métriques de qualité" en haut du tableau de bord Google Home Vitals reflète les métriques utilisées pour calculer le niveau de qualité de votre intégration.
Légende
- VERT (BON) : la métrique atteint le seuil de qualité.
- ROUGE (MAUVAISE) : la métrique ne respecte pas le seuil de qualité.
Exemple
Dans l'exemple ci-dessous, vous pouvez voir que le type d'appareil AC_UNIT répond aux critères de qualité dans les sections "Taux de réussite des requêtes et des exécutions" et "Latence des requêtes", mais échoue au niveau de la barre "Latence des exécutions" (rouge). Cela signifie que les commandes réussissent à un taux acceptable, mais que la latence EXECUTE est trop lente de 36 ms. La section "État du système" indique un taux d'échec de 98, 92% pour les méthodes agrégées dans l'intégration.Cela signifie qu'il est possible d'améliorer la précision de l'état des appareils des utilisateurs dans Google Home. Cela signifie que 1,08% des appels (DeleteAgentUser, Query, ReportStateAndNotification, RequestSyncDevices ou Sync) renvoient des codes de réponse qui ne sont pas égaux à 2xx ou 5xx (par exemple, erreurs 404). La dernière métrique utilisée pour mesurer la qualité de réussite/échec pour le type d'appareil AC_UNIT est la précision de l'état. Dans cet exemple, le taux de réussite est de 77,43 %, ce qui signifie que les utilisateurs sont susceptibles de voir des résultats inexacts pour les appareils. Avec ces trois métriques, le score global pour AC_UNIT est FAIBLE et inférieur au seuil de qualité.
Chacun de ces calculs de qualité correspond à une section de débogage ci-dessous. Développez les étapes réduites pour déboguer davantage.
Pour déboguer les taux de réussite et les latences des requêtes/exécutions, accédez à "Étape 1 : Valider les appels Cloud".
Pour déboguer les taux de réussite des partenaires vers Google, accédez à "Étape 2 : Valider les appels à Google".
Pour déboguer la précision de l'état pour chaque type d'appareil, accédez à "Étape 3 : Améliorer la précision de l'état".
3. Étape de débogage 1 : Valider les appels Cloud
Étape 1 : Présentation
Cette section se concentre sur les appels cloud, c'est-à-dire les métriques qui mesurent l'état des communications entre Google et votre backend cloud (également appelées métriques Google-to-Partner). Cela inclut des commandes telles que Query et Execute.
Nous suivons les taux de réussite et les latences pour les requêtes et les exécutions (qui sont pris en compte dans les scores de qualité de vos types d'appareils).
L'aperçu ci-dessous montre les taux de réussite et les erreurs agrégés des requêtes et des exécutions au niveau de l'intégration. Les étapes 1a à 1d montrent la répartition de ces métriques au niveau du type/trait de l'appareil. 
Les étapes 1a et 1b montrent l'évolution du nombre de demandes d'exécution, du nombre d'erreurs au fil du temps et des états d'erreur spécifiques.
Étape 1a : Examiner les erreurs de requête
Étape 1b : Examiner les erreurs d'exécution
Les étapes 1c et 1d montrent la répartition des 90e et 50e centiles pour ces métriques, à la fois au niveau de l'intégration et au niveau du type d'appareil.
Étape 1c : Examiner la latence des requêtes
Étape 1d : Examiner la latence d'exécution
4. Étape 2 de débogage : Valider les appels à Google
Étape 2 : Aperçu
Après le débogage des appels de Google au partenaire, cette seconde étape couvre le débogage des appels du cloud du partenaire à Google. Cette section couvre les métriques au niveau de l'intégration du partenaire, et non au niveau du type d'appareil. Cela inclut les codes de réponse tels que 400 Bad Request, 404 Not Found et 429 Resource Exhausted.
Étape 2a : Déboguer les problèmes de quota
Google Home impose des limites à l'attribution et à l'utilisation des ressources, et applique des quotas appropriés pour chaque projet. Google applique la limite par défaut de 6 000 requêtes par période de 60 secondes à l'ensemble de vos appels d'API de requête, de suppression, de signalement de l'état et de synchronisation des requêtes asynchrones, pour chaque intégration cloud à cloud.
Les problèmes de quota peuvent avoir un impact négatif sur la précision de l'état des rapports, car l'échec d'une mise à jour de l'état peut entraîner une incohérence. Vous trouverez ci-dessous des graphiques détaillés qui indiquent l'état des rapports et les erreurs de synchronisation des requêtes, la répartition des méthodes d'API par nombre et par erreurs, ainsi que le pourcentage d'utilisation du quota. Si ces graphiques affichent une augmentation inattendue du trafic, examinez votre intégration pour déterminer si une modification entraîne l'envoi d'un trafic plus important à l'API Home Graph.
Dans certains cas, comme la croissance naturelle du trafic au fil du temps (par exemple, la croissance est cohérente avec une augmentation du nombre d'appareils, le lancement d'un nouveau type d'appareil ou un autre lancement prévu), il peut être approprié d'augmenter le quota de votre intégration. Pour demander une augmentation de quota, suivez les étapes décrites dans notre documentation pour les développeurs.
5. Étape de débogage 3 : Améliorer la précision de l'état
Étape 3 : Aperçu
Une fois les étapes 1 et 2 déboguées, l'étape 3 porte sur la précision de Signaler l'état, c'est-à-dire les états des appareils stockés dans les systèmes Google, qui sont utilisés pour répondre aux requêtes des utilisateurs. Vous trouverez ci-dessous des répartitions par trait et par type d'appareil. Les étapes 3a et 3b couvrent deux erreurs courantes pour l'état du rapport : les erreurs de champ manquant et les erreurs d'inexactitude.
Étape 3a : Erreurs "Champ manquant"
Les erreurs "Champ manquant" se produisent lorsque l'ensemble des champs de charge utile diffère entre une réponse QUERY et une demande d'état signalé pour un appareil donné. L'ensemble des champs de la charge utile de chaque appareil doit être identique. Cela peut se produire si la logique de calcul de la charge utile diffère entre la réponse à l'état de la requête et celle du rapport. Utilisez les graphiques ci-dessous pour identifier les types d'appareils et les caractéristiques dont les réponses QUERY et les réponses d'état des rapports ne correspondent pas.
Étape 3b : Erreurs "Inexact"
Les erreurs inexactes se produisent lorsque l'ensemble des champs de charge utile est identique entre une réponse QUERY et une demande d'état signalé pour un appareil donné, mais que les valeurs d'état diffèrent. Cela peut se produire si un rapport d'état est manquant ou si la logique de calcul de l'état diffère entre QUERY et un rapport d'état. Utilisez les graphiques ci-dessous pour identifier les types d'appareils et les caractéristiques dont les réponses QUERY et les réponses d'état des rapports ne correspondent pas.
6. Autres ressources et documentation
- Pour envoyer des commentaires ou signaler des problèmes concernant ce tableau de bord, créez un problème dans notre Issue Tracker public.
- Pour faire appel, signalez un problème à l'aide de notre formulaire d'appel concernant les métriques de qualité.
- Pour suivre régulièrement la qualité de votre intégration, configurez des alertes Google Cloud Platform afin de recevoir des notifications lorsque vos métriques passent en dessous d'un seuil acceptable. Vous serez ainsi le premier informé en cas de problème.
- Pour toute autre information, veuillez consulter la documentation du développeur : https://developers.home.google.com/tools/analytics/home-vitals.