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 un challenge. Par exemple, vous pouvez choisir d'émettre un challenge pour la caractéristique OnOff d'une caméra de sécurité, mais pas pour celle de la OnOff caractéristique 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'envoyer 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 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 réponse d'erreur challengeNeeded. 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

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 challenge 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 de la désactivation.
  • La caractéristique Reboot, SoftwareUpdate ou NetworkControl si le type d'appareil est NETWORK ou ROUTER.

Le type de challenge 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 challenges compatibles

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

  • Aucun challenge : demande 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 la caractéristique comme commentaires de réponse. Ce type de challenge n'est pas recommandé pour les appareils et caractéristiques de sécurité.
  • pinNeeded : validation secondaire de l'utilisateur qui nécessite un code secret, idéal pour les appareils et caractéristiques 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 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 challenges ackNeeded suivants :

ackNeeded simple

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

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 états de la caractéristique

Authentification de confirmation secondaire de l'utilisateur qui peut utiliser des états pour 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.

Les caractéristiques et états suivants sont compatibles avec ackNeeded avec états de la caractéristique. Si une caractéristique spécifique est listée, cela signifie que tous ses états sont compatibles.

  • ArmDisarm
    • Utilisez le type de challenge 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 challenge pinNeeded est requis.
  • Fill
  • LockUnlock
    • Utilisez le type de challenge ackNeeded pour verrouiller l'appareil et le pinNeeded type de challenge pour le déverrouiller.
  • OnOff
    • on
    • Utilisez le type de challenge ackNeeded pour cette caractéristique. Le type de challenge pinNeeded est requis lorsque cette caractéristique est utilisée avec des appareils CAMERA.
  • OpenClose
    • Utilisez le type de challenge ackNeeded pour cette caractéristique. Le type de challenge 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 un challenge ackNeeded qui utilise un état de la caractéristique. Il change le mode de la climatisation en chauffage et règle la température sur 28 degrés. L'Assistant demande ensuite 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.Assistant

Utilisateur Règle le mode de la 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

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 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 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 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 exceptions.