NOTE: This requires JavaScript programming knowledge.

Introduction

This describes how to embed the morphii technology into a Qualtrics survey. This integration uses an integration wrapper to encapsulate most of the the coding needed. Note that this is not the only way to integrate morphii into a Qualtrics survey, but this document focuses on using the integration wrapper.

Limitations

The integration wrapper does have limitations. This does not mean that these things cannot be done, just they are limitations for this integration wrapper implementation.

  • The survey must be a single page. The wrapper does not support survey questions on separate pages.
  • Marking morphii questions as required is not supported.
  • Requiring comments for morphii questions is not supported.
  • The integration wrapper is only supported on modern browsers. No support for old browsers such as IE8.

Integration Wrapper

Qualtrics survey questions that are associated with the morphii widget must be of question type: Descriptive Text.

Descriptive Text

The integration wrappers requires the ID (QID) assigned to a question. The ID can be found by inspecting the DOM or via the Tools menu on the Survey page.

QID via Survey UI

On the Survey page click Tools -> Auto-Number Questions. Then select Internal ID Numbering See below for example.

Auto-number

QID via DOM

Preview the survey. Right-click on the question in the preview window and select “Inspect”. The question IDs can be seen in the Developer Tools window. See below for example.

Question ID inspection

To add the integration wrapper, create a “dummy question” with the question type Descriptive Text in the Qualtrics survey. The JavaScript needed to setup the integration wrapper will be attached to this “dummy question”. It is recommended that this “dummy question” be the first question in the survey. Follow the Qualtrics instructions for adding custom JavaScript to a question. Add JavaScript

Descriptive Text

Below is canned JavaScript which can be used in the “dummy question” mentioned above. There are 5 sections that need to be modified in the following code.

  1. Morphii account id and client key values must be entered at the top of the script in the _accountId and _clientKey variables.
  2. To customize the Submit button color, the properties in the button_style will need to be updated.
  3. The questions section needs to be updated. This is where morphiis are associated with each question. The morphii ids for each question may be different than the ones listed in this sample. Be sure to use the id assigned to the Descriptive Text questions in the questions array.
  4. If custom logic when a morphii is selected can be added to the function onMorphiiSelectionChange.
  5. If custom logic when a user types into the morphii widget comment field the code will be in the function onMorphiiCommentChange.
Qualtrics.SurveyEngine.addOnload(function()
{
  // Configurable values: accountId, clientKey, buttonStyle, questions
  var accountId = '<ACCOUNT ID HERE>';
  var clientKey = '<CLIENT KEY HERE>';
  var buttonStyle = {
    background_color: '#c32432',
    focus_background_color: '#db3f4c',
    hover_background_color: '#ad202c',
    active_background_color: '#821821'
  };
  var questions = [
    {
      id: 2,  // This maps to question id "Q2".
      comment: {
        show: false
      },
      morphiiIds: [
        { id: '6363734358316589056', name: 'Angry', weight: 1 },
        { id: '6362666072115564544', name: 'Happy', weight: 2 },
        { id: '6363488681244622848', name: 'Sad', weight: 3 },
        { id: '6363735117617217536', name: 'Disgusted', weight: 4 },
        { id: '6362674737212084224', name: 'Surprised', weight: 5 }
      ]
    },
    {
      id: 6,  // This maps to question id "Q6".
      comment: {
        show: true,
        maxlength: 120,
        label: 'Please leave a comment'
      },
      slider: {
        initial_intensity: 0.5,
        show_animation: false
      },
      morphiiIds: [
        { id: '6363734358316589056' },
        { id: '6362666072115564544' },
        { id: '6363488681244622848' },
        { id: '6362674737212084224' }
      ]
    }
  ];

  function onMorphiiSelectionChange(event) {
    // Add custom logic when morphii is selected.
  }

  function onMorphiiCommentChange(event) {
    // Add custom logic when text is entered into comment field.
  }

  // End configurable settings.

  // The code below should not be changed.
  var survey = this;
  var scriptSrc =  'https://survey-wrapper.morphii.com/v1/qualtrics-wrapper.min.js';

  // Load the wrapper script if not already loaded.
  if (!isScriptAlreadyIncluded()) {
    var js = document.createElement('script');
    js.type = 'application/javascript';
    js.src = scriptSrc;
    js.onload = processSetup;
    document.body.appendChild(js);
  }
  else {
    processSetup();
  }

  // Initialize the wrapper.
  var wrapper = null;
  function processSetup() {
    wrapper = new Morphii.QualtricsWrapper();
    if (wrapper) {
      var params = {
        response_id: '${e://Field/ResponseID}',
        survey_id: '${e://Field/SurveyID}',
        client_key: clientKey,
        account_id: accountId,
        button_style: buttonStyle,
        questions: questions,
        callbacks: {
          selection_change: onMorphiiSelectionChange,
          comment_change: onMorphiiCommentChange
        }
      };
      wrapper.init(survey, $('NextButton'), params);
    }
  }

  // Helper function to check if wrapper script is already loaded.
  function isScriptAlreadyIncluded() {
    var scripts = document.getElementsByTagName('script');
    for(var i = 0; i < scripts.length; i++) {
      if(scripts[i].getAttribute('src') === scriptSrc) {
        return true;
      }
    }
    return false;
  }
});

