qualtrics.js

/**
 * AUTO-ADVANCE HEATMAP FOR QUALTRICS
 * ===================================
 * Automatically advances to the next block after a specified number of clicks
 * on a heatmap question. 
 * 
 * @author Dakota Roth
 * @version 1.0
 * @license MIT
 *
 * SETUP INSTRUCTIONS:
 * -------------------
 * 1. Create or edit a heatmap question in Qualtrics
 * 2. Under "Edit Question", set "Interaction clicks" to match your desired NUMBER_OF_CLICKS
 *    (this controls the minimum clicks Qualtrics requires before allowing advancement)
 * 3. Update the NUMBER_OF_CLICKS constant below to your desired value
 * 4. Copy this entire code block
 * 5. In your question settings, Under the question behavior dropdown click JavaScript 
 * 6. Remove pre-existing code and paste the code into the JavaScript editor
 * 7. Save and test in preview mode
 * 
 * HOW IT WORKS:
 * -------------
 * - Hides the Next/Previous buttons to prevent manual advancement
 * - Counts each click on the heatmap
 * - Automatically clicks "Next" when the target click count is reached
 * - Participants cannot advance until they've clicked the required number of times
 * 
 * TROUBLESHOOTING:
 * ----------------
 * - If auto-advance doesn't trigger: Ensure the "Interaction clicks" setting in 
 *   Qualtrics matches or is less than NUMBER_OF_CLICKS
 * - If clicks aren't registering: Check that the question type is set to "Heatmap"
 * - Test in preview mode before deploying to ensure expected behavior
 * 
 * CUSTOMIZATION:
 * --------------
 * To change the required number of clicks, modify only the NUMBER_OF_CLICKS value below.
 * Do not change other parts of the code unless you understand the Qualtrics JavaScript API.
 */

// ============= CONFIGURATION =============
const NUMBER_OF_CLICKS = 3 // UPDATE THIS: Set to your desired number of clicks before auto-advance
// =========================================

// Internal counter - do not modify
let counter = 0;

Qualtrics.SurveyEngine.addOnload(function() {
	/*
	 * Runs when the page loads (before elements are visible)
	 * Hides navigation buttons to force participants to complete the interaction
	 */
	this.hideNextButton();
	this.hidePreviousButton();
});

Qualtrics.SurveyEngine.addOnReady(function() {
	/*
	 * Runs when the page is fully loaded and interactive
	 * Sets up click tracking on the heatmap container
	 */
	const q = jQuery("#" + this.questionId); // Get reference to this specific question
	
	// Attach click listener to heatmap container
	q.find(".HeatMapContainer").on("click", () => {
		counter++; // Increment click counter
		
		// Auto-advance when target clicks reached
		if (counter >= NUMBER_OF_CLICKS) {
			this.clickNextButton();
		}
	});
});