NOTE: This integration requires knowledge of the JavaScript programming language.

Introduction

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

Limitations

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

  • The survey must be a single page. The integration 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 only supported on modern browsers. No support for old browsers such as IE8.

Integration

Morphii Questions

SurveyGizmo survey questions that are associated with the morphii widget should be Text/Media - Text/Instruction type questions.

Text/Instruction

QID via Survey UI

The integration requires the ID assigned to a question. The ID can be found in the Build tab for a survey.

Question Id

Add a script tag for loading the SurveyGizmo integration in the Style -> HTML/CSS Editor -> Custom<Head> tab. Add the script tag:

<script src="https://survey-integration.morphii.com/v1/surveygizmo-integration.min.js"></script>

Auto-number

JavaScript Action

The integration requires that a JavaScript Action be added to the SurveyGizmo survey. This is where the main JavaScript code will reside to interface with the integration. It is recommended that the JavaScript action is the first element in the survey.

JavaScript Action

JavaScript Action Editing JavaScript Action

JavaScript

Below is canned JavaScript which can be used in the “JavaScript Action” mentioned above. There are multiple properties that need to be modified in the following code.

  1. Morphii account_id and client_key values must be entered.
  2. The questions array 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.
  3. Optional: The additional_info property with: audience, category, and timing.
  4. Optional: custom logic when a morphii is selected can be added to the function onMorphiiSelectionChange.
  5. Optional: custom logic when a user types into the morphii widget comment field the code will be in the function onMorphiiCommentChange.
$(function() {

  $(document).ready(function() {

    // Configurable values: account_id, client_key, additional_info, and questions
    var integrationParams = {
      account_id: '<ACCOUNT ID HERE>',
      client_key: '<CLIENT KEY HERE>',
      additional_info: {
        audience: null, // ['customer', 'employee', 'patient', 'community', 'general', 'other']
        category: null, // ['satisfaction', 'engagement', 'hr', 'mood']
        timing: null    // ['pre-event', 'during-event', 'post-event', 'n/a']
      },
      response_id: '[survey("session id")]',
      survey_id: '[survey("id")]',
      page_id: '[page("id")]',
      callbacks: {
        selection_change: onSelectionChange,
        comment_change: onCommentChange
      },
      questions: [
        {
          id: 57,
          comment: {
            show: true,
            maxlength: 512,
            label: {
              en: 'Please leave a comment'
            }
          },
          slider: {
            show_animation: true,
            anchor_labels: {
              show: true
            }
          },
          instructions: {
            show: true
          },
          morphii_ids: [
            { id: '6202184382145363968', name: { en: 'Excited' } },
            { id: '6362666072115564544', name: { en: 'Delighted' } },
            { id: '6363734358316589056', name: { en: 'Frustrated' } },
            { id: '6362674737212084224', name: { en: 'Surprised' } },
            { id: '6363735117617217536', name: { en: 'Disgusted' } },
            { id: '6363735353273270272', name: { en: 'Worried' } },
            { id: '6363488681244622848', name: { en: 'Disappointed' } },
            { id: '6202184384594837504', name: { en: 'Meh' } }
          ],
          hidden_action_ids: {
            id: 94,
            intensity: 95,
            name: 96,
            part_name: 97,
            question: 98,
            comment: 99
          }
        },
        {
          id: 59,
          comment: {
            show: false
          },
          slider: {
            anchor_labels: {
              show: true
            }
          },
          instructions: {
            show: true
          },
          morphii_ids: [
            { id: '6362666072115564544', name: { en: 'Happy' } },
            { id: '6363488681244622848', name: { en: 'Sad' } },
            { id: '6363734358316589056', name: { en: 'Grumpy' } },
            { id: '6363735353273270272', name: { en: 'Anxious' } },
            { id: '6202184384594837504', name: { en: 'Bored' } }
          ],
          hidden_action_ids: {
            id: 100,
            intensity: 101,
            name: 102,
            part_name: 103,
            question: 104,
            comment: 105
          }
        }
      ]
    };

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

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

    // Create an instance of the morphii integration and call the init function.
    var morphiiIntegration = new Morphii.SurveyGizmoIntegration();
    if (morphiiIntegration) {
      morphiiIntegration.init(integrationParams, function(error, results) {
        if (error) {
          console.log('integration error: ' + JSON.stringify(error, null, 2));
          alert('There was an error loading the survey. Please try again later.');
        }
      });
    }
  });
});

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 account_id = '15521928';
var client_key = 'db055eeb-af22-5c2b-b2df-e11eec55c789';