Account Id and Client Key

The Vizbii team will provide the account id and client key when the account has been provisioned. These values will look something like:

var accountId = '15521928';
var clientKey = 'db055eeb-af22-5c2b-b2df-e11eec55c789';

Button Style

The buttonStyle contains the colors used for the Submit button. These include the background color for the normal, hover, active, and focus states.

var buttonStyle = {
  background_color: '#c32432',
  focus_background_color: '#db3f4c',
  hover_background_color: '#ad202c',
  active_background_color: '#821821'
};

Submit Buttons

Questions Array

The questions contains an array of objects that define the morphiis to use for specific questions. The object contains an id property which is the question id. For example the id would be 6 for the question id Q6. The morphiiIds property is an array of morphiis to use for that question. The morphii object is defined by an id and name. If the name property is omitted then the default morphii name will be used.

Comment

The comment property is used to configure the comment field. It contains 3 properties:

  • show: Flag to display the morphii comment field or not. Default: false
  • maxlength: The max character length of the comment field. Default: 512
  • label: The label above the comment field. Default: Please leave a comment

Slider

The slider property is used to configure the the initial intensity and if the slider should animate when morphii is selected. It contains 2 properties:

  • initial_intensity: The initial intensity of the morphii when selected. The number must be between 0 and 1. Default: 0.2
  • show_animation: Flag to animated the slider/morphii when selected. Default: false

Morphii Ids

The morphiiIds property is an array of morphii objects to use for that question. The morphii object contains the following properties:

  • id: This property is required. It is the unique id of the morphii.
  • name: The label to display under the morphii. If omitted the default morphii name will be used.
  • weight: An arbitrary integer value assigned to this morphii. If omitted the value will be 0. Setting this property is helpful if using the morphii selection callback.

Example:

var questions = [
  {
    id: 6,  // This maps to question id "Q6".
    comment: {
      show: true,
      maxlength: 10,
      label: 'Please leave a comment'
    },
    slider: {
      initial_intensity: 0.2,
      show_animation: true
    },
    morphiiIds: [
      {
        id: '6362666072115564544',
        name: 'Joy',
        weight: 5
      },
      {
        id: '6363488681244622848'
      }
    ]
  }
];

Morphii Selection Change Callback

The onMorphiiSelectionChange function is for custom logic when a morphii is selected. The function is passed the morphii selection event. This data contains properties to identify which morphii was select/unselected and which target the morphii is associated with.

Example:

{
  "selection_required_valid": true,
  "type": "selection_changed",
  "widget": {
    "id": "f0f3c13d-3bc8-449b-bce1-88a6b9362d36",
    "target_id": "QID2",
    "morphii": {
      "selected": true,
      "weight": "2"
    }
  }
}

The event properties:

  • selection_required_valid: This property indicates that all selection requirement have been met across all morphii widgets on the page. This property is not valid for this survey integration wrapper implementation.
  • type: The type of event. This value will be selection_changed.
  • widget: Information about the specific widget firing the event.
    • id: The unique id of the widget. This property is not valid for this survey integration wrapper implementation.
    • target_id: The id of the target associated with this widget. For this implementation this will the ID of the Qualtrics question. For example, QID2.
    • morphii: Information about the specific morphii in the widget.
      • selected: A flag if the morphii is selected or not.
      • weight: The weight value assigned to this morphii in the Morphii Ids section. This value will help determine which morphii was selected/unselected in the list.

Below is sample code for the onMorphiiSelectionChange function. This sample code demonstrates if the user selects the Happy morphii for Question 2 then Question 11 will be displayed.

function onMorphiiSelectionChange(event) {
  // Add custom logic when morphii is selected.

  // Check the target id if event is for QID2.
  if (event.widget.target_id === 'QID2') {
    // If the morphii for this event is selected and the weight is 2
    // then display question 11, else hide question 11.

    // NOTE: The weight value 2 was assigned to the morphii when
    // defining the morphiiIds.

    // Get the element for question 11.
    var qId = document.getElementById('QID11');
    if (qId && event.widget.morphii.selected === true &&
        event.widget.morphii.weight === '2') {
      qId.style.display = 'block';
    }
    else {
      qId.style.display = 'none';
    }
  }
}

Morphii Comment Change Callback

The onMorphiiCommentChange function is for custom logic when a user changes the text in a morphii widget comment field. The function is passed the morphii comment changed event. This data contains properties to identify change to the comment text and which target the morphii is associated with.

Example:

