Skip to content

JavaScript SDK Roistat

Using the JavaScript SDK, you can access the objects of the Roistat tracking code installed on your websites, which allows you to manage all its functions. For example, you can receive information about a visit or manage Calltracking, Lead Hunter, Emailtracking, etc.

Please note:

Please read this page carefully before using the JavaScript SDK. If you use it incorrectly, this can cause Roistat to malfunction. If you still have questions, please write to us.

How the JavaScript SDK Works

The Roistat tracking code adds a set of objects and methods to your website. They allow you to manage Roistat functions and provide additional logic of how modules work.

For the JavaScript SDK to work properly, you need to wait for it to load. There are callbacks that are executed when the JS API is ready: window.onRoistatModuleLoaded and window.onRoistatAllModulesLoaded.

When the main module is loaded, the roistat object is added to the page. This object contains a set of methods and variables responsible for the work of the tracking code and other modules.

Main Methods

While loading, the tracking code adds the window.roistat object to the page. This object contains methods and objects for managing all Roistat functions. As all modules are loaded, the corresponding objects will become available in window.roistat.

The table below shows methods and attributes of the window.roistat object.

Method / Attribute Return type Description
authClientByEmail(email) void assign a client's email to a visit to make the chain of visits
authClientById(clientId) void assign a client ID to a visit to make the chain of visits
callTracking object object with Calltracking methods and attributes
disableCallTracking() void disable Calltracking on the page
emailtracking object object with Emailtracking methods and attributes
event.send(eventName,[eventFields]) void sends an event to analytics
geo object object with geographic data of a client
getSource() string get the value of the roistat tag (the source of the visit)
getVisit() string get a visit number
leadHunter object object with Lead Hunter methods and attributes
multiwidget object object with Multiwidget methods and attributes
onlineChat object object with Online Chat methods and attributes
page.params.roistat_param1..5 string object with page parameters
setRoistatParams(param1, param2, param3, param4, param5) void set additional parameters of roistat_param1-5 tags
setVisit(visitId) void set a visit number

authClientByEmail(email)

Assign a client's email to a visit to make the chain of visits.

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

authClientById(cliendId)

Assign a client ID to a specific visit to combine multichannel chains from multiple devices.

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

callTracking

Object with Calltracking methods and attributes.

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

enabled

A flag showing whether Calltracking is enabled on the page.

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

phone

Calltracking replacement phone number.

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

disableCallTracking()

Disable Calltracking on the page.

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

emailtracking

Object with Emailtracking methods and attributes.

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

emails

Object with matches of email addresses to be replaced and replacing addresses.

window.onRoistatAllModulesLoaded = function () {
    console.log("Emails to be replaced: " + JSON.stringify(window.roistat.emailtracking.emails));
};

Example of the returned object:

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

enabled

A flag showing whether Emailtracking is enabled on the page.

window.onRoistatAllModulesLoaded = function () {
  console.log("Emailtracking enabled: " + window.roistat.emailtracking.enabled); 
};

To disable Emailtracking on a page, set the value before the Emailtracking module is loaded:

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

loaded

Flag showing whether replacing email addresses are loaded from the server.

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

refresh()

Refresh replacing email addresses on the page.

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

event.send(eventName,[eventFields])

Send and event to analytics.

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

geo

Object with geographic data of a client. It lets you replace website content depending on visitor's city, region and country.

Method / attribute Return type Description
city string visitor's city
region string visitor's region
country string visitor's country

city

Visitor's city.

window.onRoistatAllModulesLoaded = function () {
    console.log("Visitor's city: " + window.roistat.geo.city);
};

region

Visitor's region.

window.onRoistatAllModulesLoaded = function () {
    console.log("Visitor's region: " + window.roistat.geo.region);
};

country

Visitor's country.

window.onRoistatAllModulesLoaded = function () {
    console.log("Visitor's country: " + window.roistat.geo.country);
};

getSource()

