Validation de l'utilisateur secondaire

La validation de l'utilisateur secondaire vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Vous pouvez ainsi renforcer la sécurité 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 à une caractéristique spécifique de l'appareil, ce qui vous permet de décider quand Google Assistant posera une question d'authentification. Par exemple, vous pouvez émettre une question d'authentification pour la caractéristique OnOff d'une caméra de sécurité, mais pas pour la caractéristique OnOff pour une lumière. Vous pouvez également avoir des défis 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 une clé sans contact NFC ne se trouve pas à proximité, mais ne pas envoyer de demande d'authentification si la clé sans contact est présente.

Le Assistant peut émettre deux types de questions d'authentification : la confirmation explicite ou le numéro d'identification personnel (PIN). Cela ajoute un bloc de challenge aux intents QUERY et EXECUTE renvoyé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 défi dans le 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é appropriée.

Assistant utilise la boîte de dialogue pour émettre le test, 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'authentifications acceptés

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

  • Aucun défi : requête et réponse qui n'utilisent pas de question d'authentification secondaire pour la validation 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 caractéristique comme commentaire de réponse. Ce type d'authentification n'est pas recommandé pour les appareils et les caractéristiques de sécurité.
  • pinNeeded : une validation secondaire de l'utilisateur qui nécessite un code d'identification personnel (code), ce qui est idéal pour les dispositifs et les caractéristiques de sécurité.

Aucun défi

Cet exemple montre une requête et une réponse EXECUTE réussies, sans qu'il soit nécessaire d'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 confirmation de l'utilisateur qui peut utiliser plusieurs états pour une caractéristique ou une simple authentification de confirmation.

Il existe les types d'authentification ackNeeded suivants:

ackNeeded simple

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

Une authentification secondaire de confirmation de l'utilisateur pouvant utiliser des états pour une caractéristique. Par exemple, si vous travaillez avec la caractéristique TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont tous deux définis, Assistant peut demander Voulez-vous vraiment régler le chauffage sur 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 é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. Elle active le mode chauffage sur le climatiseur et règle la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs la confirmation d'allumer le chauffage et de définir la température sur 28 degrés, car un thermostatTemperatureSetpoint de 28 est renvoyé sous forme d'é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 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
      }
    }]
  }
}

pinNeeded

Le test pinNeeded est recommandé pour les appareils de sécurité.

Cet exemple montre une requête initiale et une réponse avec un défi pinNeeded. L'exemple renvoie une réponse avec un défi 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 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 montre la requête et la réponse avec un défi challengeFailedPinNeeded. Cette question d'authentification doit être utilisée après l'échec d'une première vérification pinNeeded.

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 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 d'accès valide

Cet exemple illustre la demande et la réponse d'un code PIN valide.

Utilisateur 333444
Google Assistant Déverrouillage de 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'appli 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.