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 à une caractéristique d'appareil spécifique, ce qui vous permet de décider quand Google Assistant doit émettre une demande de validation. Par exemple, vous pouvez choisir d'émettre une demande de validation pour la caractéristique OnOff d'une caméra de sécurité, mais pas pour la demande de validation pour la OnOff caractéristique d'une lumière. Vous pouvez également demander à Assistant Assistant d'émettre des demandes de validation dans certaines situations pour la même action. Par exemple, vous pouvez demander à Assistant d'émettre une demande de validation pour ouvrir une porte si un porte-clés NFC ne se trouve pas à proximité de cette porte, mais pas si le porte-clés est présent.

Le Assistant peut émettre deux types de demandes de validation : une confirmation explicite ou un code secret. Cela ajoute un bloc de demande de validation 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 demande de validation dans le bloc de demande de validation. Vous pouvez ensuite valider les données de la demande de validation 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 validation, 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 d'appareil ou caractéristique. Toutefois, vous devez implémenter la validation secondaire de l'utilisateur pour certains types d'appareils et certaines caractéristiques sensibles à la sécurité afin de faire certifier votre intégration.

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

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

Le type de demande de validation ackNeeded est requis pour la caractéristique TemperatureSetting si le type d'appareil est AC_UNIT et que l'intégration se trouve au Japon.

Types de demandes de validation compatibles

Voici les types de demandes de validation secondaires de l'utilisateur compatibles :

  • Aucune demande de validation : demande et réponse qui n'utilisent pas de demande 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 la caractéristique comme commentaires de réponse. Ce type de demande de validation 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 secret, idéal pour les appareils et les caractéristiques de sécurité.

Aucune demande de validation

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

Utilisateur Allume les lumières.
Google Assistant OK, 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 une caractéristique ou une authentification de confirmation simple.

Il existe les types de demandes de validation ackNeeded suivants :

ackNeeded simple

Cet exemple montre une requête et une réponse simples avec une demande de validation ackNeeded pour tamiser une lumière et la confirmation de tamisage de la lumière.

Utilisateur Tamise la lumière du salon.
Google Assistant Je tamise la lumière du salon. Continuer ?
Utilisateur Oui.
Google Assistant Je tamise 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 les états de la caractéristique

Authentification de confirmation secondaire de l'utilisateur qui peut utiliser les états d'une caractéristique. Par exemple, si vous utilisez la caractéristique TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont définis, Assistant peut vous 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 caractéristiques et états suivants sont compatibles avec ackNeeded avec les états de la caractéristique. Une liste d'une caractéristique spécifique indique que tous ses états sont compatibles.

  • ArmDisarm
    • Utilisez le type de demande de validation ackNeeded pour activer ou annuler l'activation de l'appareil, mais pour les fonctions de désactivation et d'annulation de la désactivation, le type de demande de validation pinNeeded est requis.
  • Fill
  • LockUnlock
    • Utilisez le type de demande de validation ackNeeded pour verrouiller l'appareil et le pinNeeded type de demande de validation pour le déverrouiller.
  • OnOff
    • on
    • Utilisez le type de demande de validation ackNeeded pour cette caractéristique. Le type de demande de validation pinNeeded est requis lorsque cette caractéristique est utilisée avec des appareils CAMERA.
  • OpenClose
    • Utilisez le type de demande de validation ackNeeded pour cette caractéristique. Le type de demande de validation pinNeeded est requis lorsque cette caractéristique est utilisée 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 une demande de validation ackNeeded qui utilise un état de caractéristique. Il change le mode de climatisation en 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 climatisation sur chauffage.
Google Assistant Êtes-vous sûr de vouloir 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

La demande de validation pinNeeded est recommandée pour les appareils de sécurité.

Cet exemple montre une requête et une réponse initiales avec une demande de validation pinNeeded. L'exemple renvoie une réponse avec une demande de validation 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éverrouille la porte.
Google Assistant Quel est 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 une demande de validation challengeFailedPinNeeded. Cette demande de validation doit être utilisée après l'échec d'une demande de validation pinNeeded initiale.

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 Malheureusement, le code de sécurité est incorrect. Quel est 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 Tamise la lumière du salon.
Google Assistant Quel est 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.