Web Feedback JavaScript API Reference

This page contains the complete API reference for QSI.API, QSI.API.Events, QSI.API.SessionRecording, InterceptAPI, and QSI.config. For usage guides, see Overview and the related guide pages.

Class: API
Class: Events
Class: InterceptAPI
Class: SessionRecordingAPI
Type Aliases
Configuration (QSI.config)

Classes

Class: API

QSI.API

The Website Feedback JavaScript API is provided as a simple, constant interface that allows users to have more control over their intercepts.

Methods

getIntercept
load
run
unload

Properties

Events

• Events: Events – The Events API for tracking user actions.

SessionRecording

• SessionRecording: SessionRecordingAPI

Methods

getIntercept

▸ getIntercept(interceptId: string): Promise<void | InterceptAPI>

Returns a Promise that resolves to an instance of the Intercept API for a specific Intercept. When manually loading intercepts this MUST be called after calling window.QSI.API.load() or the Promise will not resolve. See the documentation for how to use the Intercept API.

Parameters:

Name	Type
`interceptId`	string

Returns: Promise<void | InterceptAPI>

load

▸ load(): Promise<void>

Loads the script tags for any intercepts/zones on the page. This will make a request back to the Site Intercept servers simulating a normal page refresh.

example

 // Loads the Site Intercept code for any defined intercepts or creatives
 window.QSI.API.load();
 // Starts the intercept code evaluation.
 window.QSI.API.run();

Returns: Promise<void>

A Promise that resolves when QSI has finished loading.

run

▸ run(options?): void

Runs all defined intercepts on the page. When manually loading intercepts this MUST be called after loading the page or calling window.QSI.API.load() for the intercept to show.

example

 // Loads the Site Intercept code for any defined intercepts or creatives
 window.QSI.API.load();
 // Starts the intercept code evaluation.
 window.QSI.API.run();

example

 // Starts the intercept code evaluation right after loading the Site Intercept
 // code for any defined intercepts or creatives
 QSI.API.load().then(QSI.API.run);

example

// Starts the intercept code evaluation with a passed-in option, jsExpressionValues, 
// right after loading the Site Intercept code. Example targeting logic that 
// would be satisfied by this could be:
// "If JavaScript Expression siteMetrics.frustrationDetected Equal to true"
// and an embedded data field could be filled with:
// "Type: Value from JavaScript, Name: ActiveMinutes, Value: siteMetrics.activeMinutes"
// Note: jsExpressionValues in run() does NOT populate externalReference. 
var options = {
  "jsExpressionValues": {
    "userId": 123,
    "siteMetrics": {
      "activeMinutes": 1.4,
      "frustrationDetected": true
    }
  }
};
QSI.API.load().then(() => QSI.API.run(options));

Returns: void

unload

▸ unload(): void

Unloads any intercepts on the page. All creatives are removed and the main QSI object is returned to a blank state (cleared of loaded intercepts and request state).

example

 // Removes any currently displaying creatives
 window.QSI.API.unload();
 // Loads the Site Intercept code for any defined intercepts or creatives
 window.QSI.API.load();

Returns: void

Class: Events

QSI.API.Events

Tracking events allows a user to know how many times a client has performed a certain action. Any events being tracked can be passed as embedded data to the intercept target.

An event can be tracked by using the following:

example

 // gets the window._qsie variable or sets it to an array
 window._qsie = window._qsie || [];
 window._qsie.push('eventName');

This will ensure the event is tracked even if QSI.API.Events is not yet defined on the page.

Methods

count

Methods

count

▸ count(name: string): number

Gets the number of times the given event occurred.

example

 // Gets the event count
 var count = window.QSI.API.Events.count('eventName');

Parameters:

Name	Type
`name`	string

Returns: number

Class: InterceptAPI

InterceptAPI

Accessors

id
name

Methods

getEvaluationResult
onClose

Accessors

id

• get id(): string

The ID of the intercept

Returns: string

name

• get name(): string

The name of the intercept

Returns: string

Methods

getEvaluationResult

▸ getEvaluationResult(): EvaluationResult

Allows accessing the intercept evaluation result for a specific intercept. This is useful for understanding whether a given intercept passed the Qualtrics targeting logic.

example

  // Add an onClose handler if the intercept
  QSI.API.getIntercept(intercept_id).then(function(interceptAPI) {
    var evaluationResult = interceptAPI.getEvaluationResult();
    if(evaluationResult.passed) {
      interceptAPI.onClose(function() {
        console.log('intercept closed!')
      });
    } else {
      console.log('intercept did not pass!')
    }
  });

Returns: EvaluationResult

The intercept evaluation result

onClose

▸ onClose(closeFn: () => any): EventCallbackCleanupFn

Registers a callback that that will be triggered when any creative in the intercept is closed.

remarks This callback is currently limited to Info Bar, PopOver, and Web Responsive Dialog creative types. This function can be called multiple times; registered callbacks will be called in the order they were added.

example

  QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
    interceptAPI.onClose(function () {
      console.log('Intercept was closed!');
    });
  });

It is also possible to register multiple onClose callbacks. The callbacks will be executed in the order they are added.

example

  QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
    interceptAPI.onClose(function () {
      console.log('first close handler');
    });
    interceptAPI.onClose(function () {
      console.log('second close handler');
    });
  });

Callbacks can also be removed after they've been added.

  QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
    var removeHandler = interceptAPI.onClose(function () {
      console.log('first close handler');
    });
  });
  // ...later
  // Remove the handler
  removeHandler();

