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 de renforcer la sécurité de certaines actions, comme désactiver une caméra de sécurité ou ouvrir une porte. La validation secondaire de l'utilisateur n'est pas liée à une caractéristique spécifique de l'appareil, ce qui vous permet de décider quand Google Assistant doit émettre un défi. Par exemple, vous pouvez choisir d'émettre une question d'authentification pour le trait OnOff d'une caméra de sécurité, mais pas pour le trait OnOff d'une ampoule. Vous pouvez également émettre des Assistant dans certaines situations pour la même action. Par exemple, vous pouvez demander à Assistant d'envoyer une demande de validation pour ouvrir une porte si un porte-clés NFC n'est pas à proximité de cette porte, mais pas si le porte-clés est présent.

Le Assistant peut émettre deux types de demandes : une confirmation explicite ou un code secret. Cela ajoute un bloc de questions 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'intention à votre action avec les données du défi dans le bloc de défi. Vous pouvez ensuite valider les données du défi 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 d'authentification, mais si vous utilisez Assistant sur des surfaces non vocales, le code secret et les confirmations s'affichent à l'écran.

Quand utiliser la validation secondaire de l'utilisateur ?

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

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

  • Caractéristique OnOff si le type d'appareil est CAMERA.
  • Caractéristique OpenClose si le type d'appareil est DOOR, GARAGE, GATE ou WINDOW.
  • Le trait LockUnlock lors du déverrouillage.
  • Trait ArmDisarm lors du désarmement ou de l'annulation d'un désarmement.
  • Caractéristique Reboot, SoftwareUpdate ou NetworkControl si le type d'appareil est NETWORK ou ROUTER.

Le type de défi 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 validation secondaire de l'utilisateur acceptés :

  • Aucun challenge : demande et réponse qui n'utilisent pas de validation secondaire de l'utilisateur.
  • ackNeeded : validation secondaire de l'utilisateur qui nécessite une confirmation explicite ("Oui" ou "Non") et peut également utiliser les états de caractéristiques comme commentaires de réponse. Ce type de validation n'est pas recommandé pour les appareils et les traits de sécurité.
  • pinNeeded : une validation secondaire de l'utilisateur qui nécessite un code secret. Cette méthode est idéale pour les appareils et les caractéristiques de sécurité.

Aucun challenge

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

Utilisateur Allume les lumières.
Google Assistant D'accord, j'allume 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
      }
    }]
  }
}

ackNeeded

Authentification secondaire par confirmation de l'utilisateur, qui peut utiliser plusieurs états pour un trait ou une authentification par confirmation simple.

Voici les types de questions d'authentification ackNeeded :

ackNeeded simple

Cet exemple montre une requête et une réponse simples avec un défi ackNeeded pour baisser l'intensité d'une lumière et la confirmation de la baisse d'intensité.

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 caractéristiques

Authentification de confirmation par un utilisateur secondaire pouvant utiliser des états pour un trait. Par exemple, si vous utilisez le trait TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont définis, Assistant peut demander Êtes-vous sûr de vouloir régler le chauffage 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 traits et états suivants sont compatibles avec ackNeeded avec les états de traits. Si une caractéristique spécifique est listée, cela signifie que tous ses états sont pris en charge.

  • ArmDisarm
    • Utilisez le type de défi ackNeeded pour armer ou annuler l'armement de l'appareil, mais pour les fonctions de désarmement et d'annulation du désarmement, le type de défi pinNeeded est requis.
  • Fill
  • LockUnlock
    • Utilisez le type de défi ackNeeded pour verrouiller l'appareil et le type de défi pinNeeded pour le déverrouiller.
  • OnOff
    • on
    • Utilisez le type de défi ackNeeded pour ce trait. Le type de défi pinNeeded est obligatoire lorsque ce trait est utilisé avec des appareils CAMERA.
  • OpenClose
    • Utilisez le type de défi ackNeeded pour ce trait. Le type de défi pinNeeded est requis lorsque ce trait 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 défi ackNeeded qui utilise un état de caractéristique. Il passe la climatisation en mode chauffage et règle la température sur 28 degrés. Assistant demande ensuite aux utilisateurs de confirmer qu'ils souhaitent allumer le chauffage et régler la température sur 28 degrés, car une thermostatTemperatureSetpoint de 28 est renvoyée 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

Le défi pinNeeded est recommandé pour les dispositifs de sécurité.

Cet exemple montre une requête et une réponse initiales avec un défi pinNeeded. L'exemple renvoie une réponse avec un défi pinNeeded, donc Assistant demande 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éverrouille la porte.
Google Assistant Pouvez-vous m'indiquer 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 incorrect

Cet exemple montre la requête et la réponse avec un défi challengeFailedPinNeeded. Ce défi doit être utilisé après l'échec d'un défi 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 la section Réponses d'erreur.

Utilisateur 333222
Google Assistant Malheureusement, le code de sécurité est incorrect. Pouvez-vous m'indiquer 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 valide

Cet exemple montre la requête et la réponse d'un code 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 Pouvez-vous m'indiquer 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 d'erreur

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

  • tooManyFailedAttempts : Malheureusement, vous avez dépassé le nombre de tentatives infructueuses autorisé. Veuillez accéder à l'application de votre appareil pour effectuer cette action.
  • pinIncorrect : Malheureusement, le code de sécurité est incorrect.
  • userCancelled – OK

Consultez la liste complète des erreurs et exceptions.