Returns the ad channel of a visit. Returns null if there is no tag.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function() {
        console.log("Visit tag: " + window.roistat.getSource());
    });
};

getVisit()

Returns a visit number.

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function() {
        console.log("Set visit number: " + window.roistat.getVisit());
    });
};

leadHunter

Object with methods and attributes for working with Lead Hunter.

Method / Attribute Return type Description
additionalNotifyEmail string Additional email address for lead notification
form.autoShowTime int The number of seconds after which to automatically show the Lead Hunter form
form.buttonText string Lead Hunter button text
form.contactLabel string Text in the phone number field
form.isNameRequired boolean Flag showing whether the name field is required
form.isNeedExplicitAgreement boolean Flag showing whether the consent to the processing of personal data is required
form.nameLabel string Text in the name field
form.subTitle string Lead Hunter form subtitle
form.thankYouText string Text shown after form submission
form.title string Lead Hunter form title
isEnabled boolean Flag showing whether Lead Hunter is enabled
localization.translateToEnglish() void Function for translating the Lead Hunter form into English
localization.translateToRussian() void Function for translating the Lead Hunter form into Russian
onAfterAppear function() Callback executed before the appearance of the Lead Hunter form
onAfterSubmit function(lead) Callback executed before submitting the Lead Hunter form
onBeforeAppear function() Callback executed after the appearance of the Lead Hunter form
onBeforeSubmit function(lead) Callback executed after submitting the Lead Hunter form

When customizing Lead Hunter texts using the JavaScript SDK, you can use HTML tags. For example, you can add line breaks:

window.roistat.leadHunter.form.subTitle = "First line <br> Second line";

additionalNotifyEmail

Additional email address for lead notification. You have to install it before submitting the Lead Hunter form.

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

form.autoShowTime

The number of seconds after which to automatically show the Lead Hunter form.

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

form.buttonText

Lead Hunter button text.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    window.roistat.leadHunter.form.buttonText = "Button text";
  }
};

form.contactLabel

Text in the phone number field.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    window.roistat.leadHunter.form.contactLabel = "Enter your phone number";
  }
};

form.isNameRequired

Flag showing whether the name field is required.

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

form.isNeedExplicitAgreement

Flag showing whether the consent to the processing of personal data is required.

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

form.nameLabel

Text in the name field.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    window.roistat.leadHunter.form.nameLabel = "Enter your name";
  }
};

form.subTitle

Lead Hunter form subtitle.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    window.roistat.leadHunter.form.subTitle = "Subtitle";
  }
};

form.thankYouText

Text shown after form submission.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    window.roistat.leadHunter.form.thankYouText = "Thank you, we will contact you soon.";
  }
};

form.title

Lead Hunter form title.

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

isEnabled

Flag showing whether Lead Hunter is enabled.

window.onRoistatModuleLoaded = function () {
    window.roistat.leadHunter.isEnabled = false; //disable Lead Hunter on the page
};

localization.translateToEnglish()

Function for translating the Lead Hunter form into English.

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

localization.translateToRussian()

Function for translating the Lead Hunter form into Russian.

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

onAfterAppear

Callback executed before the appearance of the Lead Hunter form.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onAfterAppear = function() {
    console.log("Lead Hunter form is shown to a user");
  }
};

onAfterSubmit

Callback executed before submitting the Lead Hunter form. The lead object is used as an attribute of the function. It contains the methods and attributes of the lead.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onAfterSubmit = function(lead) {
    console.log("Lead Hunter form is submitted");
  }
};

onBeforeAppear

Callback executed after the appearance of the Lead Hunter form.

It takes the eventType parameter, which specifies the event that triggers the appearance of the Lead Hunter form. Possible eventType values: click, auto, exit.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeAppear = function(eventType) {
    console.log("Event that triggers the Lead Hunter form "+eventType);
  }
};

onBeforeSubmit

Callback executed after submitting the Lead Hunter form. The lead object is used as an attribute of the function. It contains the methods and attributes of the lead.

