Skip to main content

Pairing with Session Recording

The QSI.API.SessionRecording API gives you control over when Digital Experience Analytics (DXA) Session Recording starts, stops, and pauses. This is useful for:

  • Consent workflows – Start recording only after the user opts in.
  • Cookie controls – Align recording with your cookie banner or preferences.
  • Fine-tuned control – Pause or resume recording across route changes when you need more control than the default behavior.
  • Passing context to other tools – Get the recording information (such as session ID or replay URL) to pass along to other website logging, error reporting, or analytics tooling you may be using.

Session Recording Methods​

MethodPurpose
QSI.API.SessionRecording.start()Starts a session recording. Returns a Promise that resolves to the session ID.
QSI.API.SessionRecording.getSession()Returns a Promise that resolves to the current session’s sessionId and playbackUrl. If recording is not initialized yet, waits until the session starts (see note below).
QSI.API.SessionRecording.getSessionSync()Returns current session’s sessionId and playbackUrl if session recording is initialized, or null if not.
QSI.API.SessionRecording.stop()Stops and closes the current recording.
QSI.API.SessionRecording.pause()Pauses the current recording.
async function onUserConsents() {
  try {
    const sessionId = await QSI.API.SessionRecording.start();
    console.log('Recording started:', sessionId);
  } catch (error) {
    console.error('Failed to start recording:', error);
  }
}

Stopping and Pausing​

// Stop recording (e.g., when user logs out)
await QSI.API.SessionRecording.stop();

// Pause recording (e.g., when user navigates to a sensitive area)
await QSI.API.SessionRecording.pause();

Reading session ID and playback URL​

Use getSessionSync() when you want to get the current session immediately - for instance, to attach to a log call you're about to make - and are fine if the session may occasionally not be available.

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

Use getSession() when you want to get session information and are able to wait until recording has started (which make take several seconds on initial page load). This is useful if you want to push a dedicated event to other analytics provider's on your page - say, Google or Adobe Analytics - that contains the Qualtrics session ID or replay URL.

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

Warning​

getSession() resolves as soon as the session exists, or after start() completes. If recording never starts (for example, start() is never called or the session is sampled out), the returned Promise may never resolve, because session start timing is not guaranteed.

SPA Navigation and Session Recording​

Session Recording captures SPA navigations out of the box, without API setup. The APIs are for providing fine-tuned control on your website.

When using SPAs with the zone snippet on all routes, Session Recording should work automatically. Recording will pause only if the pause() method is called, or if the user navigates to a page that does not include the zone snippet.

For manual control, use QSI.API.unload() when switching contexts and QSI.API.SessionRecording.pause() or stop() when you need to halt recording.

Error Handling​

SessionRecording.start() can throw:

  • Error – Config not found, DXA not enabled, or recording already initializing.
  • SampledOutError – Session was sampled out. Try clearing cookies if sampling is disabled.
  • MismatchSessionInfoCookieError – Session info mismatch. Clear cookies and reload.
  • MissingSessionInfoCookieError – Session info cookie missing. Clear cookies and reload.

stop() and pause() throw if no recording is active.

getSessionSync() does not throw; it returns null when there is no active session. getSession() does not reject for a missing session—it waits for qsi_session_started—so avoid relying on it without a timeout or without a path where start() (or automatic recording) will run.

See Also​