Сценарий взаимодействия для ручной обработки капчи

Ниже описаны сценарии взаимодействия между мобильным приложением на платформе Android и VK ID Captcha SDK, если вы используете ручную обработку с помощью listener-интерфейсов.

Обработка зависит от типа ошибки, которая пришла от API ВКонтакте:

Как установить и подключить VK ID Captcha SDK Android, смотрите в инструкции.

Подробнее о методах и интерфейсах — в справочнике VK ID SDK Android.

Обработка ошибки с кодом 14

Если пользователь в мобильном приложении слишком часто вызывает какое-то событие, API ВКонтакте может вернуть вашему мобильному приложению ошибку капчи с кодом "error_code": 14, сообщением "error_msg": "Captcha needed" и ссылкой для инициализации сессии капчи в поле redirect_uri.

Схема взаимодействия

Схема взаимодействия с VK ID Captcha SDK AndroidСхема взаимодействия с VK ID Captcha SDK Android при обработке ошибки с кодом 14

Порядок взаимодействия

  1. 1.
    Мобильное приложение отправляет запрос к API ВКонтакте.
  2. 2.
    API ВКонтакте возвращает мобильному приложению ошибку капчи с кодом "error_code": 14, сообщением "error_msg": "Captcha needed" и ссылкой для инициализации сессии капчи в поле redirect_uri.
  3. 3.
    Мобильное приложение получает из поля redirect_uri ссылку на инициализацию сессии капчи.
  4. 4.
    Мобильное приложение начинает отслеживать результат прохождения капчи с помощью интерфейса VKCaptchaResultListener.
  5. 5.
    Мобильное приложение отправляет в VK ID Captcha SDK Android запрос на отображение капчи методом VKCaptcha.openCaptcha(domain, redirectUri, listener).
  6. 6.
    VK ID Captcha SDK Android отправляет в Captcha WebView запрос на отображение капчи.
  7. 7.
    Пользователь проходит капчу.
  8. 8.
    API ВКонтакте анализирует действия пользователя. В зависимости от результата возможны варианты:
    • •
      Успешный сценарий: пользователь — человек, прошёл капчу.
      1. 1.
        API ВКонтакте формирует токен успешного прохождения капчи success_token и передаёт его в Captcha WebView.
      2. 2.
        Captcha WebView передаёт success_token в VK ID Captcha SDK Android.
      3. 3.
        VK ID Captcha SDK Android закрывает окно капчи методом VKCaptcha.closeCaptcha().
      4. 4.
        VK ID Captcha SDK Android передаёт success_token в событии onResult() в listener-интерфейсе VKCaptchaResultListener, возвращая VKCaptchaResult.Success(val token: String).
      5. 5.
        Мобильное приложение отправляет API ВКонтакте повторный запрос, в ответ на который вернулась ошибка капчи (шаг 1), с токеном успешного прохождения капчи success_token.
      6. 6.
        API ВКонтакте выполняет запрос.
    • •
      Неуспешный сценарий: пользователь — бот.
      1. 1.
        API ВКонтакте возвращает в Captcha WebView ошибку.
      2. 2.
        В Captcha WebView отображается экран неуспешного прохождения капчи.
      3. 3.
        Пользователь закрывает окно с капчей.
      4. 4.
        VK ID Captcha SDK Android возвращает в мобильное приложение событие VKCaptchaError.Cancelled в listener-интерфейсе VKCaptchaResultListener. Пользователь может пройти капчу ещё раз или обратиться в Поддержку.
    • •
      Неуспешный сценарий: пользователь или бот закрыл окно с капчей.
      1. 1.
        API ВКонтакте возвращает в Captcha WebView ошибку.
      2. 2.
        Captcha WebView уведомляет VK ID Captcha SDK Android о закрытии окна.
      3. 3.
        VK ID Captcha SDK Android возвращает в мобильное приложение событие VKCaptchaError.Cancelled в listener-интерфейсе VKCaptchaResultListener.
    • •
      Неуспешный сценарий: ошибка.
      1. 1.
        API ВКонтакте возвращает в Captcha WebView результат.
      2. 2.
        Captcha WebView уведомляет VK ID Captcha SDK Android об ошибке.
      3. 3.
        VK ID Captcha SDK Android возвращает ошибку VKCaptchaResult.Error(val error: VKCaptchaError?) в listener-интерфейсе VKCaptchaResultListener.
  9. 9.
    Мобильное приложение отображает пользователю результат прохождения капчи.

Обработка заголовков X-Challenge и X-Challenge-Url

В ответ на ваш запрос API ВКонтакте может вернуть вашему мобильному приложению заголовки X-Challenge и X-Challenge-Url.

