Связка аккаунтов в навыках общего типа

Навыки общего типа поддерживают авторизацию. Через навык пользователи смогут управлять своей учетной записью на стороннем сервисе — например, добавлять встречи в свой календарь, запрашивать баланс счета, оформлять заказы в интернет-магазине.

Чтобы у навыка был доступ к защищенной информации, пользователь должен связать свой аккаунт в Яндексе с аккаунтом на стороннем сервисе.

Связка аккаунтов выглядит следующим образом. Пользователь запрашивает какую-то информацию, требующую авторизации (например, баланс). В ответ навык присылает карточку авторизации — сообщение о необходимости авторизоваться. Когда пользователь нажимает на карточку, запускается процесс связки аккаунтов.

При нажатии на кнопку Авторизоваться навык перенаправляет пользователя на страницу авторизации. Подробнее см. в разделе Как устроен процесс авторизации в навыке.

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

Примечание. Если вам не нужна аутентификация пользователя, а требуется только сохранять данные о пользователе между сессиями — используйте свойство session.user_id. Диалоги присылают этот идентификатор в каждом запросе. Подробнее см. в разделе Формат запроса.

В какой момент запрашивать авторизацию

Для некоторых навыков авторизация может потребоваться сразу — при запуске навыка. Например, в навыке онлайн-банка. Чтобы пользователь смог открыть навык и получить доступ к своему личному кабинету, ему необходимо сначала авторизоваться. До тех пор пока пользователь не авторизуется в навыке, он не сможет взаимодействовать с этим навыком.

Другие навыки могут запрашивать авторизацию по необходимости, по ходу общения с пользователем. Например, пользователь может общаться с навыком сотового оператора «PhonOn» — узнавать про акции, тарифы, адреса отделений. Как только пользователь запросит конфиденциальную информацию, навык должен ответить карточкой с просьбой авторизоваться.

Прежде чем показывать карточку авторизации, навык должен проверить, авторизован ли пользователь.

Как проверить, авторизован ли пользователь

Прежде чем ответить карточкой авторизации, необходимо убедиться, что пользователь еще не авторизован. Для этого проверьте наличие заголовка Authorization в запросе, который пришел от Диалогов.

Authorization: Bearer <access_token>
Если запрос содержит токен, пользователь авторизован. Однако, прежде чем отдавать по токену защищенные ресурсы, следует проверить валидность токена.

Если токен отсутствует или он некорректен, навык должен попросить пользователя авторизоваться — показать карточку авторизации.

Как показать карточку авторизации

Чтобы показать карточку авторизации, ответ навыка должен содержать поле start_account_linking:
{
  "start_account_linking": {},
  "session": {
    "message_id": 4,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
  },
  "version": 1.0
}
Внимание. Когда навык отвечает карточкой авторизации, поле response должно отсутствовать. При одновременном указании полей start_account_linking и response, ответ будет считаться некорректным. Алиса сообщит пользователю, что навык не отвечает.

Когда Диалоги получат от навыка команду start_account_linking, Алиса попросит пользователя авторизоваться — в окне навыка будет отображаться кнопка Авторизоваться. Когда пользователь нажмет кнопку, он будет перенаправлен на страницу авторизации. Подробнее см. в разделе Как устроен процесс авторизации в навыке.

Работа навыка после завершения авторизации

Когда пользователь авторизуется, Диалоги пришлют навыку запрос с полем account_linking_complete_event:

{
  "account_linking_complete_event": {},
  "session": {
    "new": false,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
  },
  "version": "1.0"
}
В заголовке Authorization будет содержаться токен:
Authorization: Bearer <access_token>
Токен нужно проверить и только после этого показывать пользователю конфиденциальную информацию. Ответ, который будет показываться пользователю, следует разместить в поле response:
{
  "response": {
    "text": "Вы успешно авторизовались. Ваш баланс 20 рублей.",
    "tts": "Вы успешно авторизовались. Ваш баланс 20 рублей." 
  },
  "session": {
    "new": false,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "1ds51567-f5rd-4079-a14b-138632932443",
    "user_id": "AW9ZC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DA"
  },
  "version": "1.0"
}

После этого навык должен продолжать слушать запросы от Диалогов в обычном режиме.

Чтобы пользователю не пришлось повторять свой запрос после завершения авторизации (например, запрос баланса), навык должен возвращать запрашиваемую информацию сразу — в ответе на запрос с полем account_linking_complete_event.

Обратите внимание, после завершения авторизации Диалоги не присылают поле request.command с репликой пользователя. Чтобы реализовать «бесшовную авторизацию», вам следует сохранить запрос пользователя перед тем, как запускать связку аккаунтов.

Примечание. Если связка аккаунтов произошла на одной поверхности, то все последующие запросы с других поверхностей будут приходить с токеном (в случае если на этой поверхности пользователь залогинен под аккаунтом на Яндексе). В повторной связке аккаунтов в этом случае нет необходимости.

Проверка валидности токена

Когда навык получает запрос с токеном, необходимо проверить валидность этого токена. Убедитесь, что:
  • Токен представляет действительного пользователя на сервере ресурсов.
  • Для токена разрешены права на выполнение запрашиваемой операции.
  • Срок действия токена не истек.

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

Что делать, если токен недействителен

Токен может быть недействительным по следующим причинам:
  • Пользователь удалил или изменил параметры своей учетной записи в вашем сервисе. Например, пользователь связал навык со своей учетной записью в «PhonOn», а затем удалил эту учетную запись или сменил ее пароль. Токен, сохраненный Диалогами, будет идентифицировать несуществующего пользователя.
  • Срок действия токена истек, но по каким-то причинам Диалогам не удалось получить новый токен. Например, если при обновлении токена сервер авторизации не ответил вовремя (при использовании refresh-токенов).

Если токен оказался недействительным, ваш навык должен ответить пользователю карточкой авторизации. При необходимости, вы можете объяснить пользователю, почему требуется повторная авторизация.