Embedding Voxpopme in Sparq3 (Alida)

This article gives a simple 5 step guide on how to embed Voxpopme into the Sparq3 platform.

Step 1: Voxpopme Project creation

All new projects require a project to be created through the Voxpopme Portal. Please see our document How to set up your Embed project in the Portal if you would like to complete this step first or keep reading if you have been sent the Javascript already by your Voxpopme Project Manager.

Step 2: Insert Voxpopme embed code into your survey

Now armed with your Voxpopme Project ID and Sparq3 survey you are ready to incorporate the Voxpopme embed code. The embed code has been designed for easy integration and requires only slight modification once embedded.

First, create a Survey and add the Embedded Content step to it.

Next, you will need to add in the Javascript embed code. Copy the embed code below into the Embedded Content box. Update any invalid pipe references with real ones (they will show up with a name "Invalid Pipe" when the script is copied in because the identifier for their pipes will be different). This is really easy using the following "Add a pipe" option - 

Example I would like to add Member ID -

The above generates the Merge code needed for MemberId and you can see all options easily.

When the survey is previewed from the Survey Build interface the value for MemberId will be empty as there is no member context when previewing the survey. You can enter a test value for the MemberId while previewing it. 

<br>
<div id="messageDiv"></div>
<div class="vpm-capture-widget"></div>
<br>
<br/><input type="checkbox" id="checkboxAbort">I am having technical difficulties or would no longer like to record</input>

<style>
#Back { 
 visibility:hidden;
 }
</style>
<script>
 //Enter in your project Id
 var _projectId = "[Project ID]";
 
 //set the locale code to configure voxpopme with
 var _locale = "[Language]";
 
 //define the minimum and maximum recording time
 var _minRecordingTimeInSeconds = 15;
 var _maxRecordingTimeInSeconds = 120;
 
 //pipe in some member data. 
 //Note: when you paste this sample into your survey you will be required to update the pipes with valid ones using the pipe control {}. 
 //Do not remove the quotation marks when replacing the pipe token 
 var _memberId = "[%MemberId|44029f77-e9c6-4b32-807e-23f0ef1a43ef%]";
 var _firstName = "[%firstname|urn:vc:datapoint:member-variable:b17ea76d-b744-47ce-8797-a9b501707c0d:value%]";
 var _lastName = "[%lastname|urn:vc:datapoint:member-variable:f47266ac-26bd-479b-9db9-a9b501707c10:value%]"
 
 //provide initial messaging to survey respondent when the step loads 
 setMessage("Please be patient while the video capture component is loading");

var vpm_widget_config = {
  project_id: _projectId,
  additional_data: {
  'MemberId': _memberId,
  'first_name': _firstName,
  'last_name': _lastName
   },
   settings: {
   locale: _locale,
   min_recording_time: _minRecordingTimeInSeconds,
   max_recording_time: _maxRecordingTimeInSeconds
   }
 };
 
 !function(a, b, c, d) {
 function e() {
   var a = b.createElement(c);
   a.type = "text/javascript", a.async =! 0, a.src = d;
   var e = b.getElementsByTagName(c)[0];
   e.parentNode.insertBefore(a, e)
 }
 a.attachEvent ? a.attachEvent("onload", e) : a.addEventListener("load", e, !1)
 }
 (window, document, "script","https://capture.voxpopme.net/main.js");
 
 //hook up the checkbox handler so the page will move back to option page to record video, text response, etc
 document.addEventListener("DOMContentLoaded", function(event) {

 //disable the Next button 
 var nextCheck = setInterval(function () {
  if (document.getElementById("Next")) {
   document.getElementById("Next").style.display = "none";
   clearInterval(nextCheck);
  }
 }, 50);

 var checkbox = document.getElementById("checkboxAbort");

checkbox.onchange = function() {
if (checkbox.checked) {
 setEmbeddedContentComplete();
 } else {
 setEmbeddedContentIncomplete();
 }
}
});

//this code is used to listen for events from the iframe
 var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
 var eventer = window[eventMethod];
 var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";

// Listen to message from child window (iframe)
 var onlyStrings = false;
 
 try {
   window.postMessage({
   toString: function(){
   onlyStrings = true;
  }
  }, "*");
 } 
 catch (e){
 }

