Qualtrics API Integration guide + Example Surveys

STEP 1

Add these Embedded data variables at the top from Survey Flow:

Param_id (set param id value for shopping exercise)

findability_param_id (set param id value for findability exercise)

ResponseID (Value is set by Qualtrics itself, no need to add anything in value)

api_error (any error in api is stored in here)

purchase_data (all purchase data is stored in this as JSON)

findability_product (set product sku here for findability)

findability_data (all findability data is stored in this as JSON)

STEP 2

Enable ‘Allow respondents to finish later’ from Survey Option->Responses

STEP 3

Add below code to the question after which respondent should be redirected to conceptsauce for shopping shelf

Qualtrics.SurveyEngine.addOnUnload(function() {
	let paramId = '${e://Field/param_id}';
	let responseId = '${e://Field/ResponseID}';
	const url = encodeURIComponent(window.location.href);
	let redirectUrl = 'https://survey.rose.conceptsauce.io/?param_id=' + paramId + '&respondent_id=' + responseId + '&link=' + url;
	window.open(redirectUrl, '_self');
});

STEP 4

Add below code to the next question where respondent will be redirected back from conceptsauce shopping exercise.

Qualtrics.SurveyEngine.addOnload(function() {
	var $this = jQuery(this.questionContainer);
	$this.hide();  //hide survey question until we get information from api
});
Qualtrics.SurveyEngine.addOnReady(function() {
	var $this = jQuery(this.questionContainer);

	//this method gets purchase details
	var getShopShelfPurchaseDetails = function (surveyId, responseEncoded) {
		//preparing data for api call
		let postData = {
			"event_type":"survey_data_request",
			"action":"get_shop_shelf_detail_purchases",
			"data":{
				"target": {
					"survey_id": surveyId,
					"respondent_encoded": responseEncoded,
					"block_id":"shelf"
				}
			}
		}
		jQuery.ajax({
			type: 'POST',
			url: 'https://public-survey-data-api.rose.conceptsauce.io/api',
			data: JSON.stringify(postData),
			contentType: "application/json",
			dataType: 'json',
			success: function(res) { 
				//check api response code
				if (!res || res.code != 200) {
					//capture error code in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', res.code + (res.reason || ''));
					return;
				}
				//reading purchase data from response and saving in embedded data
				if (res.data && res.data.basket_details && res.data.basket_details && res.data.basket_details.raw_purchase_details) {
					console.log(res.data.basket_details.raw_purchase_details);
					let outputStr = '';
					res.data.basket_details.raw_purchase_details.forEach(item=> {
						outputStr += 'SKU: ' + item.sku + ', Quantity: ' + item.quantity + ', Price for One: ' + item.price_for_one + ', Zone: ' + item.zone + '\n\n';
					});
					outputStr = outputStr.trim();
					//show data below question text
					jQuery(".QuestionBody", $this).html(outputStr.replace(/\n/ig,"<br>"));
					//saving data in embedded variable
					Qualtrics.SurveyEngine.setEmbeddedData('purchase_data', JSON.stringify(res.data.basket_details.raw_purchase_details));
				} else {
					//capture any error in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', 'purchase details not found');
				}
			 },
			 error: function(error) {
				console.log(error);
			 }
		});
	}
	
	//this method is for getting respondent encoded id
	var getRespondentEncodedId = function (surveyId) {
		let qualtricsResId = '${e://Field/ResponseID}';  //get qualtrics response id
		//preparing data for api call
		let postData = {
			"event_type":"respondent_encoded",
			"action":"get_respondent_encoded",
			"data":{
				"survey_id": surveyId,
				"respondent_id": qualtricsResId
			}
		}
		jQuery.ajax({
			type: 'POST',
			url: 'https://public-survey-data-api.rose.conceptsauce.io/api',
			data: JSON.stringify(postData),
			contentType: "application/json",
			dataType: 'json',
			success: function(res) { 
				//check api response code
				if (!res || res.code != 200) {
					//capture error code in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', res.code + (res.reason || ''));
					return;
				}
				if (res.data && res.data.respondent_encoded) {
					//get respondent encoded from api response and pass it to the function that calls api to get purchase data
					getShopShelfPurchaseDetails(surveyId, res.data.respondent_encoded);
				} else {
					//capture any error in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', 'respondent encoded not found');
				}
			 },
			 error: function(error) {
				console.log(error);
			 }
		});
	}

	//this function is called first to get survey id
	var getSurveyId = function() {
		let paramId = Qualtrics.SurveyEngine.getEmbeddedData('param_id'); //get param id from embedded data
		//preparing data for api call
		let postData = {
			"event_type":"params_crud",
			"action":"get_params",
			"data":{
				"params_id": paramId
			}
		}
		jQuery.ajax({
			type: 'POST',
			url: 'https://better-params-api.rose.conceptsauce.io/api',
			data: JSON.stringify(postData),
			contentType: "application/json",
			dataType: 'json',
			success: function(res) { 
				$this.show();  //show qualtrics question after we get first api response
				//check api response code
				if (!res || res.code != 200) {
					//capture error code in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', res.code + (res.reason || ''));
					return;
				}
				if (res.data && res.data.params && res.data.params.survey_id) {
					//get survey id from api response and pass it to the function that calls api to get respondent encoded
					getRespondentEncodedId(res.data.params.survey_id);
				} else {
					//capture any error in the embedded data variable
					Qualtrics.SurveyEngine.setEmbeddedData('api_error', 'survey id not found');
				}
			 },
			 error: function(error) {
				console.log(error);
			 }
		});
	}
	getSurveyId();
});

STEP 5

Add below code to the question after which respondent should be redirected to conceptsauce for findability

Qualtrics.SurveyEngine.addOnUnload(function() {
	let paramId = '${e://Field/findability_param_id}';  //get embedded data value of param id
	let responseId = '${e://Field/ResponseID}';  //get unique response id generated from Qualtrics
	let findabilityProduct = '${e://Field/findability_product}';  //get embedded data value of product sku
	const url = encodeURIComponent(window.location.href);  //encode current url to be callback from conceptsauce
	
	//preparing custom params value
	let customParams = {
		"shelf": {
			"set:correct_product":findabilityProduct
		}
	};
	let redirectUrl = 'https://survey.rose.conceptsauce.io/?param_id=' + paramId + '&respondent_id=' + responseId + '&custom_params=' + btoa(JSON.stringify(customParams)) + '&link=' + url;
	window.open(redirectUrl, '_self');  //redirect to conceptsauce with all the parameters
});

STEP 6

Add below code to the next question where respondent will be redirected back from conceptsauce findability exercise:

A few example Surveys you can import as a test: