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.
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:
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.
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.
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.
Remember that you can see all of these files in action at the simple example site.
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.
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.
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.
function traitwiseSurveyEventCallback( options ) { console.log( "traitwiseSurveyEventCallback with options: " + JSON.stringify(options) ); }
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.