Qualtrics count down timer control

README.md

Qualtrics count down timer control

Features

This script helps adding a global count down timer that:

1. Counts from a pre-defined time down to 0.
2. When it counts down to 0, automatically submit the survey.
3. When clicking on Yes option on specific pages, extend the timer for another 10s.

Usage

1. Paste first-question.js content in the first question that adds the timer and register necessary functions.
2. Paste each_of_all_questions.js content in all other questions.
3. For questions that can extend the timer, paste time_extension_question.js content instead.

each_of_all_questions.js

///////////////////////////////////////////
// All questions are required to have this registerTimerControl(this) 
// to manage auto-submit.

Qualtrics.SurveyEngine.addOnload(function() {
  // Kun: check if it should timeout and submit
  registerTimerControl(this);
});

first-question.js

TOTAL_TIME = 60; // Count down timer in seconds
TIMER_EXTENSION_YES_INDEX = 1; // the index of YES option in a block

////////////////////////////////////////////////////////////////////////////
// Events
Qualtrics.SurveyEngine.addOnload(function () {
  /*Place your JavaScript here to run when the page loads*/
});

Qualtrics.SurveyEngine.addOnReady(function () {
  that = this;
  // Add a global timer display at the top of every page
  addTimerElement(toTimeStr());

  // Start the countdown
  var interval = setInterval(function () {
    newTotalTime = getTotalTime() - 1;
    setTotalTime(newTotalTime);

    document.getElementById("globalTimer").innerHTML = toTimeStr();

    // Check if time is up
    if (newTotalTime <= 0) {
      clearInterval(interval);
      // Auto-submit the survey
      Qualtrics.SurveyEngine.setJSEmbeddedData("timeOut", "1");
      checkSubmit(that);
    }
  }, 1000);
});

Qualtrics.SurveyEngine.addOnUnload(function () {
  /*Place your JavaScript here to run when the page is unloaded*/
});
// Events END
////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////
// Functions
function addTimerElement(content) {
  var timerDiv = document.createElement("div");
  timerDiv.id = "globalTimer";
  timerDiv.style.position = "fixed";
  timerDiv.style.top = "10px";
  timerDiv.style.right = "10px";
  timerDiv.style.padding = "10px";
  timerDiv.style.backgroundColor = "#f8d7da";
  timerDiv.style.color = "#721c24";
  timerDiv.style.fontSize = "16px";
  timerDiv.style.fontWeight = "bold";
  timerDiv.style.border = "1px solid #f5c6cb";
  timerDiv.innerHTML = content;
  document.body.appendChild(timerDiv);
}

const getTotalTime = () => {
  totalTime = parseInt(Qualtrics.SurveyEngine.getJSEmbeddedData("globalTimer"));

  if (isNaN(totalTime)) {
    totalTime = TOTAL_TIME;
    Qualtrics.SurveyEngine.setJSEmbeddedData("globalTimer", totalTime);
  }

  return totalTime;
};

const setTotalTime = (totalTime) => {
  Qualtrics.SurveyEngine.setJSEmbeddedData("globalTimer", totalTime);
};

const toTimeStr = () => {
  var totalTime = getTotalTime();
  return "Time Remaining: " + totalTime + "s";
};

// Make checkSubmit globally available
window.checkSubmit = (that) => {
  if (Qualtrics.SurveyEngine.getJSEmbeddedData("timeOut") === "1") {
    that.clickNextButton();
  }
};

window.registerTimeExtension = (that) => {
  Qualtrics.SurveyEngine.addOnPageSubmit(function (type) {
    if (type == "next") {
      choices = that.getChoices();
      value = that.getChoiceValue();

      // if not exactly 2 choices, then return
      if (choices.length != 2) {
        console.log("[timer] choices.length != 2");
        return;
      }

      // TIMER_EXTENSION_YES_INDEX = 1, if that choice is selected, then add 10 seconds
      choiceYes = choices[TIMER_EXTENSION_YES_INDEX];
      if (value == choiceYes) {
        setTotalTime(getTotalTime() + 10);
      }
    }
  });
};

window.registerTimerControl = (that, registerTimerExtension = false) => {
  checkSubmit(that);

  if (registerTimerExtension) {
    console.log("answers", that.getChoices());
    // if that (this called from addOnReady) .getAnswers() has more than one element, then it is a question page, then register time extension
    if (that.getChoices().length > 1) {
      registerTimeExtension(that);
    }
  }
};

time_extension_question.js

///////////////////////////////////////////
// The questions with time extension feature (selecting Yes would extend the timer for another 10s) pass another parameter: `registerTimerExtension=true`

Qualtrics.SurveyEngine.addOnload(function() {
  // Kun: check if it should timeout and submit, (true) also register time extension control
  registerTimerControl(this, true);
});