Bienvenue dans le Centre des développeurs Google Home, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque : Vous continuerez à créer des actions dans la console Actions.

Validation de l'utilisateur secondaire

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

La validation de l'utilisateur secondaire vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Cela vous permet de renforcer la sécurité de certaines actions, comme éteindre une caméra de sécurité ou ouvrir une porte. La validation de l'utilisateur secondaire n'est pas liée à une caractéristique d'appareil spécifique, ce qui vous permet de décider quand Google Assistant doit émettre une question d'authentification. Par exemple, vous pouvez choisir d'émettre une question d'authentification pour la caractéristique OnOff (désactivée) pour une caméra de sécurité, mais pas pour la caractéristique OnOff (activée) pour une lumière. Vous pouvez également rencontrer des problèmes Assistant dans certaines situations pour la même action. Par exemple, vous pouvez demander à Assistant d'émettre une requête d'authentification pour ouvrir une porte si un porte-clés NFC n'est pas à proximité de cette porte, mais pas de lancer un défi si le trousseau est présent.

L'Assistant peut émettre deux types de questions : la confirmation explicite ou le code secret. Cela ajoute un bloc de question d'authentification aux intents QUERY et EXECUTE envoyés depuis Assistant à votre action et accepte une réponse d'erreur challengeNeeded. Assistant renvoie ensuite la requête d'intent à votre action avec les données d'authentification du bloc d'authentification. Vous pouvez ensuite valider les données d'authentification pour déterminer si l'utilisateur a donné la réponse de sécurité correcte.

Assistant utilise la boîte de dialogue pour lancer le test, mais si vous utilisez Assistant sur des surfaces non vocales, le code et les confirmations sont effectués à l'écran.

Types d'appareils compatibles

La validation de l'utilisateur secondaire est compatible avec tous les types d'appareils.

Caractéristiques des appareils compatibles

La validation de l'utilisateur secondaire est compatible avec toutes les caractéristiques de l'appareil.

Types d'authentification acceptés

Voici les types d'authentification de validation des utilisateurs secondaires acceptés:

  • Aucun défi : requête et réponse qui n'utilisent pas de test de validation d'utilisateur secondaire.
  • ackNeeded : validation secondaire de l'utilisateur nécessitant un accusé de réception explicite (oui ou non) et pouvant également utiliser des états de caractéristiques en tant que commentaires de réponse. Ce type d'authentification n'est pas recommandé pour les caractéristiques et appareils de sécurité.
  • pinNeeded : validation secondaire de l'utilisateur nécessitant un code secret, idéal pour les appareils et les caractéristiques de sécurité.

Aucun défi

Cet exemple montre une requête EXECUTE réussie et une réponse sans difficulté à allumer les lumières.

Utilisateur Allume la lumière.
Google Assistant OK, j'allume les trois lumières.
Demande
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

Confirmation requise

Une authentification de confirmation utilisateur secondaire pouvant utiliser plusieurs états pour une caractéristique ou une simple authentification.

Il existe les types d'authentification ackNeeded suivants:

ackNeeded simple

Cet exemple montre une requête simple et une réponse avec un défi ackNeeded pour baisser la lumière, et une confirmation pour diminuer la lumière.

Utilisateur Baisse la lumière du salon.
Google Assistant Je baisse la lumière du salon. Continuer ?
Utilisateur Oui.
Google Assistant Je baisse la lumière du salon.
Demande 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Réponse 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Demande 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Réponse 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded avec des états de caractéristiques

Une authentification de confirmation de l'utilisateur secondaire pouvant utiliser des états pour une caractéristique. Par exemple, si vous travaillez avec la caractéristique TempératureSetting, et que thermostatMode et thermostatTemperatureSetpoint sont tous les deux définis, Assistant peut demander Voulez-vous vraiment définir la température de la climatisation sur 28 degrés ?

Vous pouvez également inclure un état dans une réponse pour que Assistant effectue une action spécifique en fonction d'une requête donnée.

Les caractéristiques et les états suivants sont compatibles avec ackNeeded avec des états de caractéristiques. La liste d'une caractéristique spécifique indique que tous ses états sont acceptés.

Cet exemple montre une requête et une réponse avec un défi ackNeeded qui utilise un état de caractéristique. Il règle le climatiseur sur chauffage et règle la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs l'accusé de réception pour allumer le chauffage et définir la température sur 28 degrés, car un résultat thermostatTemperatureSetpoint de 28 est renvoyé en tant qu'état dans la réponse.

Utilisateur Règle le mode AC sur le chauffage.
Google Assistant Voulez-vous vraiment régler le chauffage de la climatisation à 28 degrés ?
Utilisateur Oui.
Google Assistant Je règle le chauffage du climatiseur sur 28 degrés.
Demande 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}
Réponse 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Demande 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Réponse 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

Besoin d'une épingle

L'authentification pinNeeded est recommandée pour les appareils de sécurité.

Cet exemple montre une requête et une réponse initiales comportant un défi pinNeeded. L'exemple renvoie une réponse avec un test pinNeeded. Assistant demande donc le code. À ce stade, l'utilisateur peut fournir un code incorrect ou valide.

Exemple de requête et de réponse pour un code incorrect ou valide:

Utilisateur Déverrouillez la porte.
Google Assistant Puis-je avoir votre code de sécurité ?
Demande
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Code PIN incorrect.

Cet exemple montre la requête et la réponse avec un défi challengeFailedPinNeeded. Utilisez ce défi après l'échec d'un premier défi pinNeeded.

Lorsqu'un type challengeFailedPinNeeded est renvoyé, Assistant demande à nouveau le code de sécurité. Si l'utilisateur effectue un trop grand nombre de tentatives infructueuses, vous pouvez renvoyer une réponse d'erreur tooManyFailedAttempts. Consultez Réponses d'erreur.

Utilisateur 333222
Google Assistant Désolé, le code de sécurité est incorrect. Puis-je avoir votre code de sécurité ?
Demande
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Code PIN valide

Cet exemple montre la requête et un message de code d'accès valide.

Utilisateur 333444
Google Assistant Je déverrouille la porte.
Demande
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Utilisateur Baisse la lumière du salon.
Google Assistant Puis-je avoir votre code de sécurité ?
Demande
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Réponses aux erreurs

Voici quelques codes d'erreur pouvant être renvoyés avec vos réponses:

  • challengeFailedNotSetup : cette action nécessite un code de sécurité, mais elle n'a pas été configurée dans l'application de votre appareil.
  • tooManyFailedAttempts - Désolé, trop de tentatives infructueuses. Veuillez accéder à l'application de votre appareil pour effectuer cette action.
  • pinIncorrect : Désolé, le code de sécurité est incorrect.
  • userCancelled - OK.

Consultez la liste complète des erreurs et exceptions.