Дополнительная верификация пользователя

Дополнительная верификация пользователя позволяет добавить двухфакторную аутентификацию для голосовых команд. Это позволяет повысить безопасность при выполнении определенных действий, например при отключении камеры видеонаблюдения или открытии двери. Дополнительная верификация пользователя не привязана к определенному свойству устройства, поэтому вы можете сами решать, когда Google Assistant будет запрашивать подтверждение. Например, вы можете выбрать, чтобы при использовании функции OnOff для камеры видеонаблюдения требовалось подтверждение, а для функции OnOff для светильника – нет. В некоторых случаях Assistant может запрашивать подтверждение личности для одного и того же действия. Например, вы можете настроить Assistant так, чтобы при попытке открыть дверь без NFC-брелока отправлялся запрос на подтверждение, а при наличии брелока – нет.

Assistant может выдавать два типа запросов: явное подтверждение или PIN-код. Это добавляет блок проверки к намерениям QUERY и EXECUTE, отправленным из Assistant обратно в ваше действие, и принимает ответ об ошибке challengeNeeded. Assistant отправляет запрос намерения обратно вашему действию с данными проверки в блоке проверки. Затем вы можете проверить данные, чтобы определить, правильно ли пользователь ответил на запрос.

Assistant использует диалог, чтобы выдать запрос, но если вы используете Assistant на устройствах без голосового управления, PIN-код и подтверждения выполняются на экране.

Когда использовать дополнительную верификацию пользователя

Вы можете включить дополнительную верификацию пользователя для любого типа устройства или характеристики. Однако для сертификации интеграции необходимо реализовать дополнительную верификацию пользователя для определенных типов устройств и функций, связанных с безопасностью.

Дополнительная верификация пользователя с помощью pinNeeded требуется для следующих комбинаций типа устройства и типажа:

  • Черта OnOff, если тип устройства – CAMERA.
  • Типаж OpenClose, если тип устройства – DOOR, GARAGE, GATE или WINDOW.
  • Свойство LockUnlock при разблокировке.
  • Типаж ArmDisarm при отключении или отмене отключения.
  • Типаж Reboot, SoftwareUpdate или NetworkControl, если тип устройства – NETWORK или ROUTER.

Для свойства TemperatureSetting требуется тип проверки ackNeeded, если тип устройства – AC_UNIT, а интеграция находится в Японии.

Поддерживаемые типы заданий

Поддерживаются следующие типы дополнительной проверки пользователя:

  • Без запроса. Запрос и ответ, в которых не используется дополнительная верификация пользователя.
  • ackNeeded – дополнительная верификация пользователя, которая требует явного подтверждения (да или нет) и может использовать состояния функций в качестве ответа. Этот тип проверки не рекомендуется для устройств и функций безопасности.
  • pinNeeded – дополнительная верификация пользователя, для которой требуется PIN-код. Идеально подходит для устройств и функций безопасности.

Нет соревнований

В этом примере показан успешный запрос EXECUTE и ответ без проверки для включения света.

Пользователь Включи свет.
Google Assistant Хорошо, включаю три светильника.
Запрос
{
  "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
          }
        }]
      }]
    }
  }]
}
Ответ
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Дополнительная аутентификация пользователя, которая может использовать несколько состояний для признака или простую аутентификацию.

Существуют следующие типы проверок ackNeeded:

ackNeeded simple

В этом примере показаны простой запрос и ответ с проверкой ackNeeded на приглушение света и подтверждение приглушения света.

Пользователь Приглуши свет в гостиной.
Google Assistant Уменьшаю яркость света в гостиной. Вы уверены?
Пользователь Да.
Google Assistant Уменьшаю яркость света в гостиной.
Запрос 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
          }
        }]
      }]
    }
  }]
}
Ответ 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Запрос 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
          }
        }]
      }]
    }
  }]
}
Ответ 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded с состояниями признаков

