Отправка и получение API сообщений, типы запросов

Отправка API запросов к плагину и получение ответных сообщений. Типы поддерживаемых сообщений и передаваемых параметров. Способы передачи API сообщений.

Внимание, API доступно только начиная с версии 0.1800. Сейчас идет активная разработка, поэтому обновляйтесь до последней версии чтобы использовать все методы и возможности.

В некоторых случаях от плагина требуется особое поведение, которое невозможно заранее предугадать и запрограммировать разработчиками. Для этих случаев мы разработали и продолжаем разрабатывать API при помощи которого вы сможете решать только нужную вам капчу, выставлять селекторы для решения капч-картинок и многое другое.

Отправка сообщения плагину

Обратиться к плагину можно при помощи отправки сообщения методом window.postMessage. Этот метод обычно предназначен для междоменного общения между Window объектами. Сообщения отправляются всем слушателям в одностороннем порядке без подтверждения получения, без callback или чего-либо подобного.

В качестве примера приведем код обращения к API плагина AntiCaptcha с целью старта разгадывания рекапчи и разберем его на составляющие:

window.postMessage( { receiver: 'antiCaptchaPlugin', type: 'solveRecaptcha', containerSelector: '.g-recaptcha' }, window.location.href );

Линии со 2 по 6 содержат тело сообщения, мы к нему еще вернемся. Линия 7 указывает на домен получателя сообщения, тут всегда указывается текущий адрес.

Тело сообщения состоит из объекта, который содержит обязательные и опциональные поля. Поле receiver всегда имеет значение равное строке antiCaptchaPlugin, при помощи него плагин понимает, что сообщение адресуется именно ему, а не кому-либо другому.

Поле type определяет тип сообщения, иначе говоря, действие, которое необходимо совершить. В данном примере мы просим плагин решить рекапчу, контейнер которой представлен на веб странице в HTML объекте с классом g-recaptcha. Селектор с указанием этого контейнера мы передаем в последнем поле containerSelector.

Получение ответных сообщений от плагина

Вы можете подписаться на ответные сообщения от плагина. Обычно это ответ на последнее обращение к API. Эти сообщения в поле data содержат указание отправителя в поле sender, которое всегда равно строке antiCaptchaPlugin, а так же type — тип последнего API запроса на который пришел ответ.

status — статус последнего запроса. Возможные значения ok — запрос прошел успешно, error — произошла ошибка.
errorId — id ошибки, равен нулю если все впорядке.
errorText — Текстовое краткое описание ошибки, всегда соответствует коду.
messageText — обычно подробное описание произошедшей операции или ошибки.

Следующий блок кода показывает как можно подписаться на прием этих сообщений.

