Перейти к содержанию

JS API Roistat

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

Внимание!

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

Описание работы JS API

Счетчик Roistat добавляет на страницу набор объектов и методов, которые позволяют управлять поведением Roistat и добавлять дополнительную логику в работу модулей.

Для правильной работы JS API требуется дождаться его загрузки. Для этого существуют колбэки, которые вызываются по готовности JS API: window.onRoistatModuleLoaded и window.onRoistatAllModulesLoaded

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

Основные методы

При загрузке счетчик добавляет на страницу объект window.roistat. В нём находятся методы и объекты по управлению всей функциональностью Roistat. По мере загрузки всех модулей, в window.roistat будут становиться доступными соответствующие объекты.

В таблице ниже приведены методы и атрибуты объекта window.roistat.

Метод / атрибут Возвращаемый тип Описание
authClientByEmail(email) void присвоить визиту email клиента для объединения цепочки визитов
authClientById(clientId) void присвоить визиту id клиента для объединения цепочки визитов
callTracking object объект с методами и атрибутами коллтрекинга
disableCallTracking() void отключить Коллтрекинг на странице
emailtracking object объект с методами и атрибутами емейлтрекинга
event.send(eventName,[eventFields]) void отправляет событие в аналитику
getSource() string получить значение маркера roistat (источника визита)
getVisit() string получить номер визита
leadHunter object объект с методами и атрибутами ловца лидов
multiwidget object объект с методами и атрибутами мультивиджета
onlineChat object объект с методами и атрибутами онлайн-чата
page.params.roistat_param1..5 string объект с параметрами страницы
setRoistatParams(param1, param2, param3, param4, param5) void установить дополнительные параметры roistat_param1-5
setVisit(visitId) void установить номер визита

authClientByEmail(email)

Присваивает email клиента к текущему визиту, чтобы можно было объединить мультиканальные цепочки.

window.onRoistatModuleLoaded = function () {
    window.roistat.authClientByEmail("test@example.com");
};

authClientById(cliendId)

Присваивает id клиента к конкретному визиту, чтобы можно было объединить мультиканальные цепочки по нескольким устройствам.

window.onRoistatModuleLoaded = function () {
    window.roistat.authClientByEmail("1234567");
};

callTracking

Объект с методами и атрибутами коллтрекинга.

Метод / атрибут Возвращаемый тип Описание
enabled int Флаг, отражающий включен ли коллтрекинг на странице
phone string Подменный номер коллтрекинга

enabled

Флаг, отражающий включен ли коллтрекинг на странице.

window.onRoistatAllModulesLoaded = function () {
   console.log("Calltracking enabled = " + window.roistat.callTracking.enabled);
};

phone

Подменный номер коллтрекинга.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnCalltrackingPhoneReceivedCallback(function () {
         console.log("Calltracking replacement phone recieved: " + window.roistat.callTracking.phone);
    });
};

disableCallTracking()

Отключает работу Коллтрекинга на странице.

window.onRoistatModuleLoaded = function () {
    window.roistat.disableCallTracking();
};

emailtracking

Объект с методами и атрибутами емейлтрекинга.

Метод / атрибут Возвращаемый тип Описание
emails object массив с соответсвиями подменяемых и подменных имейлов
enabled boolean флаг, включен ли емейлтрекинг
loaded boolean флаг, был ли загружены имейлы с серверва
refresh() void обновить подменные имейлы на страницы

emails

Объект с соответсвиями подменяемых и подменных имейлов

window.onRoistatAllModulesLoaded = function () {
    console.log("Емейлы для подмены: " + JSON.stringify(window.roistat.emailtracking.emails));
};

Пример возвращаемого объекта:

{
  "email_to_replace1@mail.com": "email_to_replace_with1@mail.com",
  "email_to_replace2@mail.com": "email_to_replace_with2@mail.com"
}

enabled

Флаг, включен ли емейлтрекинг

window.onRoistatAllModulesLoaded = function () {
  console.log("Емейльтрекинг включен: " + window.roistat.emailtracking.enabled); 
};

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

window.onRoistatModuleLoaded = function() {
  window.roistat.emailtracking.enabled = false;
}

loaded

Флаг, загружены ли подменные емейлы с сервра

window.onRoistatAllModulesLoaded = function () {
  console.log("Емейлы для подмены загружены с сервера: " + window.roistat.emailtracking.loaded); 
};

refresh()

Обновить подменные емейлы на странице

window.onRoistatAllModulesLoaded = function () {
  window.roistat.emailtracking.refresh(); 
};

