Validation de l'utilisateur secondaire

La validation secondaire de l'utilisateur vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Vous pouvez ainsi renforcer la sécurité de 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 un challenge. Par exemple, vous pouvez choisir d'émettre un challenge pour le trait OnOff d'une caméra de sécurité, mais pas pour le OnOff trait d'une lumière. Vous pouvez également demander à l'Assistant d'Assistant émettre des challenges dans certaines situations pour la même action. Par exemple, vous pouvez demander à Assistant d'émettre une requête de challenge pour ouvrir une porte si un porte-clés NFC ne se trouve pas à proximité de cette porte, mais pas d'émettre de challenge si le porte-clés est présent.

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

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

Types d'appareils compatibles

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

Traits d'appareil compatibles

La validation secondaire de l'utilisateur est compatible avec tous les traits d'appareil.

Types de challenges compatibles

Voici les types de challenges compatibles pour la validation secondaire de l'utilisateur :

  • Aucun challenge : requête et réponse qui n'utilisent pas de challenge 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 de trait comme commentaires de réponse. Ce type de challenge n'est pas recommandé pour les appareils et traits de sécurité.
  • pinNeeded : validation secondaire de l'utilisateur qui nécessite un code secret, idéal pour les appareils et traits de sécurité.

Aucun challenge

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

Utilisateur Allume la lumière.
Google Assistant D'accord, j'allume trois lumières.
Requête
{
  "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 de confirmation secondaire de l'utilisateur qui peut utiliser plusieurs états pour un trait ou une authentification de confirmation simple.

Il existe les types de challenges ackNeeded suivants :

ackNeeded simple

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

Utilisateur Baisse l'intensité de la lumière du salon.
Google Assistant Je baisse l'intensité de la lumière du salon. Continuer ?
Utilisateur Oui.
Google Assistant Je baisse l'intensité de 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"
      }
    }]
  }
}
Requête 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 états de trait

Authentification de confirmation secondaire de l'utilisateur qui peut utiliser des états pour un trait. Par exemple, si vous utilisez le TemperatureSetting trait et que thermostatMode et thermostatTemperatureSetpoint sont définis, Assistant peut demander Voulez-vous vraiment 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.

Les traits et états suivants sont compatibles avec ackNeeded avec états de trait. Une liste d'un trait spécifique indique que tous ses états sont compatibles.

Cet exemple montre une requête et une réponse avec un challenge ackNeeded qui utilise un état de trait. Il remplace le mode de la climatisation par le chauffage et règle la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs de confirmer qu'ils souhaitent activer 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 le mode de la climatisation sur 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"
      }
    }]
  }
}
Requête 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 challenge pinNeeded est recommandé pour les appareils de sécurité.

Cet exemple montre une requête et une réponse initiales avec un challenge pinNeeded. L'exemple renvoie une réponse avec un pinNeeded challenge. 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éverrouille la porte.
Google Assistant Pouvez-vous m'indiquer votre code de sécurité ?
Requête
{
  "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 challenge challengeFailedPinNeeded. Ce challenge doit être utilisé après l'échec d'un challenge 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é ?
Requête
{
  "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.
Requête
{
  "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 l'intensité de la lumière du salon.
Google Assistant Pouvez-vous m'indiquer votre code de sécurité ?
Requête
{
  "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 effectué trop de tentatives infructueuses. 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 des exceptions.