window.addEventListener('message', function (event) { if (typeof event.data.sender === 'undefined' || event.data.sender != 'antiCaptchaPlugin') { return; } // event.data contains all the data that were passed console.log(event.data); // { // sender: "antiCaptchaPlugin" // type: "solveRecaptcha" // status: "ok" // errorId: 0 // errorText: "" // messageText: "" // } });

Чуть разберем этот блок. Строки 2-4 — проверка отправителя сообщений, дабы исключить получение посторонних сообщений.

Строки 8-15 содержат пример нормального ответа от плагина на предыдущий пример API запроса с целью решения рекапчи (type == solveRecaptcha). Он означает, что селектор прошел проверку и рекапча, если будет найдена в этом контейнере, начнет решаться.

Поддерживаемые типы сообщений type

solveRecaptcha

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

Этот метод подходит когда нужно решать только определенную рекапчу, а не все автоматически найденные на странице. Необходимо выключить режим авторазгадывания всех найденных reCAPTCHA 2 (в настройках плагина) и в параметрах API запроса передавать селектор containerSelector (строка) HTML элемента-контейнера, содержащего рекапчу. Обычно это элемент с классом g-recaptcha.

Пример тела сообщения:

{ receiver: 'antiCaptchaPlugin', type: 'solveRecaptcha', containerSelector: '.g-recaptcha' }

solveFuncaptcha

Аналогично Рекапче дает возможность указать HTML элемент-контейнер с Фанкапчей для решения.

Когда надо решить только определенную фанкапчу на какой-либо странице. Имеет смысл выключить опцию Разгадывать Funcaptcha автоматически. В containerSelector (строка) передается контейнер фанкапчи, обычно это #funcaptcha, но подойдет и любой предок в дереве элементов повыше — плагин сам найдет фанкапчу в нем.

Пример тела сообщения:

{ receiver: 'antiCaptchaPlugin', type: 'solveFuncaptcha', containerSelector: '#funcaptcha' }

setImageCaptchaSelectors

Отметить каптчу-картинку и поле ввода при помощи селектора для целевого домена.

Избавляет от необходимости вручную помечать изображение как капчу, а так же поле ввода в качестве получателя для конкретного домена.

Передаваемые параметры:

imageSelector (строка) — селектор для нахождения картинки, которая будет восприниматься в качестве каптчи. Для отмены селектора стоит передать значение null.

inputSelector (строка) — аналогично, селектор для нахождения поля ввода, которое будет получать решение каптчи. Обязательный параметр. Для отмены передать значение null.

Один из двух селекторов imageSelector или inputSelector или оба обязаны быть переданы.

domain (строка) — домен, для которого будут применены вышеуказанные селекторы. Не обязательный параметр, если не передавать, то будет использоваться текущий домен, на котором произошел вызов API.

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

Пример тела сообщения:

{ receiver: 'antiCaptchaPlugin', type: 'setImageCaptchaSelectors', // для страницы https://antcpt.com/rus/information/demo-form/image.html imageSelector: '#htest_image', inputSelector: '#vericode', domain: 'antcpt.com', saveInStorage: true }

setOptions

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

Передаваемые параметры:

options (object) — объект, содержащий параметры, которые необходимо установить. К параметрам относятся:

  • enable (boolean, default true) — Включить/Выключить плагин AntiCaptcha
  • antiCaptchaApiKey (string, default <empty>) — ваш anti-captcha.com API ключ аккаунта

  • autoSubmitForm (boolean, default false) — Автоотправка формы после разгадывания
  • playSounds (boolean, default false) — Включить/выключить звуковой режим

  • useRecaptchaPrecaching (boolean, default false) — Включить / выключить фукнцию предварительного кеширования reCAPTCHA 2
  • kPrecachedSolutionCountMin (integer, default 2) — Число K (precachedSolutionsCountK) мин
  • kPrecachedSolutionCountMax (integer, default 4) — Число K (precachedSolutionsCountK) макс

  • solveRecaptcha2 (boolean, default true) — Включить/выключить авторазгадывание всех найденных reCAPTCHA 2
  • solveInvisibleRecaptcha (boolean, default true) — Включить/выключить авторазгадывание всех невидимых reCAPTCHA
  • dontReuseRecaptchaSolution (boolean, default true) — Не использовать повторно предыдущее решение reCAPTCHA 2 на этой же странице
  • solveOnlyPresentedRecaptcha2 (boolean, default false) — Не решать скрытую на странице reCAPTCHA 2
  • startRecaptcha2SolvingWhenChallengeShown (boolean, default false) — Включить/выключить режим запуска рекапчи только при появлении окна с выбором изображений

  • solveFuncaptcha (boolean, default false) — Включить/выключить авторазгадывание всех найденных Funcaptcha
  • usePredefinedImageCaptchaMarks (boolean, default true) — Включить/выключить автоматический поиск капч-картинок и их решение
  • reenableContextmenu (boolean, default false) — Всегда показывать стандартное контекстное меню (Устарело, удалено)

Пример:

{ receiver: 'antiCaptchaPlugin', type: 'setOptions', options: { antiCaptchaApiKey: '12345678900987654321' } }

Способы передачи API сообщений

Существует несколько мест из которых можно производить передачу API запросов к плагину, мы рассмотрим несколько из них.

Из консоли браузера

Самый очевидный, простой, но не самый удобный способ передачи. Имеется возможность на любой странице браузера открыть консоль (обычно клавиша F12) и вставить вызов метода window.postMessage с параметрами прямо туда и нажать Enter. Плагин подхватит сообщение, обработает его, выполнит необходимое действие и так же разошлет ответ, на который точно таким же способом можно подписаться.

Из любой веб страницы

Можно создать свою веб страницу на любом домене и на ней в JavaScript выполнить все необходимые запросы. Например по помечанию картинки и поля ввода в качестве источника каптчи и получателя решения соответственно. Не забудьте только указать domain, для которого необходимо применить эти селекторы.

Из другого расширения для браузера

Возможна передача сообщений к API при помощи кода, выполняющегося в другом браузерном расширении. Главное чтобы это был Content script, т.е. код, выполняющийся в контексте веб страницы. Например это может быть скрипт, запущенный из собственного расширения, или из User Script расширений вроде Tampermonkey (Chrome) или Greasemonkey (Firefox).

Существуют еще и другие способы обращения к API, но мы сразу все здесь рассматривать не будем, но по мере необходимости будем их добавлять.

Из расширения iMacros

Вы можете использовать конвертер JS кода с вашими API запросами в однострочный iMacros скрипт.