Дополнительная аутентификация пользователя, которая может использовать состояния для типажа. Например, если вы работаете с типажом TemperatureSetting и заданы оба параметра thermostatMode и thermostatTemperatureSetpoint, Assistant может спросить: Вы уверены, что хотите установить температуру кондиционера на 28 градусов?

Вы также можете включить в ответ состояние, чтобы Assistant выполнил определенное действие на основе заданного запроса.

Следующие характеристики и состояния поддерживают ackNeeded с состояниями характеристик. Если в списке указана определенная характеристика, значит поддерживаются все ее состояния.

  • ArmDisarm
    • Для постановки на охрану и отмены этого действия используйте тип проверки ackNeeded, а для снятия с охраны и отмены этого действия – тип проверки pinNeeded.
  • Fill
  • LockUnlock
    • Используйте тип проверки ackNeeded для блокировки устройства и тип проверки pinNeeded для разблокировки.
  • OnOff
    • on
    • Для этого свойства используйте тип задачи ackNeeded. При использовании этого типажа с устройствами CAMERA требуется тип проверки pinNeeded.
  • OpenClose
    • Для этого свойства используйте тип задачи ackNeeded. Тип проверки pinNeeded требуется, когда этот типаж используется с устройствами DOOR, GARAGE, GATE или WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

В этом примере показаны запрос и ответ с проверкой ackNeeded, в которой используется состояние свойства. Он переключает кондиционер в режим обогрева и устанавливает температуру 28 градусов. Затем Assistant просит пользователя подтвердить, что нужно включить обогрев и установить температуру 28 градусов, поскольку в ответе возвращается thermostatTemperatureSetpoint со значением 28.

Пользователь Включи на кондиционере режим обогрева.
Google Assistant Вы уверены, что хотите установить температуру кондиционера на 28 градусов?
Пользователь Да.
Google Assistant Устанавливаю на кондиционере температуру обогрева 28 градусов.
Запрос 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"
          }
        }]
      }]
    }
  }]
}
Ответ 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Запрос 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
          }
        }]
      }]
    }
  }]
}
Ответ 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

Для устройств безопасности рекомендуется использовать проверку pinNeeded.

В этом примере показаны первоначальный запрос и ответ с проверкой pinNeeded. В примере возвращается ответ с запросом pinNeeded, поэтому Assistant запрашивает PIN-код. В этот момент пользователь может ввести неправильный или правильный PIN-код.

Пример запроса и ответа для неверного или действительного PIN-кода:

Пользователь Отпереть дверь.
Google Assistant Назовите защитный код.
Запрос
{
  "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
          }
        }]
      }]
    }
  }]
}
Ответ
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Неверный PIN-код

В этом примере показаны запрос и ответ с проверкой challengeFailedPinNeeded. Этот запрос следует использовать после того, как первоначальный запрос pinNeeded не был выполнен.

Если возвращается тип challengeFailedPinNeeded, Assistant снова запрашивает код безопасности. Если пользователь совершает слишком много неудачных попыток, вы можете вернуть ответ с ошибкой tooManyFailedAttempts. Подробнее об ответах об ошибках…

Пользователь 333222
Google Assistant Неверный код безопасности. Назовите защитный код.
Запрос
{
  "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"
          }
        }]
      }]
    }
  }]
}
Ответ
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Действительный PIN-код

В этом примере показаны запрос и ответ для действительного PIN-кода.

Пользователь 333444
Google Assistant Отпираю дверь.
Запрос
{
  "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"
          }
        }]
      }]
    }
  }]
}
Ответ
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Пользователь Приглуши свет в гостиной.
Google Assistant Назовите защитный код.
Запрос
{
  "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
          }
        }]
      }]
    }
  }]
}
Ответ
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Ответы при ошибках

Ниже приведены некоторые коды ошибок, которые могут возвращаться в ответах.

  • tooManyFailedAttempts – Слишком много неудачных попыток. Чтобы выполнить это действие, перейдите в приложение на устройстве.
  • pinIncorrect – Неверный защитный код.
  • userCancelled – Ok

Ознакомьтесь с полным списком ошибок и исключений.