How to set up a custom JS API

A custom JavaScript API is a piece of code that allows you to perform additional functions along with the main SessionCam tag.

This article is aimed at developers who are familiar with advanced SessionCam configurations and the custom JS API. If you’re uncertain about any aspect of using custom JS APIs, please contact our support team on support@sessioncam.com for advice before you read on.

sessionCamRecorder.createVirtualPageLoad(path)

For example: sessionCamRecorder.createVirtualPageLoad('virtual/testpage');

Returns: null

Effect: if recording is active a virtual page load is created 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. 

Multiple calls to createVirtualPage produces a stack of these and the last one is removed on each call to closeVirtualPage, reactivating the previous one, until there are none left and the main page is reactivated. 

If closeVirtualPage is called when there’s no current virtual page then it won’t do anything. 

To avoid potential errors (such as where SessionCam is not present) this should be checked using: 

window.sessionCamRecorder.createVirtualPageLoad('newPageUrl').

This would produce and 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.

Make any dom changes that you want to be part of the new page first when using either of the above functions. 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.  

You can do this by taking advantage of jQuery functions as these allow for a callback function, which is run after the jQuery function itself has completed. This can be used to call the SessionCam methods. 

For example, to create a virtual page while a particular message is displayed and then remove it afterwards, you could use something like the following: 

$('#message').show('fast', function() {

if(window.sessionCamRecorder && window.sessionCamRecorder.createVirtualPageLoad)

window.sessionCamRecorder.createVirtualPageLoad('message');

}); 

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

Effects:

  1. 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
  2. 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 the '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