Инструкции и API

Веб-расширение grabli.app позволяет написать скрипт для автоматического взаимодействия с любой страницей веб, открытой в браузере. Такой скрипт программируется на языке JavaScript, который повсеместно распространён и используется для написания сценариев взаимодействия пользователя со страницей веб-сайта.

Любой скрипт, выполняемый в веб-расширении может работать как конвейер (pipeline), получая какие-то данные на входе и записывая какие-то данные на выходе. Для таких операций предусмотрены две вкладки "Вводные данные" и "Конечные данные". "Вводные данные" позволяют загрузить файл для работы с его содержимом в скрипте через функции библиотеки веб-расширения. Например, можно загрузить url страниц, которые необходимо обойти, чтобы собрать какую-то информацию или наоборот, разместить данные из файла на необходимой странице. Вкладка "Конечные данные" содержит результаты работы скрипта по сбору данных. Также, через интерфейс расширения можно динамически получать данные "Конечные данные" для работы другого скрипта. Например, можно собрать все новостные ссылки одним скриптом и получать содержимое страниц уже другим.

Существуют два типа скриптов, для выполнения в режиме работы одного пользователя и для выполнения в режиме кампания. Второй режим позволяет использовать динамические параметры, которые указывает рекламодатель при создании кампании. Такие скрипты могут быть собраны в шаблоны, которые могут выполнять операторы. Таким образом можно масштабировать выполнение "потока" скриптов для решения бизнес задач. Для скриптов выполняемых в режиме кампания необходимо запрограммировать два ключевых момента - получение параметра MC.getParam (см.ниже) и отправка статуса MC.sendStatus (см.ниже)

Параметры могут быть двух типов - статические и динамические. Веб-расширение позволяет добавить массив параметров, где каждый объект параметра должен иметь три свойства - name, description, type. Получившийся массив необходимо представить строкой в формате JSON. Например: [{"name": "message", "description": "Текст, который будет вставлен в форму отправки сообщений", "type": "static"}, {"name": "list", "description": "Номера профилей, для которых будут выполнено действие в процессе цикла отправки сообщений", "type": "dynamic"}]

Для удобства и повышения скорости написания скрипта разработчику будет полезно ознакомиться с функциями библиотеки веб-расширения "грабли" (grabli.app)

В процессе выполнения любого скрипта веб-расширения на страницу добавляется переменная MC, которая является единой входной точкой для работы с функциями библиотеки веб-расширения "грабли" (grabli.app).

Ниже, везде где есть параметр _callback действует соглашение, при котором если параметр не предоставлен, то возвращается Promise Для работы с DOM веб-страницы при каждом выполнении любого скрипта происходит загрузка библиотеки jQuery версии 3.5.1. Объект библиотеки доступен в скриптах через переменную _jQuery.

• Для загрузки файла из вкладки "Вводные данные" необходимо использовать функцию MC.loadFile(filename:string [, parseAs:string(json|text)] [, _callback:function]), которая принимает на вход один обязательный параметр filename, который является именем файла, который был загружен на вкладку. Второй аргумент может принимать два значения - json или text. По умолчанию файл будет возвращён в текстовом формате.

• Для сохранения строки на вкладке "Выходные данные" необходимо использовать функцию MC.saveRow(title:string, content:string [, _callback:function])), которая принимает на вход два параметра - название коллекции строк и содержимое текущий строки. Если название коллекции уже используется, то строка будет дописана в эту коллекцию.

• Чтобы получить строки из коллекции, необходимо использовать функцию MC.getRows(title:string, [, number:number] [, count:number] [, _callback:function])) передавая на вход название коллекции, номер строки (number) с начала которой необходимо вернуть определенное количество строк (count).

• Если необходимо очистить всю коллекцию, то необходимо использовать функцию MC.saveRow(title:string, "clean", 1 [, _callback:function])) с параметрами название коллекции для очистки (title) и два других параметра должны быть "clean" и 1.

• Если необходимо получить значение ("name") параметра для текущей кампании, то необходимо использовать функцию MC.getParam(name [, parseAs:string(json|text)] [, callback:function])

• Если необходимо отправить статус для параметра "name" для текущий кампании, то необходимо использовать MC.sendStatus(name, value [, customStatus:string] [, result:string] [, callback:function]), где название (name) и значение (value) являются обязательными параметрами. Вы также можете установить customStatus, result - например, содержание разговора, flag - изменять баланс или нет.

• В общем случае удобно использовать формат MC.saveRow(title:string, content:string [, rewrite:number(0|1)] [, _callback:function])

• Чтобы показать пользователю текст в процессе выполнения скрипта, необходимо использовать MC.console(...args)

• Чтобы очистить все сообщения в консоле пользователя MC.clearConsole() Если скрипт планируется использовать в режиме запуска по расписанию, то необходимо добавить в код console.log("script is ended") для остановки задачи, в противном случае скрипт будет ограничен по времени и получит предупреждение.

Функции помощники

• MC.helpers.getUrl() - возвращает href страницы (string).

• MC.helpers.getHost() - возвращает hostname страницы (string).

• MC.helpers.toHex(input) - возвращает hex формат по input строке (string).

• MC.helpers.isMobile() - возвращает true если запущено на мобильном устройстве.

• MC.helpers.getCookie(name) - возвращает значение по названию куки.

• MC.helpers.loadScript(url, callback) - присоединяет внешний скрипт к текущей странице и запускает callback функцию. Например, можно загрузить библиотеку для работы с GraphQl через cdnjs.

• MC.helpers.generateForm(formDescription, buttonLabel, callback) - строит форму и возвращает значения после отправки. formDescription это массив объектов со свойствами: {type(input|select|checkbox), label: string, name: string, ?options:[(label: string, name: string, value: string)]} свойства "options" применяются только для типа "select". callback возвращает значения всех полей в массиве.

• MC.helpers.packCSV(arr, _delim, _sanitize) - возвращает запакованную csv строку по "arr" (array или object) с "_delim" (разделитель, опционально, по умолчанию ",") и безопасную, если _sanitize равен true (по умолчанию true).

• MC.helpers.unpackCSV(string, _delim) - трансформирует строку в "_delim" (разделитель строка, опционально, по умолчанию ",") в массив.

• MC.helpers.getHeaderCSV(object) - получить имена полей по входящему объекту.

• MC.helpers.filterObject(object, filter) - возвращает объект с полями, которые указаны в filter параметре или устанавливает пустую строку.

• MC.helpers.flatten(object, _allObjects) - возвращает "плоский" объект. Если _allObjects стоит в true, тогда все объекты будут иметь индексированный по глубине путь. Если свойства с глубиной более 1, то будет приведены к строке.