Additional Information

The additional_info object contains information about items like audience, category, and timing. Valid property values:

  • audience: ‘customer’, ‘employee’, ‘patient’, ‘community’, ‘general’, ‘other’
  • category: ‘satisfaction’, ‘engagement’, ‘hr’, ‘mood’
  • timing: ‘pre-event’, ‘during-event’, ‘post-event’, ‘n/a’
var additional_info = {
  audience: 'customer',
  category: 'satisfaction',
  timing: 'post-event'
};

Questions Array

The questions array contains objects that define the morphiis to use for specific questions.

var questions = [
  {
    id: 57,
    comment: {
      show: true,
      maxlength: 512,
      label: {
        en: 'Please leave a comment'
      }
    },
    slider: {
      show_animation: true,
      anchor_labels: {
        show: true
      }
    },
    instructions: {
      show: true
    },
    morphii_ids: [
      { id: '6202184382145363968', name: { en: 'Excited' } },
      { id: '6362666072115564544', name: { en: 'Delighted' } },
      { id: '6363734358316589056', name: { en: 'Frustrated' } },
      { id: '6362674737212084224', name: { en: 'Surprised' } },
      { id: '6363735117617217536', name: { en: 'Disgusted' } },
      { id: '6363735353273270272', name: { en: 'Worried' } },
      { id: '6363488681244622848', name: { en: 'Disappointed' } },
      { id: '6202184384594837504', name: { en: 'Meh' } }
    ],
    hidden_action_ids: {
      id: 94,
      intensity: 95,
      name: 96,
      part_name: 97,
      question: 98,
      comment: 99
    }
  },
  {
    id: 59,
    comment: {
      show: false
    },
    slider: {
      anchor_labels: {
        show: true
      }
    },
    instructions: {
      show: true
    },
    morphii_ids: [
      { id: '6362666072115564544', name: { en: 'Happy' } },
      { id: '6363488681244622848', name: { en: 'Sad' } },
      { id: '6363734358316589056', name: { en: 'Grumpy' } },
      { id: '6363735353273270272', name: { en: 'Anxious' } },
      { id: '6202184384594837504', name: { en: 'Bored' } }
    ],
    hidden_action_ids: {
      id: 100,
      intensity: 101,
      name: 102,
      part_name: 103,
      question: 104,
      comment: 105
    }
  }
];

id

The id property is the question id. This can be found in the Build tab for the survey.

Question Id

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 property that holds the text in each supported language. The label above the comment field. Each translation is defined separately. The en version of the label is required if any other language is declared. Default: Please leave a comment

Example:

var comment: {
  show: true,
  maxlength: 10,
  label: {
    en: 'Please leave a comment',
    es: 'Por favor deja un comentario',
    zh: '请发表评论'
  }
};

slider

The slider property is used to configure the the initial intensity, the slider animation, and anchor text.

  • 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.
  • anchor_labels: This property defines the options for the anchor text on each side of the slider.
    • show: This property is the flag to show the anchor text. Value is true or false. Default: false.
    • left: This property is used to override the default text for the left anchor text. Each translation is defined separately. The en version of the label is required if any other language is declared.
    • right: This property is used to override the default text for the right anchor text. Each translation is defined separately. The en version of the label is required if any other language is declared.

Example:

