Приложение A. Руководство разработчика

JavaScript API
Использование JavaScript API без подключения дополнительного кода
Персонализация посетителей
Установка целей
Теги и атрибуты посещений
Запись вызовов JavaScript-функций
Полуавтоматическая регистрация пользователей

В «Руководстве разработчика» описываются программные интерфейсы (API) системы WebVisor.

JavaScript API

JavaScript API доступен во время просмотра посетителем сайта страницы, на которую установлен код WebVisor. Для того, чтобы воспользоваться им, проще всего подключить дополнительный код WebVisor API. Дополнительный код доступен по адресу http://jsapi.web-visor.com/visor.js. Можно подключать код непосредственно с этого адреса, можно скопировать файл visor.js на свой сайт и подключать его с локального адреса. В первом случае вам будут автоматически доступны все обновления API, во втором случае скорость загрузки страниц вашего сайта не будет зависеть от качества связи с серверами webvsior.

<!-- Подключение дополнительного кода с сервера WebVisor -->
<script src="http://jsapi.web-visor.com/visor.js" type="text/javascript"></script>

<!-- Подключение дополнительного кода с локального сервера -->
<script src="/visor.js" type="text/javascript"></script> 

Подключив дополнительный код, можно пользоваться функциями JavaScript API, доступными через глобальный объект Visor.

Visor.setGoal(2);                           // установка цели 2
Visor.addTag('foo');                        // установка тега foo
Visor.addField('key', 'value');             // установка поля key в значение value

Функции, доступные в JavaScript API, подробно описаны в следующих разделах.

Использование JavaScript API без подключения дополнительного кода

Для продвинутых пользователей также возможно использование JavaScript API без подключения дополнительного кода. В этом случае объект Visor станет доступен только после загрузки всего кода WebVisor, подключенного к странице, а загрузка кода может произойтие в любое время до или после окончательной загрузки страницы (т.к. код загружается асинхронно). Поэтому перед использованием объекта Visor надо определить, доступен ли он в настоящий момент. Для упрощения кода и уменьшения количества проверок можно определить на странице функцию onVisorReady, которая вызовется сразу после того, как будет загружен код WebVisor и объект Visor станет доступен.

// Использование объекта Visor с проверкой
if (window.Visor) { // Если объект Visor доступен
    Visor.setUserName('vasya');        // страницу просматривает vasya
    Visor.setUserId(42);               // страницу просматривает пользователь с id=42
}

// Использование onVisorReady
function onVisorReady() {
    Visor.setGoal(2);                  // установка цели 2
    Visor.addTag('foo');               // установка тега foo
    Visor.addAttribute('key', 'value');// установка атрибута key в значение value
}

Персонализация посетителей

Если в контекcте JavaScript кода на странице известно имя посетителя, можно отправить эти данные на сервер WebVisor, чтобы это посещение (а также прошлые и будущие посещения этого посетителя) проассоциировалось с этим именем. Можно также проассоциировать с посетителем уникальный идентификатор, по которому можно будет найти этого посетителя или просмотреть его профиль в системе учёта. Для этого используются функции:

setUserName(name)

Ассоциирует посетителя с заданным именем. Ассоциация перманентная: следующие посещения этого же посетителя будут тоже проассоциированы с этим именем.

setUserId(id)

Ассоциирует посетителя с заданным идентификатором. Идентификатор может быть как числовой, так и строковый. Ассоциация тоже перманентная.

<!-- берём имя (логин) посетителя из формы -->
<form id="loginform" onsubmit="Visor.setUserName(this.login.value);" ...> 
   <input name="login" ... >
</form>

<script>
   // берём идентификатор посетителя из PHP-переменной userid
   Visor.setUserId('<?=userid?>');
</script>

Установка целей

WebVisor предоставляет возможность регистрировать достижение цели по выполнению условия или набора условий. Например, считать, что посетитель сайта достиг цели, если он дошел до страницы с формой обратной связи (условие по адресу страницы). Или если провел на сайте более 5 минут (условие по продолжительности посещения). Однако не всегда стандартных условий достаточно для работы с целями. С помощью условий, например, нельзя проверить, кликал ли посетитель на заданном участке страницы, или воспользовался ли определенным элементом интерфейса. Для регистрации таких целей необходимо использовать JavaScript API.

Для регистрации достижения цели используется функция API setGoal(), в которую передаётся номер цели.

Visor.setGoal(1); // Регистрируем достижение цели #1.

Теги и атрибуты посещений

Посещение можно пометить произвольными тегами и/или атрибутами и использовать эту информацию для дальнейшего анализа поведения посетителей. К посещению можно привязать неограниченное количество тегов и атрибутов. Для этого используются функции:

addTag(value)

Помечает посещение тегом со значением value.

addAttribute(name, value)

Привязывает к посещению атрибут с именем name и значением value.

<!-- Помечаем тегом 'price' посещения, где загружали прайс-лист -->
<a href="/price.xls" onclick="Visor.addTag('price');">Загрузить прайс-лист</a>

<!-- Привязываем к посещению номер заказа, взятый из PHP-переменной-->
<script>
    Visor.addAttribute('order', '<?=userid?>');
</script>

Запись вызовов JavaScript-функций

Код WebVisor, установленный на страницах сайта, записывает большинство действий посетителя. Но в некоторых случаях простой записи действий недостаточно: страница может самостоятельно реагировать на действия посетителя и изменять свое состояние. Самый простой пример — выпадающее меню на сайте, работающее при помощи JavaScript. Код меню отслеживает движения мышью над некоторыми областями страницы и в ответ на передвижения отображает те или иные пункты меню. Если воспроизводить посещения на таком сайте в WebVisor, то движения мыши воспроизведутся, а появление пунктов меню — нет, так как WebVisor ничего не знает о появлении меню. Как же записать «нестандартные» действия посетителя, отрабатываемые с использованием JavaScript?

Для записи действий, сопряжённых с выполнением JavaScript-кода, надо вызвать функцию API captureFunctions(). Эта функция принимает на вход названия JavaScript-функций, вызовы которых необходимо записывать. То есть если открытие меню производится с помощью функции openMenu(...), а закрытие — с помощью функции closeMenu(...), то инициализация записи их вызовов будет выглядеть так:

Visor.captureFunctions('openMenu', 'closeMenu');

Естественно, будут записаны только те вызовы функций, которые произошли после вызова captureFunctions().

Аргументы записываемых функций могут быть только следующих типов:

  • Числа.

  • Строки.

  • Даты (объекты Date).

  • Регулярные выражения (объекты RegExp).

  • DOM-элементы.

  • Массивы и объекты, которые могут содержать все вышеперечисленные типы, включая массивы и объекты.

Кроме того, записываемые функции должны быть глобальными (то есть функцию можно вызвать как window.function()).