Skip to main content

Qualtrics Integration

Qualtrics is a comprehensive platform for designing and running behavioral-science studies, from simple questionnaires to complex multi-block experiments. Its built-in JavaScript hooks make it straightforward to integrate external tools — including Chiasm eye tracking — directly into a survey flow.

This tutorial walks you through adding Chiasm to a Qualtrics survey. The entire integration takes just a few steps.

caution

Qualtrics does not support storing eye-tracking data. Gaze predictions must be saved to the Chiasm server by setting saveData to true in setExpInfo. You can then download the data from Chiasm using a private link.

Prerequisites​

  • A Qualtrics account with survey editing access
  • A Chiasm account with an Experiment created (you'll need your Experiment ID and Auth Token)

1. Create a Chiasm setup question block​

The first question block in your survey will load the Chiasm library, calibrate the participant's webcam, and then automatically advance to the rest of the survey.

  1. Add a new Text / Graphic question at the very beginning of your survey.
  2. Click the question text, then click the JavaScript icon (</>) to open the script editor.
  3. Replace the default content with the following code:
Qualtrics.SurveyEngine.addOnload(async function () {
  const qualtricsThis = this;

  const CHIASM_AUTH_TOKEN = "YOUR_AUTH_TOKEN";
  const expId = "YOUR_EXPERIMENT_ID";
  const ppId = Qualtrics.SurveyEngine.getEmbeddedData("ResponseID");

  // Hide all Qualtrics UI while Chiasm calibrates
  document.body.style.margin = "0";
  document.body.style.padding = "0";
  document.body.style.backgroundColor = "black";

  const el = document.querySelector(".SkinInner");
  if (el) el.style.display = "none";

  // Load the Chiasm library (once per session)
  if (!window.chiasmTracker) {
    const script = document.createElement("script");
    script.src = "https://cdn.chiasm.eu/latest/chiasm-tracker.js";
    script.onload = async () => {
      window.chiasmTracker = await initChiasmTracker({
        authToken: CHIASM_AUTH_TOKEN,
      });

      try {
        chiasmTracker.setExpInfo(expId, ppId, true);
        await chiasmTracker.showScreenCalibration();
        await chiasmTracker.setupTrackerWithRetries();

        setTimeout(() => {
          qualtricsThis.clickNextButton();
        }, 100);
      } catch (err) {
        alert("Setup failed. Please check your webcam and reload the page.");
      }
    };
    document.head.appendChild(script);
  } else {
    await chiasmTracker.setupTrackerWithRetries();
  }
});
  1. Replace YOUR_EXPERIMENT_ID and YOUR_AUTH_TOKEN with the credentials from your Chiasm dashboard.
tip

The script uses Qualtrics' built-in ResponseID — a unique identifier automatically assigned to every survey response. No extra setup is needed.

What happens at runtime​

  1. The Qualtrics page loads and immediately hides the default survey.
  2. The Chiasm script is injected into the page.
  3. The participant completes screen calibration and webcam setup.
  4. Once setup succeeds, the survey automatically advances to the next block — no manual click required.

2. Record eye-tracking on a question​

For each question where you want to capture gaze data, add a short script that starts recording when the question appears and stops when the participant leaves the page.

  1. Select the question (e.g. a Text / Graphic block showing a stimulus image).
  2. Click the JavaScript icon (</>) to open the script editor.
  3. Replace the default content with the following code:
Qualtrics.SurveyEngine.addOnReady(function () {
  if (window.chiasmTracker) {
    window.currentTrialTimestamps = chiasmTracker.startRecording(this.questionId);
  }
});

Qualtrics.SurveyEngine.addOnUnload(function () {
  if (window.chiasmTracker) {
    chiasmTracker.stopRecording();
  }
});

startRecording receives this.questionId so each recording segment is tagged with the Qualtrics question that produced it. stopRecording is called in addOnUnload, which fires when the participant navigates away from the page — whether by clicking Next or through auto-advance.

tip

Repeat this step for every question where you need gaze data. Questions without this script are simply skipped by the tracker.

3. Clean up at the end of the survey​

On your final question (or a dedicated end-of-survey Text / Graphic block), add a script that releases tracker resources when the participant leaves the page.

  1. Open the JavaScript editor on the last question.
  2. Replace the default content with the following code:
Qualtrics.SurveyEngine.addOnUnload(function () {
  if (window.chiasmTracker) {
    chiasmTracker.cleanupTracker();
  }
});

This calls cleanupTracker to stop the webcam and free all tracker resources.

Next steps​