window.onRoistatAllModulesLoaded = function () {
  window.roistat.leadHunter.onBeforeSubmit = function(lead) {
    lead.isNeedCallback = 0; // Don't make a call back 
    lead.callbackPhone = 79999999999 //Manager's number to call

    console.log("Additional fields of the lead: " + lead.fields );
    console.log("Lead name: " + lead.name );
    console.log("Lead phone: " + lead.phone );
  }
};

multiwidget

Object with Multiwidget settings.

Method / attribute Return type Description
fb object object with Facebook Multiwidget button settings
isEnabled boolean flag showing whether Multiwidget is enabled
isVisible boolean flag showing whether the Multiwidget button is visible
telegram object object with Telegram Multiwidget button settings
vk object object with VK Multiwidget button settings

fb

Object with Facebook Multiwidget button settings.

window.onRoistatAllModulesLoaded = function () {
    console.log("Facebook button is enabled: " + window.roistat.multiwidget.fb.isEnabled);
    console.log("Facebook link: " + window.roistat.multiwidget.fb.link);
};

Change the Facebook button link:

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

isEnabled

Flag showing whether Multiwidget is enabled.

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.isEnabled = false; //Disable Multiwidget on a page
};

isVisible

Flag showing whether the Multiwidget button is visible.

window.onRoistatModuleLoaded = function () {
    window.roistat.multiwidget.isVisible = false; //Hide the Multiwidget button on a page
};

When using this flag, you can make the Multiwidget button visible on a page by using the window.roistatMultiwidgetShow() method.

telegram

Object with Telegram Multiwidget button settings.

window.onRoistatAllModulesLoaded = function () {
    console.log("Telegram button is enabled: " + window.roistat.multiwidget.telegram.isEnabled);
    console.log("Telegram link: " + window.roistat.multiwidget.telegram.link);
};

Change the Telegram button link:

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

vk

Object with VK Multiwidget button settings.

window.onRoistatAllModulesLoaded = function () {
    console.log("VK button is enabled: " + window.roistat.multiwidget.vk.isEnabled);
    console.log("VK link: " + window.roistat.multiwidget.vk.link);
};

Change the VK button link:

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

onlineChat

Object with Online Chat methods and attributes.

Method / Attribute Return type Description
isAvailableForCurrentUserAgent boolean flag showing whether Online Chat is available for the current user-agent
isEnabled boolean flag showing whether Online Chat is enabled
localization.translateToEnglish() void translate Online Chat into English
localization.translateToRussian() void translate Online Chat into Russian

isAvailableForCurrentUserAgent

Flag showing whether Online Chat is available for the current user-agent.

window.onRoistatAllModulesLoaded = function () {
    console.log("Online Chat is available: " + window.roistat.onlineChat.isAvailableForCurrentUserAgent);
};

isEnabled

Flag showing whether Online Chat is enabled.

window.onRoistatModuleLoaded = function () {
    window.roistat.onlineChat.isEnabled = false; //Disable Online Chat on a page
};

localization.translateToEnglish()

Translate Online Chat into English.

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

localization.translateToRussian()

Translate Online Chat into Russian.

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

page.params.roistat_param1..5

Attributes that store the values of the roistat_param parameters of the current visit.

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)

Set the additional roistat_param1-5 parameters to use them in your reports later.

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

You can skip any of the parameters using null:

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

Please note:

The changed data will appear in the project when the analytic data is refreshed.

For example, you need to assign three additional parameters to a visit:

  • Day of week: roistat_param1 = monday
  • Client gender: roistat_param2 = female
  • Client age: roistat_param3 = 27

Then the request will look like this:

window.onRoistatAllModulesLoaded = function () {
    window.roistat.registerOnVisitProcessedCallback(function () {
        window.roistat.setRoistatParams(monday, female, 27);
    }); 
};

setVisit(visitId)

Manually set the visit number.

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

Additional methods

Roistat adds a set of methods and attributes to the window object. They allow you to control Roistat functionality on the page.