Схема взаимодействия

Схема взаимодействия с VK ID Captcha SDK AndroidСхема взаимодействия с VK ID Captcha SDK Android при обработке заголовков "X-Challenge" и "X-Challenge-Url"

Порядок взаимодействия

  1. 1.
    Мобильное приложение отправляет запрос к API ВКонтакте.
  2. 2.
    API ВКонтакте возвращает мобильному приложению заголовки X-Challenge и X-Challenge-Url: /challenge.html.
  3. 3.
    Мобильное приложение начинает отслеживать результат прохождения капчи с помощью интерфейса VKCaptchaResultListener.
  4. 4.
    Мобильное приложение отправляет запрос к VK ID Captcha SDK Android методом VKCaptcha.getToken() для получения токена с указанием домена.
  5. 5.
    VK ID Captcha SDK проверяет наличие токена для переданного домена. Дальнейший сценарий зависит от наличия токена:
    • •
      Токен для этого домена уже есть
      1. 1.
        VK ID Captcha SDK Android передаёт токен вашему мобильному приложению.
      2. 2.
        Мобильное приложение добавляет полученный токен в заголовок X-Challenge-Solution.
      3. 3.
        Мобильное приложение отправляет API ВКонтакте повторный запрос, в ответ на который вернулась ошибка (шаг 1), с токеном прохождения капчи.
      4. 4.
        API ВКонтакте выполняет запрос.
    • •
      Токена для этого домена ещё нет
      1. 1.
        VK ID Captcha SDK Android возвращает пустое значение в мобильное приложение.
      2. 2.
        Мобильное приложение отправляет в VK ID Captcha SDK Android запрос на отображение капчи методом VKCaptcha.openCaptcha(domain, challengeUrl, listener). В методе передаётся listener-интерфейс VKChallengeResultListener.
      3. 3.
        VK ID Captcha SDK Android открывает Captcha WebView c URL, полученным от мобильного приложения.
      4. 4.
        Пользователь проходит капчу.
      5. 5.
        API ВКонтакте анализирует действия пользователя. В зависимости от результата возможны варианты:
        • •
          Успешный сценарий: пользователь — человек, прошёл капчу.
          1. 1.
            API ВКонтакте формирует токен успешного прохождения капчи success_token и передаёт его в Captcha WebView.
          2. 2.
            Captcha WebView передаёт success_token в VK ID Captcha SDK Android.
          3. 3.
            VK ID Captcha SDK Android закрывает окно капчи методом VKCaptcha.closeCaptcha().
          4. 4.
            VK ID Captcha SDK Android передаёт success_token в событии VKCaptchaResult.Success(val token: success_token) в listener-интерфейсе VKCaptchaResultListener.
          5. 5.
            Мобильное приложение добавляет токен в заголовок X-Challenge-Solution: <значение_токена>.
          6. 6.
            Мобильное приложение отправляет API ВКонтакте повторный запрос, в ответ на который вернулась ошибка капчи (шаг 1), с токеном успешного прохождения капчи success_token.
          7. 7.
            API ВКонтакте выполняет запрос.
        • •
          Неуспешный сценарий: пользователь — бот.
          1. 1.
            API ВКонтакте возвращает в Captcha WebView ошибку.
          2. 2.
            В Captcha WebView отображается экран неуспешного прохождения капчи. Пользователь закрывает окно с капчей.
          3. 3.
            VK ID Captcha SDK Android возвращает в мобильное приложение событие VKCaptchaError.Cancelled в listener-интерфейсе VKCaptchaResultListener. Пользователь может пройти капчу ещё раз или обратиться в Поддержку.
        • •
          Неуспешный сценарий: пользователь или бот закрыл окно с капчей.
          1. 1.
            API ВКонтакте возвращает в Captcha WebView результат.
          2. 2.
            Captcha WebView уведомляет VK ID Captcha SDK Android о закрытии окна.
          3. 3.
            VK ID Captcha SDK Android возвращает в мобильное приложение событие VKCaptchaError.Cancelled в listener-интерфейсе VKCaptchaResultListener.
        • •
          Неуспешный сценарий: ошибка.
          1. 1.
            API ВКонтакте возвращает в Captcha WebView результат.
          2. 2.
            Captcha WebView уведомляет VK ID Captcha SDK Android об ошибке.
          3. 3.
            VK ID Captcha SDK Android возвращает ошибку VKCaptchaResult.Error(val error: VKCaptchaError?) в listener-интерфейсе VKCaptchaResultListener.
  6. 6.
    Мобильное приложение отображает пользователю результат прохождения капчи.