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

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

В некоторых случаях от плагина требуется особое поведение, которое невозможно заранее предугадать и запрограммировать разработчиками. Для этих случаев мы разработали и продолжаем разрабатывать 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' 
}

solveHcaptcha

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

Имеет смысл выключить опцию Разгадывать hCaptcha автоматически в настройках расширения.

В containerSelector (строка) передается контейнер hCaptcha, обычно это .h-captcha, но подойдет и любой предок в дереве элементов повыше — плагин сам найдет hCaptcha в нем.

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

{ 
    receiver: 'antiCaptchaPlugin',
    type: 'solveHcaptcha',
    containerSelector: '.h-captcha' 
}

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
}

Иногда для селектора требуется экранирование, в случае когда id или class элемента содержит специальные символы, такие как ":", ">", "#" и т.д. Тогда в строке значения параметра надо применить двойное экранирование.

Например, для элемента с id == "loginPage:SiteTemplate" нужно передать следующий селектор.
Обратите внимание, что первый символ # мы не экранируем, т.к. это не часть содержимого id целевого элемента, а директива браузеру искать элемент по идентификатору. "#loginPage\\:SiteTemplate" Подобрать правильный селектор для элемента удобно при помощи Консоли браузера (клавиша F12, закладка Консоль), используя метод document.querySelector.
Например, document.querySelector('#loginPage\\:SiteTemplate')

setOptions

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

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

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

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

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

whereSolveList (array, default []) — Список доменов на которых надо/не надо решать капчу в зависимости от режима (смотри ниже)
whereSolveListIsWhite (boolean, default false) — Режим интерпретации списка доменов. Если false, то список доменов будет считаться черным, если true — белым. В режиме черного списка капчи решаются на НЕ попавших в список доменах. В режиме белого — только на доменах из списка.

solveRecaptcha2 (boolean, default true) — Включить/выключить авторазгадывание всех найденных reCAPTCHA 2
solveInvisibleRecaptcha (boolean, default true) — Включить/выключить авторазгадывание всех невидимых reCAPTCHA
solveRecaptcha3 (boolean, default true) — Включить/выключить авторазгадывание reCAPTCHA 3
recaptcha3Score (integer, default 0.3) — Желаемый reCAPTCHA 3 score
solveFuncaptcha (boolean, default true) — Включить/выключить авторазгадывание всех найденных Funcaptcha
solveGeetest (boolean, default true) — Включить/выключить авторазгадывание всех найденных Geetest
solveHcaptcha (boolean, default true) — Включить/выключить авторазгадывание всех найденных hCaptcha
usePredefinedImageCaptchaMarks (boolean, default true) — Включить/выключить автоматический поиск капч-картинок и их решение

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

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

solveProxyOnTasks (boolean, default false) — Включить/выключить решение ProxyOn тасков
userProxyProtocol (enum, default http, обязателен если solveProxyOnTasks включен) — Тип прокси (http, https, socks4, socks5)
userProxyServer (string, обязателен если solveProxyOnTasks включен) — Адрес сервера прокси, только маска *.*.*.* разрешена
userProxyPort (integer, обязателен если solveProxyOnTasks включен) — Порт прокси
userProxyLogin (string, default empty) — Прокси логин
userProxyPassword (string, default empty) — Прокси пароль

setIncomingWorkersUserAgent (boolean, default true) — Включить/выключить режим установки входящего User-Agent работника для некоторых видов капч (например, Hcaptcha)
runExplicitInvisibleHcaptchaCallbackWhenChallengeShown (boolean, default false) — Включить/выключить режим вызова callback функции только при появлении окна с выбором изображений для явно созданной невидимой Hcaptcha
delayOnreadyCallback (boolean, default false) — Включить/выключить задержку вызова onReady метода
Deprecated: 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 скрипт.