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

Дополнительная верификация пользователя позволяет добавить второй фактор защиты для голосовых команд. Это позволяет повысить безопасность при выполнении определенных действий, например при отключении камеры видеонаблюдения или открытии двери. Дополнительная верификация пользователя не связана с определенным свойством устройства, поэтому вы можете сами решать, когда 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

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