var slider = {
  initial_intensity: 0.2,
  show_animation: true,
  anchor_labels: {
    show: true,
    left: {
      en: 'Less intense',
      es: 'Menos intenso'
    },
    right: {
      en: 'More intense',
      es: 'Mas intenso'
    }
  }
};

instructions

The instructions property defines the options for the instruction text.

  • show: This property is the flag to show the instruction text. Value is true or false. Default: false.
  • pre_select_label: This property is used to override the default text for the instruction text that is displayed when a morphii selection has not been made. Each translation is defined separately. The en version of the label is required if any other language is declared.
  • post_select_label: This property is used to override the default text for the instruction text that is displayed when a morphii is selected. Each translation is defined separately. The en version of the label is required if any other language is declared.

Example:

var instructions = {
  show: true,
  pre_select_label: {
    en: 'Select the graphic above that best represents how you feel.',
    es: 'Seleccione el gráfico de arriba que mejor represente cómo se siente.'
  },
  post_select_label: {
    en: "Move the slider to show how intense your feeling is.",
    es: "Mueva el control deslizante para mostrar qué tan intenso es su sentimiento."
  }
};

morphii_ids

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

  • id: This property is required. It is the unique id of the morphii.
  • name: The property that holds the morphii name for each supported language. Each translation is defined separately. The en translation of the name is required if any other language is declared. 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:

// Define custom names.
var morphiiIds1 = [
  {
    id: '6363734358316589056',
    name: {
      en: 'Angry',
      es: 'Enojado',
      zh: '愤怒'
    },
    weight: 1
  },
  {
    id: '6362666072115564544',
    name: {
      en: 'Happy',
      es: 'Contento',
      zh: '快乐'
    },
    weight: 2
  },
  {
    id: '6363488681244622848',
    name: {
      en: 'Sad',
      es: 'Triste',
      zh: '伤心'
    },
    weight: 3
  }
];

// Use default names.
var morphiiIds2 = [
  { id: '6363734358316589056', weight: 1 },
  { id: '6362666072115564544', weight: 2 },
  { id: '6363488681244622848', weight: 3 },
  { id: '6363735117617217536', weight: 4 },
  { id: '6362674737212084224', weight: 5 }
];

morphii_show_name

The morphii_show_name property is used to configure if the morphii label is displayed or not. This defaults to true if not set. The property is used when using bi-directional morphiis in the survey.

hidden_action_ids

The hidden_action_ids property is used to configure the Hidden Action Values that are mapped to this question.

  • id: The Hidden Action Value ID to store the selected morphii id.
  • intensity: The Hidden Action Value ID to store the selected morphii intensity.
  • name: The Hidden Action Value ID to store the selected morphii name.
  • part_name: The Hidden Action Value ID to store the selected morphii part name. This is needed for bi-directional morphiis.
  • question: The Hidden Action Value ID to store the question text.
  • comment: The Hidden Action Value ID to store the comment, if one is entered.

NOTE: If a property is omitted or the ID is incorrect, that specific data will not be stored in the SurveyGizmo database.

The id for the Hidden Action Value can be found on the Build tab for the survey.

Hidden Action Id

Example:

var hidden_action_ids = {
  id: 94,
  intensity: 95,
  name: 96,
  part_name: 97,
  question: 98,
  comment: 99
};

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": "57",
    "morphii": {
      "selected": true,
      "weight": "2"
    }
  }
}

The event properties:

  • selection_required_valid: This property indicates that all selection requirements have been met across all morphii widgets on the page.
  • 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 implementation.
    • target_id: The id of the target associated with this widget. For this implementation this will the ID of the SurveyGizmo question associated with the widget. For example, 57.
    • 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.

Morphii Comment Change Callback

The onMorphiiCommentChange function is for custom logic when a user changes text in the morphii widget comment field. The function is passed the morphii comment changed event. This data contains properties to identify the 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": "57",
    "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.
  • 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 SurveyGizmo question associated with the widget. For example, 57.
    • 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.