{
  "comment_required_valid": true,
  "type": "comment_changed",
  "widget": {
    "id": "f0f3c13d-3bc8-449b-bce1-88a6b9362d36",
    "target_id": "QID5",
    "comment": {
      "required": false,
      "length": 9,
      "value": "Test text"
    }
  }
}

The event properties:

  • comment_required_valid: This property indicates that all selection requirement have been met across all morphii widgets on the page. This property is not valid for this survey integration wrapper implementation.
  • type: The type of event. This value will be comment_changed.
  • widget: Information about the specific widget firing the event.
    • id: The unique id of the widget. This property is not valid for this survey integration wrapper implementation.
    • target_id: The id of the target associated with this widget. For this implementation this will the ID of the Qualtrics question. For example, QID5.
    • comment: Information about the specific comment in the widget.
      • required: A flag indicating if the comment field was required or not.
      • length: The length of the text currently in the comment field.
      • value: The text value currently in the comment field.

Below is sample code for the onMorphiiCommentChange function. This sample code demonstrates if the user enters a comment for Question 5 then Question 11 will be displayed.

function onMorphiiCommentChange(event) {
  // Add custom logic when text is entered into comment field.

  // Check the target id if event is for QID5.
  if (event.widget.target_id === 'QID5') {
    // If the comment field for this widget contains text then show question 11
    // else hide question 11.
    var qId = document.getElementById('QID11');
    if (qId && event.widget.comment.length > 0) {
      qId.style.display = 'block';
    }
    else {
      qId.style.display = 'none';
    }
  }
}

Dynamically add morphii widget to question

The morphii widget can be dynamically added a question after the page is loaded. This can be useful if the widget options need to be based on an answer to a previous question.

Below is sample code for the onMorphiiSelectionChange function. This sample code demonstrates if the user selects a morphii for Question 2 then Question 12 will be displayed with a list of morphiis based on Question 2’s selection.

function onMorphiiSelectionChange(event) {
  // Add custom logic when morphii is selected.

  // Check the target id if event is for QID2.
  if (event.widget.target_id === 'QID2') {
    // If a morphii is selected from QID2 then display question 12
    // with morphiis based on the selection, else hide question 12.

    // Get the element for question 12.
    var qId = document.getElementById('QID12');
    if (qId && event.widget.morphii.selected === true) {
      var morphiiIds = [];
      if (event.widget.morphii.weight === '1' ||
          event.widget.morphii.weight === '2' ||
          event.widget.morphii.weight === '3') {
        morphiiIds = [
          { id: '6362666072115564544', name: 'Happy', weight: 1 },
          { id: '6363488681244622848', name: 'Sad', weight: 2 }
        ];
      }
      else if (event.widget.morphii.weight === '4' ||
               event.widget.morphii.weight === '5')  {
        morphiiIds = [
          { id: '6363735117617217536', name: 'Disgusted', weight: 1 },
          { id: '6363734358316589056', name: 'Angry', weight: 2 }
        ];
      }

      var questionParams = {
        id: 12,
        comment: {
          show: false,
          maxlength: 512,
          label: 'Please leave a comment'
        },
        morphiiIds: morphiiIds
      };

      wrapper.add(questionParams, function(error, results) {
        if (error) {
          // Handle error case.
        }
      });

      // Show Question 12.
      qId.style.display = 'block';
    }
    else {
      // Hide Question 12.
      qId.style.display = 'none';
    }
  }
}

Embedded Data

Qualtrics has a feature called Embedded Data to store any extra information to record in addition to the question responses. The morphii integration wrapper uses Embedded Data to store the morphii results (name, intensity, etc…). This data is then saved in the Qualtrics database with the other results from the survey.

Qualtrics is making enhancements everyday, but currently does not provide a way to dynamically create Embedded Data elements. Due to this, the Embedded Data elements need to be created manually while setting up the survey. Embedded Data

It is recommended that the Embedded Data element be the first element in the survey flow. There are 4 embedded data element fields that must be added per morphii question. The Embedded Data element field names must have the format below, where “#” is the question number associated with the morphii. The Embedded Data element field names will show as column names in the order entered when exporting survey results in Qualtrics.

  • morphii_name_q#
  • morphii_intensity_q#
  • morphii_comment_q#
  • morphii_question_q#

For example, for the question with id “Q6” the Embedded Data element names will be:

morphii_name_q6
morphii_intensity_q6
morphii_comment_q6
morphii_question_q6

Embedded Data

Exporting Survey Data

When exporting Qualtrics survey data to a CVS, the morphii data will be included in the export. Each question that has morphiis associated with it will have 4 columns in the exported data. They will match the Embedded Data field names. For example, for question id “Q3”:

  • morphii_name_q3: This column contains the name of the morphii selected by the user.
  • morphii_intensity_q3: This column contains the intensity that was set by the user.
  • morphii_comment_q3: This column contains the text from the morphii comment field. Note this will be blank if the comment field option was not turned on.
  • morphii_question_q3: This column contains the question text the morphiis were associated with.

Data Export