event.send(eventName,[eventFields])

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

document.getElementById("button").onclick = function() {
    window.roistat.event.send("some_event", {"value": "123"});
};

getSource()

Возвращает рекламный канал визита. Если маркера нет то возвращает null.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function() {
        console.log("Маркер визита: " + window.roistat.getSource());
    });
};

getVisit()

Возращает номер визита.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function() {
        console.log("Установлен номер визита: " + window.roistat.getVisit());
    });
};

leadHunter

Объект с методами и атрибутам для работы с Ловцом лидов.

Метод / атрибут Возвращаемый тип Описание
additionalNotifyEmail string Дополнительный емейл для оповщения о лиде
form.autoShowTime int Количество секунд, через которое нужно автоматически показать форму ловца лидов
form.buttonText string Текст на кнопке ловца лидов
form.contactLabel string Текст в поле с номером телефона
form.isNameRequired boolean Флаг, является ли поле с именем обязательным для заполнения
form.isNeedExplicitAgreement boolean Флаг, является ли согласие на обработку персональных данных обязательным
form.nameLabel string Текст в поле с именем
form.subTitle string Подзаголовок формы ловца лидов
form.thankYouText string Текст после отправки формы
form.title string Заголовок формы ловца лидов
isEnabled boolean флаг, включен ли ловец лидов
localization.translateToEnglish() void функция для перевода формы ловца лидов на английский язык
localization.translateToRussian() void функция для перевода формы ловца лидов на английский язык
onAfterAppear function() коллбэк, который вызывается перед появлением формы ловца лидов
onAfterSubmit function(lead) коллбэк, который вызывается перед отправкой формы ловца лидов
onBeforeAppear function() коллбэк, который вызывается после появления формы ловца лидов
onBeforeSubmit function(lead) коллбэк, который вызывается после отправки формы ловца лидов

additionalNotifyEmail

Дополнительный емейл для оповщения о лиде. Необходимо установить до отправки формы лоцва лидов.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeSubmit = function(lead) {
    window.roistat.leadHunter.additionalNotifyEmail = "myemail@roistat.com";
  }
};

form.autoShowTime

Количество секунд, через которое нужно автоматически показать форму ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.form.autoShowTime = 10; //Показывать ловец лидов через 10 секунд
};

form.buttonText

Текст на кнопке ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.buttonText = "Текст на кнопке";
  }
};

form.contactLabel

Текст в поле с номером телефона

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.contactLabel = "Введите номер телефона";
  }
};

form.isNameRequired

Флаг, является ли поле с именем обязательным для заполнения

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.isNameRequired = true;
  }
};

form.isNeedExplicitAgreement

Флаг, является ли согласие на обработку персональных данных обязательным

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.isNeedExplicitAgreement = true;
  }
};

form.nameLabel

Текст в поле с именем

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.nameLabel = "Введите ваше имя";
  }
};

form.subTitle

Подзаголовок формы ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.subTitle = "Подзаголовок";
  }
};

form.thankYouText

Текст после отправки формы

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.thankYouText = "Спасибо, скоро мы с вами свяжемся";
  }
};

form.title

Заголовок формы ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(lead) {
    window.roistat.leadHunter.form.title = "Заголовок";
  }
};

isEnabled

Флаг, включен ли ловец лидов.

window.onRoistatModuleLoaded = function () {
    window.roistat.leadHunter.isEnabled = false; //отключить ловец лидов на странице
};

localization.translateToEnglish()

Функция для перевода формы ловца лидов на английский язык

window.onRoistatAllModulesLoaded = function () {
    window.roistat.leadHunter.localization.translateToEnglish();
};

localization.translateToRussian()

Функция для перевода формы ловца лидов на английский язык

window.onRoistatAllModulesLoaded = function () {
    window.roistat.leadHunter.localization.translateToEnglish();
};

onAfterAppear

Коллбэк, который вызывается перед появлением формы ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onAfterAppear = function() {
    console.log("Форма ловца лидов показана пользователю");
  }
};

onAfterSubmit

Коллбэк, который вызывается перед отправкой формы ловца лидов. В качестве атрибута функции используется объект lead, в котором находятся методы и атрибуты лида

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onAfterSubmit = function(lead) {
    console.log("Форма ловца лидов отправлена");
  }
};

onBeforeAppear

Кколлбэк, который вызывается после появления формы ловца лидов

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function() {
    console.log("Сейчас будет показана форма ловца лидов");
  }
};

onBeforeSubmit