Hidden Value Action

SurveyGizmo uses Hidden Value Actions to capture/store custom data. A Hidden Value action allows you to capture/store data in your survey that your survey respondents are not able to see, but can be used for gathering data, storing browser information, and even pre-populating questions later in the survey.

Embedded Data

Exporting Survey Data

When exporting SurveyGizmo survey data to a CVS, the morphii data will be included in the export. The columns will map to the Hidden Value Action fields that you created in the survey. The columns names will be the name you assigned to the Hidden Value Action fields.

Data Export

Testing

When testing your SurveyGizmo survey, add the query string parameter preview=true to the survey URL. This will mark reaction results as testing and omit them in final analysis results. For example: https://www.surveygizmo.com/s3/12345678/Integration-Test?preview=true

Integration Functions

This integration currently provides one public function which is used to initialize the integration.

init(params, callback)

This function initializes the integration.

Parameters:

  • params: The parameters defining the integration.
  • callback: A callback for determining if the integration initialized correctly.

Example:

var integrationParams = {
  account_id: '<ACCOUNT ID HERE>',
  client_key: '<CLIENT KEY HERE>',
  additional_info: {
    audience: null, // ['customer', 'employee', 'patient', 'community', 'general', 'other']
    category: null, // ['satisfaction', 'engagement', 'hr', 'mood']
    timing: null    // ['pre-event', 'during-event', 'post-event', 'n/a']
  },
  response_id: '[survey("session id")]',
  survey_id: '[survey("id")]',
  page_id: '[page("id")]',
  callbacks: {
    selection_change: onSelectionChange,
    comment_change: onCommentChange
  },
  questions: [
    {
      id: 57,
      comment: {
        show: true,
        maxlength: 512,
        label: {
          en: 'Please leave a comment'
        }
      },
      slider: {
        show_animation: true,
        anchor_labels: {
          show: true
        }
      },
      instructions: {
        show: true
      },
      morphii_ids: [
        { id: '6202184382145363968', name: { en: 'Excited' } },
        { id: '6362666072115564544', name: { en: 'Delighted' } },
        { id: '6363734358316589056', name: { en: 'Frustrated' } },
        { id: '6362674737212084224', name: { en: 'Surprised' } },
        { id: '6363735117617217536', name: { en: 'Disgusted' } },
        { id: '6363735353273270272', name: { en: 'Worried' } },
        { id: '6363488681244622848', name: { en: 'Disappointed' } },
        { id: '6202184384594837504', name: { en: 'Meh' } }
      ],
      hidden_action_ids: {
        id: 94,
        intensity: 95,
        name: 96,
        part_name: 97,
        question: 98,
        comment: 99
      }
    },
    {
      id: 59,
      comment: {
        show: false
      },
      slider: {
        anchor_labels: {
          show: true
        }
      },
      instructions: {
        show: true
      },
      morphii_ids: [
        { id: '6362666072115564544', name: { en: 'Happy' } },
        { id: '6363488681244622848', name: { en: 'Sad' } },
        { id: '6363734358316589056', name: { en: 'Grumpy' } },
        { id: '6363735353273270272', name: { en: 'Anxious' } },
        { id: '6202184384594837504', name: { en: 'Bored' } }
      ],
      hidden_action_ids: {
        id: 100,
        intensity: 101,
        name: 102,
        part_name: 103,
        question: 104,
        comment: 105
      }
    }
  ]
};

// Create an instance of the morphii integration and call the init function.
var morphiiIntegration = new Morphii.SurveyGizmoIntegration();
if (morphiiIntegration) {
  morphiiIntegration.init(integrationParams, function(error, results) {
    if (error) {
      console.log('integration error: ' + JSON.stringify(error, null, 2));
      alert('There was an error loading the survey. Please try again later.');
    }
  });
}
Tags: documentation survey_integrations