JavaScript SDK Settings

Introduction

The JavaScript SDK, called uDash, allows to specify multiple options in its uDash.init method to control its behaviour, most importantly:

• what data is being tracked,
• how often the data is sent to servers,
• how Triggers work.

You can set different options for different pages to which you add the tracking code.

Specifying Settings

The options object is passed as a parameter to the uDash.init method which is executed in the tracking code. By default, it contains just obligatory parameters identifying your project.

uDash.init({ 
   uProjectName: 'my-project',
   uProjectApiPass: 'ec4cfa1ff9680d8fafb546ea54ef8cf2',
   uPort: 12345
});

To set an option, list of which you can find below, add them in the object, for example:

uDash.init({ 
   uProjectName: 'my-project',
   uProjectApiPass: 'ec4cfa1ff9680d8fafb546ea54ef8cf2',
   uPort: 12345,
   uRecordInteractiveEvents: false
});

Options Related to Tracking of Visits

• uCrossSiteSessionsEnabled — optional, type: Boolean, default: true
  If enabled, the tracking code will store information about current session in window.name. The information stored in window.name is persistent even if a user navigates between different domains (www.domain.com, domain.com, my.domain.com), protocols (http and https) or websites (mywebsite.com, yourwebsite.net). This feature allows to continue user’s session without the need of passing custom session IDs.
• uForceTracking – optional, type: Boolean, default: false If enabled, forces the tracking of a session from that moment onwards, even if the session was outside of the tracking sample (if other than 100%).

Options Related to Tracking of (M) Section events

• uIncludeHostnameInSection — optional, type: Boolean, default: false
  If enabled, (M) Section events values tracked based on URL include value of window.location.hostname
• uRecordHashChange — optional, type: Boolean, default: true
  If enabled, (M) Section events are tracked every time hash in URL changes and the hash value is added at the end of a section value, for example Section=contact#thank-you
• uRecordParamsChange — optional, type: Boolean, default: false
  If enabled, the search param value is added at the end of (M) Section event value, for example Section=Home?utm_source=google.com
• uRecordUrlChange — optional, type: Boolean, default: true
  If enabled, (M) Section event values tracked based on URL address contain window.location.pathname.

Options Related to Tracking of (M) Action events

• uRecordFormSubmit — optional, type: Boolean, default: true
  If enabled, (M) Action event is tracked every time a form is submitted using standard “action” method. Form submissions using AJAX that prevent default form behaviour are not tracked.

Options Related to Tracking of (E) Interactive Events

• uRecordInteractiveEvents — optional, type: Boolean, default: true
  When the value is true, uDash automatically records interactions with HTML elements on a page as (E) interactive events. When it is false, it records only (M) meta events and (A) attributes.
• uIgnoreEvents — optional, type: Object, default: {}, allowed object keys: mouseover, mousedown, mouseup, click, touchstart, touchmove, touchend, usage: uIgnoreEvents:{"mouseover":true}
  Disables tracking of specified types of events as (E) interactive events.
• uIgnoreClassNamesWithPrefix — optional, type: Array:String, default: undefined
  (E) Interactive events are formed based on tag names, ids and classnames of elements that users are interacting with. By specifying a list of classname prefixes it is possible to ignore groups of classnames to collect more readable events. Setting the uIgnoreClassNamesWithPrefix value to ["ng-"] would ignore classnames starting with “ng-” which would result in tracking form[3]#checkoutForm/fieldset[1]/label.click instead of form[3]#checkoutForm.ng-pristine.ng-valid.ng-valid-maxlength/fieldset[1]/label.click

Options Related to Tracking of Changes to Page Content for Session Replays

• uRecordPageChanges — optional, type: boolean, default: false
  If set to true, changes to document.documentElement will be registered using (E) mutate interactive event together with information which page elements are changed and how. This allows to accurately replay sessions on pages that for some reasons (i.e. due to data anonimisation) can’t be reproduced by replaying user interactions.
• uRecordPageChanges — optional, type: boolean, default: false
  If set to true, changes to document.documentElement that will happen after the first event of the type specified in uRecordPageChangesAfterEvent will be registered using mutate interactive event together with information which page elements are changed and how. This allow to accurately replay sessions on pages that for some reasons (i.e. due to data anonimisation) can’t be reproduced by replaying user interactions. Setting uRecordPageChanges to true can potentially lead to unintended collection of Personally Identifiable Information (PII) or other sensivite data displayed on the page after the first occurence of an event type specified in uRecordPageChangesAfterEvent
• uRecordPageChangesAfterEvent — optional, type: string, default: click
  Type of event which first occurence will enable registration of “mutate” events if uRecordPageChanges is set to true.
• maskTagContentSelectors — optional, type: array of strings, default: [‘[udash-mask-content=”1″]’]
  when a mutate event is tracked together with HTML content, the content of elements matching the provided selectors is masked to prevent collection of Personally Identifiable Information (PII) or other sensivite data. The masking replaces all letters with a letter ‘X’ (or ‘x’) and all digits will be replaced with a digit ‘9’. Other characters will remain intact. For example, a string ‘John28@gmail.com’ would be masked as ‘Xxxx99@xxxx.xxx’.

Options Related to Triggers

• uAllowTriggersInNotRecordedSessions — optional, type: Boolean, default: true
  If disabled, defined responses are triggered only if a visit is being recorded, which may not always be the case if you are tracking only a sample of visits.
• uTriggersEnabled — optional, type: Boolean, default: true
  If set to false, any defined responses will not be triggered.

Options Related to Sending Data to Servers

• uPackageLimit — optional, type: int, default: 40
  The number of records (interactive events, meta events and such) kept on the client side before sending them to the server. The size of each interactive record may vary, depending on the DOM tree structure, but as a rule of thumb 15 records are equal to about 1 kilobyte of data.
• uSendTimeout — optional, default: 5
  The time interval (in seconds) in which records will be sent to the server.
• uEmptySendLimit — optional, type: int, default: 300
  The number of consecutive empty packages sent to UseItBetter servers after which a visit will be terminated due to user’s inactivity

Hooks for Event Handlers

You can specify a function which will be executed when the tracking code completes a certain task just like you specify other settings.

The example below disables automatic tracking of Section events based on URL and instead tracks a custom Section value “Contact Page”.

uDash.init({ 
   uProjectName: 'my-project',
   uProjectApiPass: 'ec4cfa1ff9680d8fafb546ea54ef8cf2',
   uPort: 12345,
   uRecordUrlChange: false,
   onReady: function(){ uDash.saveMeta('Section', 'Contact Page'); }
});

• onReady — optional, type: function, default: undefined
  If specified, the function is called when uDash has finished initialization (attaching event handlers, collecting user information).
• onConnected — optional, type: function, default: undefined
  If specified, the function is called when uDash has successfully connected to UseItBetter servers and visit was accepted for recording.
• onDumpSend — optional, default: undefined
  If specified, the function is called every time the data is successfully sent and success message was returned by the server.
• onTeardown — optional, type: function, default: undefined
  If specified, the function is called when recording of a visit stops. This can happen if uDash cannot establish connection with UseItBetter servers, the server refused to record a visit, or recording was stopped due to user’s inactivity. At that point, unless uDash is running in a Preview Mode, Heat Map mode or uAllowTriggersInNotRecordedSessions is set to false, uDash will attempt to detach its event handlers and flush all temporary data.