DXA JavaScript API Guide

In some cases, JavaScript code must be executed after DXA has been fully loaded. This event allows custom code to be executed once this condition has occurred. You can bind one or more callbacks to be executed in the same order they were bound.

Argument

• callback (function): A callback containing any valid JavaScript code

Example

// Log a message in the console once DXA is fully loaded.
function decibelInit() {
    console.log('Decibel loaded!');
}
if (typeof window.decibelInsight !== 'undefined') {
  window.decibelInsight('ready', decibelInit);
} else {
  window._da_readyArray = window._da_readyArray || [];
  window._da_readyArray.push(decibelInit);
}
function decibelInit() {
window.decibelInsight('ready', function(){
console.log('Decibel loaded!'); …

This event will be triggered when the collection status of DXA changes.

Argument

• callback (function): This callback will be passed to the new and old status as parameters. It can contain any valid JavaScript code.

Example

// Log a message in the console whenever Decibel starts collecting data.
decibelInsight('onCollectionChange', function(newStatus, oldStatus) {
  if (newStatus === true) {
    console.log('Decibel is now collecting.');
  }
});

Argument

• callback (function): A callback containing any valid JavaScript code

Example

// Log a message in the console once DXA is fully loaded and the page is collected.
function decibelInit() {
  decibelInsight('onPageCollected', function(){
    console.log('Decibel loaded and page collected!');
  });
}
if (typeof window.decibelInsight !== 'undefined') {
  window.decibelInsight('ready', decibelInit);
} else {
  window._da_readyArray = window._da_readyArray || [];
  window._da_readyArray.push(decibelInit);
}

Argument

• callback (function): A callback containing any valid JavaScript code

Example

// Log a message in the console once DXA is fully loaded and HTML of the current page collected.
function decibelInit() {
  decibelInsight('onHTMLCollected', function(){
    console.log('Decibel loaded and HTML collected!');
  });
}
if (typeof window.decibelInsight !== 'undefined') {
  window.decibelInsight('ready', decibelInit);
} else {
  window._da_readyArray = window._da_readyArray || [];
  window._da_readyArray.push(decibelInit);
}

This function informs DXA of nonstandard form submissions, such as AJAX submission.

Argument

• form (element|string): An HTML form element or CSS selector pointing to a form

Examples

// Trigger submission of a form identified by DOM element.
decibelInsight('formSubmitted', form);

// Trigger submission of a form identified by a CSS selector.
decibelInsight('formSubmitted', '#contact-form');

This function informs DXA of application errors experienced by a visitor.

Arguments

• message (string): The error message shown to the user or, if the second parameter is used, a CSS selector matching one or more elements containing error messages.
• asSelector (boolean): If set to true, the message parameter will be interpreted as a CSS selector and the text of one or more matching elements will be sent as error messages. Defaults to false.

Examples

// Pass a specific application error message to DXA.
decibelInsight('sendApplicationError', 'Selected product is out of stock');

// Pass zero or more application error messages to DXA
// by matching element in the HTML using a CSS selector.
decibelInsight('sendApplicationError', '.errorMessage', true);

This function sets custom information against a visitor, session, or pageview.

Arguments

• dimension (string): Custom dimension name
• value (mixed): New value assigned to the custom dimension. This value will override any value previously set for the custom dimension within its configured scope.

Examples

// Send Custom Dimension data with a fixed value.
decibelInsight('sendCustomDimension', 'loggedIn', true);

// Send Custom Dimension data retrieved from the JavaScript data layer.
decibelInsight('sendCustomDimension', 'customerType', dataLayer.customerType);

This function triggers tracked events. The tracked event value and currency can also be set.

Arguments

• name (string): Tracked event name as configured in DXA
• value (float): Total monetary value for the tracked event (optional)
• currency (string): A three-letter ISO 4217 currency code (optional)
  
  Note: DXA supports the following currencies: USD, EUR, and GBP.

Examples

// Trigger a tracked event with no value attached.
decibelInsight('sendTrackedEvent', 'Add to Basket');

// Trigger a tracked event with a fixed value.
decibelInsight('sendTrackedEvent', 'Checkout', 250.56);

// Trigger a tracked event with a fixed value and currency.
decibelInsight('sendTrackedEvent', 'Checkout', 500, 'GBP');

// Trigger a tracked event with a value retrieved from the JavaScript data layer.
decibelInsight('sendTrackedEvent', 'Checkout', dataLayer.basketValue);

This function informs DXA of HTTP server errors.

Argument

• code (integer): Any valid 4xx or 5xx HTTP status code

Example

// Inform DXA that the current page 
// is a 404 Page Not Found error page.
decibelInsight('sendHTTPError', 404);

Tracks the content of a canvas to ensure accurate reflection in the session replay. This function can be used when a large or heavily animated canvas is present on the page and when automated canvas tracking is not desired.

Argument

• canvas (element|[element]|string): An HTML canvas element, array of elements, or a CSS selector pointing to one or more canvases

Examples

// Track a canvas identified by DOM element.
decibelInsight('trackCanvas', canvas);

// Track a canvas identified by a CSS selector.
decibelInsight('trackCanvas', '#banner-animation');

Websites using JavaScript functionality to change page content without performing a page reload must use the DXA JavaScript API to trigger pageviews.

Arguments

• path (string): Absolute path of the page (optional). If not provided, the path currently displayed in the browser will be used.
• params (object): An object containing one or more properties (optional). Parameters may include any of the following:
  • title: Title of the page. If not provided, the title currently displayed in the browser will be used.
  • queryString: The query string component of the URL (for example, “?page=2”). If not provided, the query string currently displayed in the browser address bar will be used.
  • fragment: The fragment component of the URL (for example, “#/Page/1”). If not provided, the fragment currently displayed in the browser address bar will be used.
  • waitTime: Time in milliseconds it took the page or state to load.

Example

decibelInsight('trackPageView', '/About-Us');
decibelInsight('trackPageView', '/Search', {
    queryString: '?page=1&q=Laptops',
    waitTime: 1000
});

Provides a custom user ID for the current visitor. This is usually an ID generated from a website's login area. It can be used to enable integration of DXA data with existing internal systems, such as CRM.

Argument

• userID (string): This can be any text value up to 100 characters long.

Example

// Assign a customer ID from the JavaScript data layer 
// as the DXA User ID.
decibelInsight('updateUserId', dataLayer.customerId);

Forces DXA to stop collecting any further data for the current session

Example

// Force DXA to end the current session.
decibelInsight('endSession');

Argument

• newVisitor (boolean): Whether to attribute the session to a new visitor profile (optional). If not provided, the new session will be attributed to the same visitor profile as the current session.

Example

// Force DXA to start a session, for a new visitor profile.
decibelInsight('startSession', true);

Argument

• newVisitor (boolean): Whether to attribute the session to a new visitor profile (optional). If not provided, the new session will be attributed to the same visitor profile as the current session.

Example

// Force DXA to end the current session and start a new session.
decibelInsight('restartSession');

Returns the DXA lead ID for the current session

Return

• (string) DXA lead ID

Example

// Add the DXA Lead ID to the JavaScript data layer.
dataLayer.leadId = decibelInsight('getLeadId');

Return

• (string) DXA session ID

Example

// Add the DXA Session ID to the JavaScript data layer.
dataLayer.sessionId = decibelInsight('getSessionId');

Returns

• (boolean) DXA collection status:
  • true if DXA is collecting data
  • false if no data is currently being collected
  • null if DXA is not yet initialized

 Example

// Log a message in the console if DXA is collecting data.
if (decibelInsight('isCollecting')) {
  console.log('DXA is collecting');
});

decibelInsight('setCollection', status, [remember]);

Enables or disables collection of data by DXA.

If the visitor is not being tracked, the visitor will be forced into the collection sample.

If the visitor is being tracked, the visitor will be removed from the sample.

Arguments

• status (boolean): New collection status for the current session.
• remember (boolean): Whether to remember the collection status for the next session (optional). If false, the status will apply for this session only. If true or omitted, the status will apply for this and all future sessions.

 Examples

// Enable collection for the current session 
// and future sessions for the current visitor.
decibelInsight('setCollection', true);

// Disable collection for the current session only.
decibelInsight('setCollection', false, false);

decibelInsight('setRetention');

Enables retention of data by DXA if retention sampling is enabled.

If the visitor is not being tracked, the visitor will be forced into the retention sample.

If retention sampling is not enabled, this function will have no effect.

Example

// Force the current session to be retained by DXA.
decibelInsight('setRetention');

Enables or disables collection of data by DXA.

If the visitor is not being tracked, the visitor will be forced into the collection sample.

If the visitor is being tracked, the visitor will be removed from the sample.

Arguments

• status (boolean): New collection status for the current session.
• remember (boolean): Whether to remember the collection status for the next session (optional). If false, the status will apply for this session only. If true or omitted, the status will apply for this session and all future sessions.

 Examples

// Enable collection for the current session 
// and future sessions for the current visitor.
decibelInsight('selectSessionForExperience', true);

// Disable collection for the current session only.
decibelInsight('selectSessionForExperience', false, false);

Enables or disables collection of replay data by DXA.

If the visitor is not being tracked, the visitor will be forced into the replay collection sample.

If the visitor is being tracked, the visitor will be removed from the sample.

This function will only take effect if the session is in the experience data sample.

Arguments

• status (boolean): New replay collection status for the current session.
• remember (boolean): Whether to remember the replay collection status for the next session (optional). If false, the status will apply for this session only. If true or omitted, the status will apply for this session and all future sessions.

 Examples

// Enable replay collection for the current session 
// and future sessions for the current visitor.
decibelInsight('selectSessionForReplay', true);

// Disable replay collection for the current session only.
decibelInsight('selectSessionForReplay', false, false);

Enables or disables collection of analysis data by DXA.

If the visitor is not being tracked, the visitor will be forced into the analysis collection sample.

If the visitor is being tracked, the visitor will be removed from the sample

This function will only take effect if the session is in the experience data sample.

Arguments

• status (boolean): New analysis collection status for the current session
• remember (boolean): Whether to remember the analysis collection status for the next session (optional). If false, the status will apply for this session only. If true or omitted, the status will apply for this session and all future sessions.

 Examples

// Enable analysis collection for the current session 
// and future sessions for the current visitor.
decibelInsight('selectSessionForAnalysis', true);

// Disable analysis collection for the current session only.
decibelInsight('selectSessionForAnalysis', false, false);

Enables or disables collection of analysis data by DXA.

If the page is not being tracked, the page will be forced into the analysis collection sample.

If the page is being tracked, the visitor will be removed from the sample

This function will only take effect if the session is in the experience data sample.

Argument

status (boolean): New analysis collection status for the current page

 Examples

// Enable analysis collection for the current page 
decibelInsight('selectPageviewForAnalysis', true);

// Disable analysis collection for the current page
decibelInsight('selectPageviewForAnalysis', false);

Argument

• retention (integer): Number of months the favorite will be retained. One of 1, 3, 6, 12 or 24. If omitted, the favorite will be retained indefinitely.

Examples

// Mark the session to be added as a favorite.
decibelInsight('setFavorite');

// Mark the session to be added as a favorite and stored for 3 months.
decibelInsight('setFavorite', 3);

Argument

• delay (integer): The number of milliseconds until recording will be resumed (optional).
  If not provided, recording will be paused until the resumeRecording endpoint is called or the visitor navigates to another page.

Examples

// Pause recording for the remainder of the current
// page view or until resumeRecording is called.
decibelInsight('pauseRecording');

// Pause recording for 500 millseconds.
decibelInsight('pauseRecording', 500);

Example

// Resume recording if it has previously been 
// paused on the current page view.
decibelInsight('resumeRecording');

Argument

• rate (integer): Between 1 and 10 frames per second. The default frame rate is 5.

Example

// Reduce the frame rate to two frames per second.
decibelInsight('setFrameRate', 2);