//handle events raised by Voxpopme and update messages and the completion state of the step as necessary. 
 eventer(messageEvent, function (e) {
 if (e.data) {
 var eventData = {};
 if (typeof e.data === 'string' && onlyStrings) {
   eventData = JSON.parse(e.data);
 }
 else {
   eventData = e.data
 }
 
 setEmbeddedContentIncomplete();
 
 if ('initialized' == eventData.event) {
   setMessage("Video capture is ready for you to record your feedback.");
 }
 if ('serverDisconnected' == eventData.event) {
   setMessage("We are sorry. Connection to the server was lost. Please check that you are connected to the Internet and try again.");
 }
 if ('noCamera' == eventData.event) {
   setMessage("No video recording device was found.");
 }
 if ('cameraDenied' == eventData.event) {
   setMessage("Please grant access to your camera and then refresh the page.");
 }
 if ('noMic' == eventData.event) {
   setMessage("No microphone was found.");
 }
 if ('readyToRecord' == eventData.event) {
   setMessage("You must provide at least " + _minRecordingTimeInSeconds + " seconds of feedback before continuing.");
 }
 if ('recordingStarted' == eventData.event) {
   setMessage("Recording has started.");
 }
 if ('recordingStopped' == eventData.event) {
   setMessage("Please be patient while your video is uploaded.");
 }
 if ('publishFailed' == eventData.event) {
   setMessage("We are sorry. Your video failed to upload due to technical difficulties.");
 }
 if ('response_complete' == eventData.event) {
   handleSuccess("Thank you for your feedback. Please continue with the survey.");
 }
 }
 }, false);
 
 
 /*Displays errors and sets step's state to complete so the Next button is enabled. */
 function handleError(message) {
   setMessage(message);
   setEmbeddedContentComplete();
 }
 
 /*Displays success message and sets step's state to complete so the Next button is enabled. */
 function handleSuccess(message) {
   setMessage(message);
   setEmbeddedContentComplete();
 }
 
 /*Mark the step as incomplete so Next button is disabled and the checkbox to abort is enabled.*/
 function setEmbeddedContentIncomplete() {
   document.getElementById("Next").style.display = "none";
 }
 
 /*Mark the step as complete so the Next button is enabled.*/
 function setEmbeddedContentComplete() {
   document.getElementById("Next").style.display = "block";
 }
 
 /*Present the message to the Survey Respondent*/
 function setMessage(message) {
   document.getElementById("messageDiv").innerHTML = message;
 }

</script>

Step 3: Customize the embed code

The Embed Javascript requires modifications to meet your project specifications. The fields requiring changes are highlighted above. When replacing a field, remember to remove the brackets. Details on the variables that require customization are explained below.

• [Project ID] - the “Project ID” allows the capture widget to sync videos captured with the appropriate project in the your Voxpopme portal. To set your project id, replace the [Project ID] with the unique Project ID for your Voxpopme video project, eg. var _projectId = "2cdaf2b8f505682a10c602d56abe5b5a". See "Step 1" (above) if you don't have your "Project ID".
• [Language] - setting the country code will assure we have the right language for each video captured. This is important for transcriptions and translations. Voxpopme supports over 40 languages. The languages we support and their codes can be found here.

To set your language, insert the appropriate country code between the "" where [Language] is found. See below for an example. 

Step 4: Appending Data

• Ensure you are passing through additional data to the Voxpopme portal. At minimum we recommend passing through a unique identifier so the survey results can be tied to the videos captured. The embed code above includes appended data capture titled ‘additional_data’. The name of the variable is shown on the left-hand side, the appropriate piped text for passing through additional data within the survey is on the right in quotation marks. MemberID, first name, and last name are already included in the Javascript above.
• Additional Survey Variables: Pass through as much additional data as you would like to the Voxpopme platform. To add a new piece of additional data you will need to add a comma at the end of last additional data line. If you’re passing through a survey response as additional data, use the same piped text you would use to pipe that response into another survey question. 

Step 5: Publish & Test

The last step is to save the changes made and test. While testing the video capture and additional data passthrough for your survey, be sure to say “testing” in your video or cover your camera. This will let our QA team know to decline the video. Below are instructions on how to view the additional data in the portal, and how to see declined test videos to confirm data has passed through correctly.

View additional data in portal: To view the additional data in the project, click into your project and click the additional data button (see screenshot below). The additional data will show up beneath each response’s transcript.

 

View Declined Videos: If your test video is awaiting approval, you can skip this step and use the instructions above to view the additional data. If you don’t see your test video, it was likely declined by our QA team, which prevents the video from being sent for transcription. You can see these videos by using the Filter and setting Declined to True. See screenshot below:

Additional Information

Technical Difficulties

Because the embed code will disable the 'Next' button within the survey until the respondent has successfully uploaded a video response, we recommend adding a technical difficulties option in case a respondent is unable to record a video or decides they no longer wish to record. This is included in the sample javascript and if checked it will enable the next button allowing the user to progress through the survey.

This is how the video record page will look in your survey -

Checking the Project Quota

If you would like to prevent the respondent from seeing the video question once the video quota has been met, follow the instructions in the following link: Checking the quota

Changing the Recording Time

By default, the widget allows respondents to record responses between 15 and 60 seconds. To change the minimum and maximum recording time capture widget please check with your contact at Voxpopme.

Practical tips for higher conversion rates

Read our document for tips on how to gain higher conversion rates.

FAQ

Q: What if I have multiple languages in my study?

A: When expecting responses in multiple languages users will need to embed multiple instances of the capture widget (one for each language). Branching in the survey can be used to serve up the right respondents with the corresponding language. The same Project ID can be used, this will ensure all responses fall under the respective project in the Voxpopme portal.

Q: Can I append data that is captured after the video question?

A: Yes, to see instructions on passing through variables that have been captured after the video embed please see here.

Q: Is there a limit to the number of additional variables I pass through?

A: No. You can pass through as many variables as needed. We recommend passing through a unique ID, along with any data that will be useful for filtering/sorting videos, captioning your showreels, or generally assisting with your analysis.