Parameters:

Name	Type	Description
`closeFn`	() => any	The function to run when the intercept is closed

Returns: EventCallbackCleanupFn

a function that can be called to unregister the event handler that was added.

Class: SessionRecordingAPI

QSI.API.SessionRecording

Properties

isStarting

Methods

start
getSessionSync
getSession
stop
pause

Properties

isStarting

• isStarting: boolean

Methods

`start()`

Starts a session recording. This method is ideally used within an end-user consent workflow.

Returns: Promise<string>
- Resolves to a session ID when Qualtrics starts recording.
Throws:
- Error: If the session recording configuration is not found, DXA is not enabled on your zone, or if the session recording is already initializing.
- SampledOutError: If the session is sampled out via the sampling rate. If sampling is disabled try clearing cookies before calling again.
- MismatchSessionInfoCookieError: If there is a mismatch in session info cookies. Try clearing cookies and reloading
- MissingSessionInfoCookieError: If the session info cookie is missing. Try clearing cookies and reloading

Example:

await window.QSI.API.SessionRecording.start();

`getSessionSync()`

Gets the current session recording information synchronously.

Returns: { sessionId: string; playbackUrl: string } | null
- An object with sessionId and playbackUrl if session recording is initialized, or null if not.

Example:

const session = window.QSI.API.SessionRecording.getSessionSync();
if (session) {
  console.log(session.sessionId, session.playbackUrl);
} else {
  console.log('Session not initialized yet');
}

`getSession()`

Gets the current Session Recording information including the playback URL and session ID. If the session is already initialized, returns immediately. Otherwise, waits for the session to start. Note: this promise is not guaranteed to ever resolve. This is because the timing of when the session starts may not be deterministic (e.g since the start() API can be called by the webpage at any time)

Returns: Promise<{ sessionId: string; playbackUrl: string }>
- A Promise that resolves to an object containing the sessionId and playbackUrl.

Example:

window.QSI.API.SessionRecording.getSession().then((session) => {
  console.log(session.sessionId, session.playbackUrl);
});

`stop()`

Stops and closes the current session recording.

Returns: Promise<string>
- Resolves to the session ID that was successfully stopped and closed.
Throws:
- Error: If the session recording is not initialized or if there is a network error closing the session.
Example:
```
window.QSI.API.SessionRecording.stop();
```

`pause()`

Pauses the current session recording.

Returns: Promise<string>
- Resolves to the session ID that was successfully paused.
Throws:
- Error: If the session recording is not initialized. Tried pausing a session when none was active.

Example:

window.QSI.API.SessionRecording.pause();

Type Aliases

CreativeType

EvaluationResult

Ƭ EvaluationResult: object

Type declaration:

Name	Type	Description
`creative`?	object	-
`creative.id`	string	Creative ID
`creative.name`	string	Creative Name
`creative.revision`	string	Creative Revision
`creative.type`	CreativeType	Creative Type
`passed`	boolean	Boolean that is set to true if intercept targeting evaluated to true.
`targetType`?	string	-
`targetValue`?	string	-

EventCallbackCleanupFn

Ƭ EventCallbackCleanupFn: () => void

Type declaration:

▸ (): void

Returns: void

Configuration (QSI.config)

Set QSI.config before the Website Feedback deployment code loads. Used for XM Directory integration (External Reference ID, automatic contact creation) and related options.

Property	Type	Description
`externalReference`	string	External Reference ID for the visitor. Matches the Reference ID (ExternalDataReference) in XM Directory. Required for most setups; newer contact resolution rules allow it to be omitted if the resolution rule for the directory or zone uses something else (e.g., email only).

For automatic contact creation, QSI.config can also include:

Property	Type	Description
`firstName`	string	Contact first name
`lastName`	string	Contact last name
`email`	string	Contact email
`phone`	string	Contact phone
`language`	string	Contact language
`contactEmbeddedData`	object	Key-value pairs for contact embedded data (limits apply)

See Connecting with XM Directory for full usage and examples.

Table of Contents​

Classes

Class: API​

Table of contents​

Properties​

Methods​

Properties​

Events​

SessionRecording​

Methods​

getIntercept​

Parameters:​

load​

run​

unload​

Class: Events​

Table of contents​

Methods​

Methods​

count​

Parameters:​

Class: InterceptAPI​

Table of contents​

Accessors​

Methods​

Accessors​

id​

name​

Methods​

getEvaluationResult​

onClose​

Parameters:​

Class: SessionRecordingAPI​

Table of contents​

Properties​

Methods​

Properties​

isStarting​

Methods​

start()​

getSessionSync()​

getSession()​

stop()​

pause()​

Type Aliases​

CreativeType​

EvaluationResult​

Type declaration:​

EventCallbackCleanupFn​

Type declaration:​

Configuration (QSI.config)​

Table of Contents

Class: API

Table of contents

Properties

Methods

Properties

Events

SessionRecording

Methods

getIntercept

Parameters:

load

run

unload

Class: Events

Table of contents

Methods

Methods

count

Parameters:

Class: InterceptAPI

Table of contents

Accessors

Methods

Accessors

id

name

Methods

getEvaluationResult

onClose

Parameters:

Class: SessionRecordingAPI

Table of contents

Properties

Methods

Properties

isStarting

Methods

`start()`

`getSessionSync()`

`getSession()`

`stop()`

`pause()`

Type Aliases

CreativeType

EvaluationResult

Type declaration:

EventCallbackCleanupFn

Type declaration:

Configuration (QSI.config)