Коллбэк, который вызывается после отправки формы ловца лидов. В качестве атрибута функции используется объект lead, в котором находятся методы и атрибуты лида

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeSubmit = function(lead) {
    lead.isNeedCallback = 0; // Не совершать обратный звонок
    lead.callbackPhone = 79999999999 //Номер менеджера, куда совершить звонок

    console.log("Дополнительные поля лида: " + lead.fields );
    console.log("Имя лида: " + lead.name );
    console.log("Телефон лида: " + lead.phone );
  }
};

multiwidget

Объект с настройками мультивиджета.

Метод / атрибут Возвращаемый тип Описание
fb object объект с настройками кнопки мультивиджета Facebook
isEnabled boolean флаг включен ли мультивиджет
telegram object объект с настройками кнопки мультивиджета Facebook
vk object объект с настройками кнопки мультивиджета Facebook

fb

Объект с настройками кнопки мультивиджета Facebook.

window.onRoistatAllModulesLoaded = function () {
    console.log("Кнопка FB включена: " + window.roistat.multiwidget.fb.isEnabled);
    console.log("Ссылка FB: " + window.roistat.multiwidget.fb.link);
};

Поменять ссылку кнопки FB:

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.fb.link = "https://newlink.com";
};

isEnabled

Флаг включен ли мультивиджет.

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.isEnabled = false; //Выключить мультивиджет на странице
};

telegram

Объект с настройками кнопки мультивиджета Telegram.

window.onRoistatAllModulesLoaded = function () {
    console.log("Кнопка Telegram включена: " + window.roistat.multiwidget.telegram.isEnabled);
    console.log("Ссылка Telegram: " + window.roistat.multiwidget.telegram.link);
};

Поменять ссылку кнопки Telegram:

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.telegram.link = "https://newlink.com";
};

vk

Объект с настройками кнопки мультивиджета VK.

window.onRoistatAllModulesLoaded = function () {
    console.log("Кнопка VK включена: " + window.roistat.multiwidget.vk.isEnabled);
    console.log("Ссылка VK: " + window.roistat.multiwidget.vk.link);
};

Поменять ссылку кнопки VK:

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.vk.link = "https://newlink.com";
};

onlineChat

Объект с методами и атрибутами Онлайн-чата.

Метод / атрибут Возвращаемый тип Описание
isAvailableForCurrentUserAgent boolean флаг, доступен ли онлайн-чат для текущего user-agent
isEnabled boolean флаг, включен ли онлайн-чат
localization.translateToEnglish() void перевести онлайн-чат на английский язык
localization.translateToRussian() void перевести онлайн-чат на русский язык

isAvailableForCurrentUserAgent

флаг, доступен ли онлайн-чат для текущего user-agent

window.onRoistatAllModulesLoaded = function () {
    console.log("Онлайн чат досутпен: " + window.roistat.onlineChat.isAvailableForCurrentUserAgent);
};

isEnabled

флаг, включен ли онлайн-чат

window.onRoistatModuleLoaded = function () {
    window.roistat.onlineChat.isEnabled = false; //Выключить онлайн-чат на странице
};

localization.translateToEnglish()

перевести онлайн-чат на английский язык

window.onRoistatAllModulesLoaded = function () {
    window.roistat.onlineChat.localization.translateToEnglish();
};

localization.translateToRussian()

перевести онлайн-чат на русский язык

window.onRoistatAllModulesLoaded = function () {
    window.roistat.onlineChat.localization.translateToRussian();
};

page.params.roistat_param1..5

Атрибуты, в которых хранятся значения параметров roistat_param текущего визита

window.onRoistatModuleLoaded = function () {
    console.log("roistat_param1 = " + window.roistat.roistat_param1);
    console.log("roistat_param2 = " + window.roistat.roistat_param2);
    console.log("roistat_param3 = " + window.roistat.roistat_param3);
    console.log("roistat_param4 = " + window.roistat.roistat_param4);
    console.log("roistat_param5 = " + window.roistat.roistat_param5);
};

setRoistatParams(param1, param2, param3, param4, param5)

Установить дополнительные параметры roistat_param1-5, чтобы затем строить отчеты по ним.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function () {
        window.roistat.setRoistatParams(param1, param2, param3, param4, param5);
    }); 
};

Можно пропустить любой из параметров, используя null:

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function () {
        window.roistat.setRoistatParams(param1, param2, null, param4, param5);
    }); 
};

setVisit(visitId)

Вручную задать номер визита.

window.onRoistatModuleLoaded = function () {
    window.roistat.setVisit(123456);
};