Method / attribute Return type Description
window.roistat.setCallTrackingManualMode() void switch Calltracking to manual mode
window.roistatCallTrackingRefresh() void requests Calltracking replacement numbers
window.roistatLeadHunterShow() void shows the Lead Hunter form on the page
window.roistatMetrikaCounterId string Yandex.Metrica counter ID which is set in the Roistat integration
window.roistatMultiwidgetShow void shows the Multiwidget button
window.roistatOnlineChatShow() void shows the Online Chat window
window.roistatPromoCodeRefresh() void updates the value of the Roistat promo code in the .roistat-promo element
window.registerOnCalltrackingPhoneReceivedCallback function() callback which is executed after replacement phone numbers are received from the server

window.roistat.setCallTrackingManualMode()

Sets Calltracking to manual mode.

Switches Коллтрекинг в ручной режим. In this mode, phone numbers on the page will not be replaced automatically.

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

window.roistatCallTrackingRefresh()

Requests Calltracking replacement numbers.

window.onRoistatModuleLoaded = function () {
    window.roistat.setCallTrackingManualMode(); //Switch Calltracking to manual mode

    document.getElementById("button").onclick = function() {
        window.roistatCallTrackingRefresh(); //Receive and refresh phone numbers
    };
};

window.roistatLeadHunterShow()

Shows the Lead Hunter form on the page.

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

window.roistatMetrikaCounterId

Yandex.Metrica counter ID which is set in the Roistat integration.

window.onRoistatModuleLoaded = function () {
   console.log("Yandex.Metrica counter ID from the Roistat integration: " + window.roistatMetrikaCounterId);
};

window.roistatMultiwidgetShow

Shows the Multiwidget button.

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

window.roistatOnlineChatShow()

Shows the Online Chat window.

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

window.roistatPromoCodeRefresh()

Updates the value of the Roistat promo code in the .roistat-promo element.

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

window.registerOnCalltrackingPhoneReceivedCallback

Callback which is executed after replacement phone numbers are received from the server.

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

JavaScript SDK Readiness Callbacks

These callbacks are used to execute functions after loading all tracking code modules or the main one.

Callback Description
onRoistatModuleLoaded Callback for working with visits and enabling/disabling additional features
onRoistatAllModulesLoaded Callback for accessing functionality of additional features: Calltracking, Emailtracking, A/B Tests, Events

onRoistatModuleLoaded

It is called after loading the main module, before loading additional modules of the features: Calltracking, Emailtracking, A/B Tests, Events.

Use this callback to manage additional tools. For example, you can disable Calltracking or Emailtracking on the page.

Within this callback, specific actions for features are not available (because they have not loaded yet). Use the window.onRoistatAllModulesLoaded callback to manage additional features.

window.onRoistatModuleLoaded = function () {
    window.roistat.emailtracking.enabled = false; // Disable Emailtracking
    window.roistat.setCallTrackingManualMode(); // Enable manual mode for replacing numbers in Calltracking
};

onRoistatAllModulesLoaded

It is called after feature modules have registered their settings and methods to interact with.

The full functionality of all tracking code features is available in this callback. After loading the modules, features begin to do their job: changing phones and emails, sending and receiving analytics data, loading chats, etc.

Callbacks that are called after onRoistatAllModulesLoaded:

Calling the onRoistatAllModulesLoaded callback does not necessarily mean that the data is fully loaded on the site. For example, the phone number may not be known immediately after the Calltracking module is loaded, since the server has not yet received replacement phone numbers. Once the numbers are received, the registerOnCalltrackingPhoneReceivedCallback callback is executed, and the number is sent to the site.

It is too late to disable or enable the feature at this stage. For this purpose use the window.onRoistatModuleLoaded callback.

window.onRoistatAllModulesLoaded = function () {
   window.roistat.leadHunter.form.autoShowTime = 50; //Show Lead Hunter after 50 seconds
   window.roistatOnlineChatShow(); //Open the chat window
};