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
Main Methods
Additional Methods
JavaScript SDK Readiness Callbacks

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:

onAfterAppear – called before the appearance of the Lead Hunter form;
onAfterSubmit – called before submitting the Lead Hunter form;
onBeforeAppear – called after the appearance of the Lead Hunter form;
onBeforeSubmit – called after submitting the Lead Hunter form;
window.registerOnCalltrackingPhoneReceivedCallback – called after replacement phone numbers are received from the server;
window.roistat.registerOnVisitProcessedCallback – called when working with visits (getSource(), getVisit(), setRoistatParams() methods).

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
};