Validation de l'utilisateur secondaire

La validation secondaire de l'utilisateur vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Cela vous permet d'ajouter une sécurité supplémentaire pour certaines actions, comme éteindre une caméra de sécurité ou ouvrir une porte. La validation secondaire de l'utilisateur n'est pas liée à un trait d'appareil spécifique, ce qui vous permet de décider quand Google Assistant doit émettre une demande de confirmation. Par exemple, vous pouvez choisir d'émettre une demande d'authentification pour le trait OnOff d'une caméra de sécurité, mais pas pour le trait OnOff d'une lumière. Vous pouvez également demander à Assistant d'émettre des questions de validation dans certaines situations pour la même action. Par exemple, vous pouvez demander à Assistant d'émettre une demande de vérification pour ouvrir une porte si un porte-clés NFC n'est pas à proximité de cette porte, mais de ne pas émettre de demande de vérification si le porte-clés est présent.

Le Assistant peut émettre deux types de demandes de confirmation : une confirmation explicite ou un code secret. Cela ajoute un bloc de vérification aux intents QUERY et EXECUTE envoyés par 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 de la question secrète dans le bloc de question secrète. Vous pouvez ensuite valider les données de la question d'authentification pour déterminer si l'utilisateur a fourni la bonne réponse de sécurité.

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

Quand utiliser la validation secondaire de l'utilisateur ?

Vous pouvez activer la validation secondaire de l'utilisateur pour n'importe quel type d'appareil ou trait. Toutefois, vous devez implémenter la validation secondaire de l'utilisateur pour certains types d'appareils et caractéristiques sensibles en termes de sécurité afin de faire certifier votre intégration.

La validation secondaire de l'utilisateur à l'aide du type de question d'authentification pinNeeded est requise pour les combinaisons de caractéristiques et de types d'appareils suivantes :

  • L'attribut OnOff si le type d'appareil est CAMERA.
  • Le trait OpenClose si le type d'appareil est DOOR, GARAGE, GATE ou WINDOW.
  • L'attribut LockUnlock lors du déverrouillage.
  • L'attribut ArmDisarm lors de la désactivation ou de l'annulation d'une désactivation.
  • Le trait Reboot, SoftwareUpdate ou NetworkControl si le type d'appareil est NETWORK ou ROUTER.

Le type de question d'authentification ackNeeded est requis pour le trait TemperatureSetting si le type d'appareil est AC_UNIT et que l'intégration se trouve au Japon.

Types de questions d'authentification acceptés

Voici les types de questions de validation secondaire de l'utilisateur acceptés :

  • Aucun test : requête et réponse qui n'utilisent pas de test de validation secondaire de l'utilisateur.
  • ackNeeded : validation secondaire de l'utilisateur qui nécessite une confirmation explicite (oui ou non) et qui peut également utiliser les états des caractéristiques comme réponse. Ce type de question n'est pas recommandé pour les appareils et les caractéristiques de sécurité.
  • pinNeeded : validation secondaire de l'utilisateur qui nécessite un code d'identification personnel (PIN), idéal pour les appareils et les caractéristiques de sécurité.

Aucun test

Cet exemple montre une requête et une réponse EXECUTE réussies sans question d'authentification pour allumer les lumières.

Utilisateur Allume la lumière.
Google Assistant D'accord, j'allume trois lumières.
Demander
{
  "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
      }
    }]
  }
}

ackNeeded

Authentification secondaire de confirmation de l'utilisateur pouvant utiliser plusieurs états pour un trait ou une authentification de confirmation simple.

Il existe les types de questions d'authentification ackNeeded suivants :

ackNeeded simple

Cet exemple montre une requête et une réponse simples avec un test ackNeeded pour tamiser une lumière et la confirmation de tamiser 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.
Requête 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 les états de trait

Authentification secondaire de confirmation de l'utilisateur pouvant utiliser des états pour un trait. Par exemple, si vous utilisez la caractéristique TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont tous deux définis, Assistant peut demander Voulez-vous vraiment régler le chauffage du climatiseur 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 états suivants sont compatibles avec ackNeeded avec les états de caractéristiques. La liste d'une caractéristique spécifique indique que tous ses états sont acceptés.

  • ArmDisarm
    • Utilisez le type de question d'authentification ackNeeded pour armer ou annuler l'armement de l'appareil. En revanche, pour les fonctions de désarmement et d'annulation du désarmement, le type de question d'authentification pinNeeded est requis.
  • Fill
  • LockUnlock
    • Utilisez le type de question d'authentification ackNeeded pour verrouiller l'appareil et le type de question d'authentification pinNeeded pour le déverrouiller.
  • OnOff
    • on
    • Utilisez le type de question ackNeeded pour ce trait. Le type de question d'authentification pinNeeded est obligatoire lorsque ce trait est utilisé avec des appareils CAMERA.
  • OpenClose
    • Utilisez le type de question ackNeeded pour ce trait. Le type de question d'authentification pinNeeded est requis lorsque cet attribut est utilisé avec des appareils DOOR, GARAGE, GATE ou WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Cet exemple montre une requête et une réponse avec un test d'authentification ackNeeded qui utilise un état de caractéristique. Elle passe le climatiseur en mode chauffage et règle la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs de confirmer qu'ils souhaitent allumer le chauffage et régler la température sur 28 degrés, car un thermostatTemperatureSetpoint de 28 est renvoyé en tant qu'état dans la réponse.

Utilisateur Règle la climatisation sur le mode chauffage.
Google Assistant Voulez-vous vraiment régler le chauffage de la climatisation sur 28 degrés ?
Utilisateur Oui.
Google Assistant Je règle le chauffage de la climatisation sur 28 degrés.
Requête 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
      }
    }]
  }
}

pinNeeded

La question d'authentification pinNeeded est recommandée pour les appareils de sécurité.

Cet exemple montre une requête et une réponse initiales avec un test 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é ?
Demander
{
  "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 incorrect

Cet exemple montre la requête et la réponse avec un test challengeFailedPinNeeded. Ce test doit être utilisé après l'échec d'un test pinNeeded initial.

Lorsqu'un type challengeFailedPinNeeded est renvoyé, Assistant demande à nouveau le code de sécurité. Si l'utilisateur effectue trop 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é ?
Demander
{
  "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 valide

Cet exemple montre la requête et la réponse d'un code valide.

Utilisateur 333444
Google Assistant Je déverrouille la porte.
Demander
{
  "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é ?
Demander
{
  "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 d'erreur

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

  • tooManyFailedAttempts : Désolé, trop de tentatives ont échoué. 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.