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 d'appareil spécifique, ce qui vous permet de décider quand demander à Google Assistant de répondre à une question d'authentification. Par exemple, vous pouvez choisir de demander un défi pour la caractéristique OnOff d'une caméra de sécurité, mais pas pour la caractéristique OnOff d'une ampoule. Dans certaines situations, vous pouvez également rencontrer des questions d'authentification Assistant pour la même action. Par exemple, vous pouvez demander à Assistant d'envoyer une demande d'authentification pour ouvrir une porte si une porte sans contact NFC ne se trouve pas à proximité de cette porte, mais ne pas émettre de question si celle-ci est présente.

Le Assistant peut émettre deux types de questions d'authentification : accusé de réception explicite ou code d'identification personnel (PIN). Cela ajoute un bloc de défi 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 d'authentification dans le bloc d'authentification. Vous pouvez ensuite valider les données de la question d'authentification pour déterminer si l'utilisateur a donné la réponse de sécurité appropriée.

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

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 toutes les caractéristiques d'appareil.

Types d'authentification compatibles

Voici les types d'authentification secondaire acceptés:

  • Aucune question d'authentification : requête et réponse qui n'utilisent pas de question d'authentification secondaire pour la validation de l'utilisateur.
  • ackNeeded : vérification secondaire de l'utilisateur qui nécessite un accusé de réception explicite (oui ou non) et qui peut également utiliser les états de caractéristiques comme commentaires de réponse. Ce type de défi n'est pas recommandé pour les appareils et les caractéristiques de sécurité.
  • pinNeeded : validation secondaire de l'utilisateur nécessitant un code, ce qui est idéal pour les appareils et les caractéristiques de sécurité.

Aucun défi

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

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

Une authentification secondaire de la confirmation de l'utilisateur qui peut utiliser plusieurs états pour une caractéristique ou une simple authentification de confirmation.

Il existe les types de défis ackNeeded suivants:

ackNeeded simple

Cet exemple présente une requête et une réponse simples avec un défi ackNeeded permettant de baisser la luminosité d'une lumière, ainsi que la confirmation de la réduction.

Utilisateur Baisse la lumière du salon.
Google Assistant Je baisse la luminosité du salon. Continuer ?
Utilisateur Oui.
Google Assistant Je baisse la luminosité 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 les états de caractéristiques

Une authentification secondaire de la confirmation de l'utilisateur pouvant utiliser les états pour une caractéristique. Par exemple, si vous utilisez la caractéristique TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont définis, Assistant peut demander Voulez-vous vraiment régler 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 les ackNeeded avec des états de caractéristiques. Une liste d'une caractéristique spécifique indique que tous ses états sont pris en charge.

Cet exemple présente une requête et une réponse avec un défi ackNeeded qui utilise un état de trait. Il active le mode de climatisation et règle la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs de confirmer qu'ils doivent 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églez le mode climatisation sur Chauffage.
Google Assistant Voulez-vous vraiment régler le chauffage de la climatisation sur 28 degrés ?
Utilisateur Oui.
Google Assistantnt Je règle le chauffage de la climatisation 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
      }
    }]
  }
}

pinNeeded

La vérification pinNeeded est recommandée pour les appareils de sécurité.

Cet exemple présente une requête initiale et une réponse avec une question d'authentification pinNeeded. L'exemple renvoie une réponse avec un défi pinNeeded. Assistant demande donc l'épingle. À ce stade, l'utilisateur peut fournir un code incorrect ou valide.

Exemple de demande et de réponse pour un code secret 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 PIN incorrect.

Cet exemple présente la requête et la réponse avec une question d'authentification 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 la section 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 illustre la demande et la réponse d'un code secret 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:

  • challengeFailedNotSetup : cette action nécessite un code de sécurité, mais celui-ci n'a pas été configuré 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.