Дополнительные методы

Roistat добавляет набор методов и атрибутов в объект window, которые позволяют управлять функциями Roistat на странице.

Метод / атрибут Возвращаемый тип Описание
window.roistat.setCallTrackingManualMode() void перевести коллтрекинг в ручной режим
window.roistatCallTrackingRefresh() void запрашивает номера для подмены коллтрекинга
window.roistatLeadHunterShow() void показывает форму ловца лидов на странице
window.roistatMetrikaCounterId string ID счетчика яндекс метрики, который прописан в интеграции Roistat
window.roistatOnlineChatShow() void показывает окно онлайн-чата
window.roistatPromoCodeRefresh() void обновляет значение промокода Roistat в эелементе .roistat-promo
window.registerOnCalltrackingPhoneReceivedCallback function() коллбэк, который вызывается после того, как от сервера получены телефоны для подмены на странице

window.roistat.setCallTrackingManualMode()

Переключает Коллтрекинг в ручной режим. В этом режиме номера на странице не будут подменяться автоматически.

window.onRoistatModuleLoaded = function () {
    window.roistat.setCallTrackingManualMode();
};

window.roistatCallTrackingRefresh()

Запрашивает номера для подмены коллтрекинга.

window.onRoistatModuleLoaded = function () {
    window.roistat.setCallTrackingManualMode(); //Включаем ручной режим коллтрекинга

    document.getElementById("button").onclick = function() {
        window.roistatCallTrackingRefresh(); //Получаем и обновляем номера
    };
};

window.roistatLeadHunterShow()

Показывает форму ловца лидов на странице.

window.onRoistatAllModulesLoaded = function () {
    document.getElementById("button").onclick = function() {
        window.roistatLeadHunterShow();
    };
};

window.roistatMetrikaCounterId

ID счетчика яндекс метрики, который прописан в интеграции Roistat.

window.onRoistatModuleLoaded = function () {
   console.log("ID cчетчика метрики из интеграции Roistat: " + window.roistatMetrikaCounterId);
};

window.roistatOnlineChatShow()

Показывает окно онлайн-чата

window.onRoistatAllModulesLoaded = function () {
    document.getElementById("button").onclick = function() {
        window.roistatOnlineChatShow();
    };
};

window.roistatPromoCodeRefresh()

Обновляет значение промокода Roistat в эелементе .roistat-promo.

window.onRoistatAllModulesLoaded = function () {
    document.getElementById("button").onclick = function() {
        window.roistatPromoCodeRefresh();
    };
};

window.registerOnCalltrackingPhoneReceivedCallback

Коллбэк, который вызывается после того, как от сервера получены телефоны для подмены на странице.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnCalltrackingPhoneReceivedCallback(function() {
        console.log("Получен номер для подмены: " + window.roistat.callTracking.phone);
    });
};

Колбэки готовности JS API

Колбэки используются для выполнения функций после загрузки основного или всех модулей счетчика

Колбэк Описание
onRoistatModuleLoaded Коллбэк для работы с визитами и включения/выключения дополнительных возможностей
onRoistatAllModulesLoaded Коллбэк для доступа к функциональности дополнительных возможностей - коллтрекинга, емейлтрекинга, аб тестов, событий

onRoistatModuleLoaded

Вызывается после загрузки основного модуля, до загрузки дополнительных модулей фич - коллтрекинга, емейлтрекинга, аб тестов, событий.

Используйте этот коллбэк, чтобы повлиять на поведение дополнительных фичей - например, отключить колтрекинг или емейлтрекинг на странице.

Внутри это коллбэка специфичные дейтсвия для фичей недоступны (т.к. они ещё не загрузились). Для управления возможностями дополнительных фичей используйте коллбэк window.onRoistatAllModulesLoaded.

window.onRoistatModuleLoaded = function () {
    window.roistat.emailtracking.enabled = false; // Отключить emailtracking
    window.roistat.setCallTrackingManualMode(); // Включить ручной режим для подмены номеров коллтрекинга
};

onRoistatAllModulesLoaded

Вызывается после загрузки всех модулей Roistat.

В этом коллбэке доступны все возможности всех фичей счётчика. При этом, отключить или включить фичу на этом этапе уже поздно - для включения/выключения фичей используйте коллбэк window.onRoistatModuleLoaded.

window.onRoistatAllModulesLoaded = function () {
   window.roistat.leadHunter.form.autoShowTime = 50; //Показывать ловец лидов через 50 секунд
   window.roistatOnlineChatShow(); //Открыть окно чата
};