# JavaScript API

ВНИМАНИЕ!

Этот документ предназначен для программиста JavaScript.

Объект Web-страница отображается при помощи браузера (chrome), встроенного в приложение KeenVision Player.

Для объекта Web-страница можно задать код на языке JavaScript, который будет добавлен к коду веб-страницы и запустится сразу после ее загрузки.

# Варианты запуска JavaScript

Есть два варианта запуска JavaScript, указанного в объекте веб-страница:

когда страница загружена;
при начале загрузки страницы, для этого первая строка скрипта должна быть такой:

//onPageStartedLoading

Пример скрипта, который запускается при начале загрузки страницы:

//onPageStartedLoading
function runOnDocumentReadyStateIsComplete() {
  if (document.readyState !== 'complete') return;
  /* код который исполняется когда документ готов */
};


function kvm() {
  /* код который исполняется немедленно */

  runOnDocumentReadyStateIsComplete();

  document.onreadystatechange = () => {
    runOnDocumentReadyStateIsComplete();
  };
};
kvm();

# Очередь кликов.

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

API позволяет имитировать клики реальной мышкой по HTML-элементам. В связи с тем, что каждый клик реальной мышкой занимает время, то чтобы не отслеживать время завершения клика, в API имеется очередь кликов, в которую ставятся задания на клики. Ниже перечислены функции для работы с очередью кликов.

# KeenVision.clickPos( x, y, doubleClick = false )

Добавляет в очередь кликов клик по заданным координатам.

Параметры

x - смещение от левого края окна браузера в пикселях. Значение -1 соответствует центру окна по горизонтали.

y - смещение от верхнего края окна браузера в пикселях. Значение -1 соответствует центру окна по вертикали.

doubleClick - true - имитировать двойной клик, параметр отсутствует или false - имитировать одинарный клик

Возвращаемое значение

Отсутствует.

# KeenVision.clickElement( element, doubleClick = false )

Добавляет в очередь кликов клик по середине HTML-элемента.

Параметры

element - HTML-элемент

doubleClick - true - имитировать двойной клик, параметр отсутствует или false - имитировать одинарный клик

Возвращаемое значение

Отсутствует.

# KeenVision.getClickQueueSize()

Возвращает размер очереди кликов.

Параметры

Отсутствуют

Возвращаемое значение

Целое число - количество невыполненных заданий в очереди кликов. Ноль означает, что все клики выполнены.

# Нажатие клавиши в браузере.

# KeenVision.pressKey(keyCode)

Эмулирует нажатие клавиши в браузере.

Параметры

keyCode - целое число, код клавиши

Возвращаемое значение

Отсутствует.

# Состояние сети.

# KeenVision.isNetworkOk()

Возвращает состояние сетевого интерфейса устройства отображения.

Параметры

Отсутствуют

Возвращаемое значение

true - устройство подключено к сети, false - не подключено.

# Режим "Снимок браузера".

# KeenVision.pageReady(refreshIntervalSec)

Применяется в режиме работы объекта веб-страница "Снимок браузера", сообщает приложению KeenVision Player, что веб-страница готова и можно делать снимок браузера.

Параметры

refreshIntervalSec - целое число, время в секундах, через которое заново загрузить веб-страницу, допустимые значения 30 и более. Если этот параметр отсутствует, то используется значение объекта веб-страница "Период обновления"

Чтобы сообщить приложению KeenVision Player, что скриншот браузера нужно делать, не сразу после загрузки страницы, а по вызову KeenVision.pageReady, JavaScript должен вернуть значение "waitPageReady".

Пример использования:

function kvmain() {
  const main = document.getElementsByTagName('sameElement')[0];
  if (!main) return "waitPageReady"; //если какой-то важный элемент не загрузился, то ждем его загрузки

  let btn = document.getElementsByClassName('cookie_accept')[0]; //кнопка принять использование куков
  if (btn && (btn.offsetParent != null)) KeenVision.clickElement(btn); //нажать кнопку если она есть

  setTimeout(function() {KeenVision.pageReady();}, 1000); //подождать 1000мс и сделать снимок браузера

  return "waitPageReady";
}

kvmain();

# KeenVision.setBrowserTTL(ttlSec)

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

Параметры

ttlSec - целое число, время в секундах, время жизни браузера

# KeenVision.setCacheMode(cacheMode);

Задает режим кэширования веб страницы.

Параметры

cacheMode - целое число, режим кэширования.

Допустимые значения:

/**
 * Режим использования кэша по умолчанию. Если тип навигации не накладывает никаких
 * ограничений на поведение, используются кэшированные ресурсы, когда они доступны
 * и не просрочены, в противном случае производится загрузка из сети.
 */
KeenVision.LOAD_DEFAULT = -1;

/**
 * Кэшированные ресурсы используются, когда они доступны и даже просрочены,
 * в противном случае производится загрузка из сети.
 */
KeenVision.LOAD_CACHE_ELSE_NETWORK = 1;

/**
 * Всегда производится загрузка из сети
 */
KeenVision.LOAD_NO_CACHE = 2;

/**
 * Всегда производится загрузка из кэша
 */
KeenVision.LOAD_CACHE_ONLY = 3;

# KeenVision.getCacheMode();

Параметры

возвращаемое значение - целое число, режим кэширования.

# KeenVision.saveData(dataObject)

Позволяет сохранить объект с данными, чтобы использовать его при последующем показе веб-страницы

Параметры

dataObject - Object, сохраняемый объект.

# KeenVision.loadData(defaultDataObject)

Возвращает сохраненный объект с данными.

Параметры

defaultDataObject - Object, значение по умолчанию, если метод KeenVision.saveData не использовался ранее.

# KeenVision.addUrlFilter(regex, mimeType, disableLoad)

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

Параметры

regex - string, регулярное выражение фильтра, который применяется для url ресурса;

mimeType - string, mime тип ресурса;

disableLoad - boolean, true - не загружать ресурс, false - загрузить ресурс.

Если загрузка ресурса запрещена, то вместо текстовых ресурсов будет загружена пустая строка, а вместо картинок пустой gif. Поэтому для картинок указывайте mimeType : "image/gif".

Учтите, что в регулярных выражениях символ "." является специальным, и должен экранироваться символом "\", а в строке javascript символ "\", также является специальным и тоже должен экранироваться. Поэтому в строке регулярного выражения в javascript, последовательности "\\." будет соответствовать символ "."

Пример, который запрещает загрузку:

всех javascript с сайта "xxx.zzz";
всех картинок с любых сайтов, кроме .png с сайта "aaa.bbb".

Код примера:

const stored = KeenVision.loadData({firstStart: true})
if (stored.firstStart) {
  stored.firstStart = false;
  KeenVision.saveData(stored);
//  KeenVision.setCacheMode(KeenVision.LOAD_CACHE_ELSE_NETWORK);
  KeenVision.addUrlFilter(".*xxx\\.zzz.*\\.js", "text/javascript", true);  
  KeenVision.addUrlFilter(".*aaa\\.bbb.*\\.png\\??.*", "image/gif", false);  
  KeenVision.addUrlFilter(".*\\.(jpe?g|png|gif|bmp|svg|webp|tiff?)\\??.*", "image/gif", true);  
}

Полезные JavaScript →