Creating and launching surveys
Embedding surveys on your website
Traitwise API Reference

Creating and Launching Surveys

Please see the video tutorials for an introduction to all aspects of the Traitwise survey application. Once you've viewed these, we recommend you just try it out. Most application elements have popup tooltips to help you along, and if you ever get stuck you can use the in-app feedback mechanism to ask questions and get answers while you work.

Embedding Surveys on your Website

Surveys may be embedded on your own web pages in one of two ways. For standard non-secure websites handling non-sensitive data, the simplest option is to choose the 'Iframe Embed' launch type when configuring a new survey deployment, and copy+paste the HTML code snippet into your page. If however you need advanced configuration features, API access, or are dealing with personal or sensitive data that requires end-to-end encryption, then the 'Secure API Embed' is the right option. The following discussion applies to this type of securely-embedded survey.

Embedding a secure Traitwise survey requires a few simple steps:

  1. Place scripts provided by Traitwise on your server
  2. Configure your survey by editing a local setup file, template provided.
  3. On your webpage, place an Iframe to contain the survey, and make a HTTPS call from your server to ours to set things rolling.

The result of step 3 will be a URL that you set as the "src" attribute of the Iframe that holds the survey. The interactive survey with its configurable user-interface will then simply appear and animate within the Iframe.

See this simple example site and download sample files to get started, or keep reading for more details.


Embedding a Survey: Detailed Intructions

We'll detail the steps required to get a survey working on a server that uses PHP for server-side processing. If you are using another server-side langauge, you can easily adapt these examples to your language, or read further below to gain enough understanding to write your own custom implementations in whatever language you like.

The Traitwise API Reference also contains code examples in a variety of programming languages. See the section on Iframe functions.

Step 1: Place Traitwise Scripts on your Server

The Traitwise survey operates in the context of an Iframe, and as such is limited in how it can interact with your page. This means we rely on you placing some functionality on your server so that the Iframe may communicate with the top-level window of your page. It doesn't really matter where you place these scripts, as long as it is on your server, under the same domain as the page on which the survey will live. You will reference the full URL path to the script(s) when you setup survey parameters in Step 2.

  1. The only required file for your server, regardless of the server-side language you use, is traitwise_iframe_functions.html
  2. For PHP-based websites, you'll also want our php-includes of handy utilities and the php-setup which defines the survey parameters:

Remember that you can see all of these files in action at the simple example site.

Step 2: Configure Your Survey

You configure the survey by defining a set of parameters that both authenticate your account with Traitwise, and determine how the survey looks, what UI components are available, what questions are asked, and what should happen when the survey ends.

For PHP users, you'll simply edit the traitwise.localsetup.php file that you downloaded and placed on your server in Step 1. That file is heavily documented, and you should feel free to experiment with various settings. If you have a question, just shoot us an email.

In other languages, the setup is exactly analagous, differing only in the syntax for assigning values to variable names. Example calls in other languages can be seen at the Traitwise API Reference. See the section on Iframe functions.

Step 3: Creating the Survey Iframe and Calling the Traitwise Server

The survey is implemented as a single Iframe that you'll probably place in a div whose size you control. This Iframe works in conjunction with a script that you must include onto your page, typically in the <head> section with a simple javascript link: 

<script src="https://panels.traitwise.com/hosting/traitwise_iframe_functions.js"><script>

To activate the survey in the Iframe, you need to set it's "src" attribute. The "src" attribute will be a URL pointing to Traitwise that includes information in the query string that indentifies the request as coming from an authenticated user. The URL you need, along with the authentication key, is obtained by performing an HTTPS POST operation from your server to the /hosted/secure_iframe_setup API at Traitwise.

If you are using PHP, the traitwise.inc.php file that you placed on your server in Step 1 contains a function traitwiseSecureIframe() that performs this POST operation, passing along all of the paramters that are defined in traitwise.localsetup.php.

If you are not using PHP, you simply setup the parameters and pass them with the POST to the above API using whatever POST mechanism is afforded by your language of choice. See the API Reference for details.

At this point, your survey should be functioning! If you have any questions or comments, be sure to drop us a line, and remember that this is all illustrated with files you can view and download at the simple example site.


Embedding a Survey: Additional Information

Architectural Overview

  1. When a user loads your page containing a survey, your server makes an HTTPS request to the Traitwise server supplying it with a number of parameters, including but not limited to:
    • your login credentials
    • the "foreign_user_id" -- a string you can use to identify your user
    • display parameters which affect the way that the survey looks
  2. The Traitwise server returns back to you a URL that contains a one-time-use key. This URL becomes the src for the iframe that holds the Traitwise survey.
  3. Your user's web browser then calls the Traitwise server to load the iframe and begin the survey.

This process is also documented at the API Reference for in the Iframe section. If you're using PHP, you can also view the example site where you may download a sample traitwise.localsetup.php file which documents and illustrates the parameters you can send.

Responding to or Tracking Survey Events

The Traitwise survey embedded on your webpage will send your page Javascript notifications any time a user answers a question as well as when the survey has been completed. To receive these notifications, place a function named "twSurveyEventCallback" on the page that contains the survey. This function is passed a single options parameter which contains details about the event. You can use this mechanism to do analytics tracking on each question answered, or to run custom Javascript code when certain conditions are met, such as when the user completes the survey. As a very simple demonstration, the example site defines this function and simply logs the contents of the event to the browser console: 

function traitwiseSurveyEventCallback( options ) {
  console.log( "traitwiseSurveyEventCallback with options: " + JSON.stringify(options) );
}

Sending Email Results at Survey Completion

By specifying one or more email addresses for the parameter 'email_on_survey_complete', you can have each user's results emailed to you immediately after they have completed the survey. You can optionally set conditions for this, such that the email will only be sent when certain conditions are satisfied, such as a user answering in a specific way to certain questions. An example of setting up these parameters can be seen in the file traitwise.localsetup.php, and this parameters and others are documented at the API Reference.

Redirecting to another page at Survey Completion

You may cause the user's browser to redirect to another page, such as a "Thankyou" page, by specifying a destination URL for the parameter 'redirect_on_survey_complete'.

Placing surveys on WordPress or other CMS pages

WordPress and other content-management systems typically allow you to edit the code that will appear on a page, but you may not be able to place this code directly into your HTML. You can choose to embed a "simple" iframe for anonymous surveys directly into HTML, but for more advanced features you'll need to edit the "template" that your page uses for layout. These templates typically execute PHP, so it's a handy place to insert PHP code to setup your Traitwise survey. This example wordpress template references the localsetup and include files specified above, and illustrates initializing and serving a Traitwise survey from a WordPress authored site. You need to use a template with this functionality for any page that hosts a Traitwise survey.

Embedding Traitwise survey results into your website

Embedding interactive results is almost identical to embedding the survey. All of the same files described above are used, and you simply add a display_results=1 parameter to your iframe src, and set the id of your iframe to "traitwiseIframeResults". The sample file below illustrates this. You can also see this working live at the example site on the Embedding Results page.
Example: PHP
customers_page_example_results.php