Custom JS API

This article is primarily aimed at developers who are familiar with advanced SessionCam configurations and the Custom JS API. It details the functions that are available within the Custom JS API. If you have any questions around these then please email support@sessioncam.com.

sessionCamRecorder.createVirtualPageLoad(path)

For example:

sessionCamRecorder.createVirtualPageLoad('virtual/testpage');

returns: null

effect: if recording is active creates a virtual page load in the current session.

sessionCamRecorder.closeVirtualPage()

returns: null
effect: closes any current virtual page and continues recording against the previous page. This may be another virtual page (if more than one call to createVirtualPageLoad was previously made) or the previous non-virtual page. Mulitple calls to createVirtualPage produce a stack of these and the last one is removed on each call to closeVirtualPage, reactivating the previous one, until none are left and the main page is reactivated.


If closeVirtualPage is called when there is no current virtual page then it will do nothing.
To avoid potential errors for example where SessionCam is not present this should be checked when using the methods, for example:
window.sessionCamRecorder.createVirtualPageLoad('newPageUrl');
would error if for some reason the tags had not fired correctly and SessionCam was not present.
if(window.sessionCamRecorder && window.sessionCamRecorder.createVirtualPageLoad)
window.sessionCamRecorder.createVirtualPageLoad('newPageUrl');
is safe and will not error under those circumstances as it will do nothing.


When using either of the above functions any dom changes which are to be part of the new page should be made first, and you should ideally check that these have taken effect before making the call, in order to ensure that the html we record for the new page is as you want. One way to do this would be to take advantage of jQuery functions which allow for a callback function to be provided, which is run after the jQuery function itself has completed, and that can be used to call the SessionCam methods.


For example to create a virtual page whilst a particular message is displayed and then remove it afterwards something like the following could be used:


$('#message').show('fast', function() {
if(window.sessionCamRecorder && window.sessionCamRecorder.createVirtualPageLoad)
window.sessionCamRecorder.createVirtualPageLoad('message');
});


and then when the user clicks something to close the message:


$('#message').hide('fast', function() {
if(window.sessionCamRecorder && window.sessionCamRecorder.closeVirtualPage)
window.sessionCamRecorder.closeVirtualPage();
});

 

sessionCamRecorder.getSessionCamUserId()

returns: guid identifying the user across hostnames or blank string if none or null if internal problem

side effects: if a guid is returned then a cookie 'sc.UserId' is created with that value set for 8760 hours (1 year) and the same value will be returned in the future from the same browser for any site if the cookie is not cleared.

 

sessionCamRecorder.sendCustomDataEvent(key,value)

For example:

sessionCamRecorder.sendCustomDataEvent('Message', 'Hello');

returns: null

effect:

  • if recording is in progress generates and sends an event of type CustomDataEvent (code 'tag') using key as the elementId and value as the data
  • if a survey configuration is present for the current page and a survey has popped up either on the current page or a previous page in the same session then sends custom data to the surveys host

either, both or neither of the above can occur as applicable.

 

sessionCamRecorder.sessionId()

returns: current sessionId guid and start time from config, comma separated

For example:

a59a3aee-a5e3-4721-bc2e-1e6706b1c04c,635092107600000000.

side effects: none

 

sessionCamRecorder.registerFields(fieldsSelector, functions)

parameters

  • 'fieldsSelector': jQuery selector for 0 or more fields
  • functions: unlimited number of functions to be called if the value of any of the fields changes

For example:

sessionCamRecorder.registerFields('#myElement', function(jElement) { console.log('Element has changed - value is now ' + jElement.html()); });

returns: null

effect: each time any field selected by the selector passed as 'fieldsSelector' changes then each of 'functions' will be called and passed a single parameter being a sessionCamJQuery object containing all the elements currently matched by 'fieldsSelector'

Note: this function may be called any number of times with different parameters. Each call will be handled as an entirely separate (group of) element(s) to monitor.

 

sessionCamRecorder.getFieldValue(element)

returns: current "value" of element in a manner specific to its type:

  • radio/checkbox return the "value" attribute if checked, blank otherwise
  • other input elements and textarea return the current value
  • select returns the value of options selected (array in the case of multi-selects)
  • all other element types return the innerHTML

For example:

sessionCamRecorder.getFieldValue(document.getElementById('myId'));

side effects: none

 

sessionCamRecorder.registeredFieldsGetValue(jElement)

returns: a string containing the current value (calling getFieldValue, see above, internally) of the elements in jElement which have a current value, comma separated, in a manner specific to the type of each. Note that any blank values are omitted from the list.
For example:

sessionCamRecorder.registeredFieldsGetValue(window.sessionCamJQuery('#myId'));

This can be passed the parameter passed by the recorder to the functions specified in registerFields and it will return the values. For example if the fields were a group of radios it would return the value of which one was selected.

side effects: none