Examples

Basic Usage

<html>
<head>
    <script type="text/javascript" src="https://www.socratesinsights.com/itb/ajax/standard/1.0.0/itb.js"></script>
    <script type="text/javascript">
        function collectData(xml) {
            // Parse xml with JavaScript or send to server
            // to parse with Java, .NET, etc…
        }
    </script>
</head>
<body>
    <script type="text/javascript">
        Quester.loadITB({
            "projectId"  : "EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID",
            "externalId" : "8999233",
            "question"   : "How was your day?",
            "jsFunction" : "collectData"
        });
    </script>
</body>
</html>

Look and Feel

The ITB was designed so that Quester could modify the look and feel as easily as possible, while still providing a robust layout that is compatible with virtually any browser version. The partner may create a cascading style-sheet (CSS) to change many visual features of the ITB, allowing the ITB to fit seamlessly into the partner’s survey platform. Features that the partner may modify include:

  • Width and height
  • Font size, color, weight, and style
  • Border style and size
  • Button style

The complete URI to the partner’s CSS for ITB modifications will need to be passed into the ITB as an optional variable (further explained below). The overall width and height can also be changed by passing them into the ITB as optional variables. These two variables may cause strange behavior when combined with CSS modifications that also affect the width and height of the ITB. It is recommended that either the width/height be passed in as variables without CSS modifications or that they are placed in the CSS.

Standard Theme Width/Height

You may pass the width and height variables to the Quester.loadITB() call to resize the Standard ITB.

Quester.loadITB({
    "projectId"  : "EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID",
    "externalId" : "8999233",
    "jsFunction" : "collectData",
    "width"      : 600,
    "height"     : 320
});

Standard Theme Custom CSS

You may change the look of the Standard ITB with custom css. To do this, make your custom css available on your server somewhere and pass the url to the Quester.loadITB() call. This will ensure that your css is loaded after ours, so your changes take precedence.

/* Make respondent response the same color as previous question. */
#itb div.ui-socrates-conversation-respondent { color: #c0c0c0; }
#itb div.ui-socrates-conversation-respondent-text { color: #808080; }
Quester.loadITB({
    "projectId"  : "EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID",
    "externalId" : "8999233",
    "jsFunction" : "collectData",
    "css"        : "http://mydomain.com/ITBstyle.css"
});

Blank Theme

You may use the Blank ITB if you wish to integrate the ITB seamlessly into your survey platform. The Blank ITB requires additional steps to setup:

  • Create a container where the question/probes will be displayed
  • Create an input where the respondent will enter their response
  • Create an element the respondent can click to submit their responses
  • Pass the ids to these three elements to the Quester.loadITB() call
  • Call Quester.loadITB() after the page is loaded

The ITB will attach itself to these elements to handle the conversation, giving you full control over the layout and look of the ITB.

The Blank ITB does not show previous questions/responses like the Standard ITB does. If you would like emulate this functionality with the Blank ITB, you will need to handle that with custom javascript.

<html>
<head>
    <script type="text/javascript" src="https://www.socratesinsights.com/itb/ajax/blank/1.0.0/itb.js"></script>
    <script type="text/javascript">
        function collectData(xml) {
            // Parse xml with JavaScript or send to server
            // to parse with Java, .NET, etc…
        }

        function loadITB() {
            Quester.loadITB({
                "projectId"  : "EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID",
                "externalId" : "8999233",
                "question"   : "How was your day?"
                "jsFunction" : "collectData",
                "questionId" : "question",
                "responseId" : "response",
                "sendId"     : "send"
            });
        }
    </script>
</head>
<body onload="loadITB">
    <div id="question"></div>
    <textarea id="response"></textarea>
    <button id="send">send</button>
</body>
</html>

Response XML

The response data is passed to your jsFunction in the form of a xml string upon completion of the ITB. Parsing the xml string is the responsibility of the partner and will depend on the environment and server technology the partner is using. Libraries for parsing XML are available in most server side (Java, .NET, PHP) and partner side (JavaScript, VBScript) programming languages.

The XML needs to be parsed in real time as it will include variables and status codes which need to be used in order to set up the next ITB instance. Each status code that you may encounter is described below. We have provided a schema that you may wish to use for validation, code generation, documentation, etc..

1.0 Session Complete

Status code 1.0 is returned when the ITB has completed the current question/probe session successfully. The conversation is included in the response xml.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>1.0</status>
    <respondentId>EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID</respondentId>
    <conversation>
        <question timestamp="05/23/2013 09:32:30 AM">How was your day?</question>
        <response timestamp="01/01/2009 09:32:52 AM">It was the day I was meant to have.</response>
        <question timestamp="05/23/2013 09:32:54 AM">Do tell...</question>
        <response timestamp="01/01/2009 09:33:07 AM">I spilled coffee on my keyboard.</response>
    </conversation>
</itbResponse>

1.1 Session Suspended

Status code 1.1 is returned when the current question/probe session has been suspended and the respondent should continue through your study. This can occur in custom projects that involve multiple ITB instances. You will need to save the respondentId for those subsequent ITB instances. The conversation is included in the response xml.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>1.1</status>
    <respondentId>EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID</respondentId>
    <conversation>
        <question timestamp="05/23/2013 09:32:30 AM">How was your day?</question>
        <response timestamp="01/01/2009 09:32:52 AM">It was pretty good.</response>
        <question timestamp="05/23/2013 09:32:54 AM">Do tell...</question>
        <response timestamp="01/01/2009 09:33:07 AM">IT fixed my keyboard.</response>
    </conversation>
</itbResponse>

2.0 Session Expired

Status code 2.0 is returned when the respondents session has expired. This will occur if you attempt to show an ITB using a respondentId for a respondent that has a completed session. This may also occur if the respondent sits on a question for a very long time.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>2.0</status>
</itbResponse>

2.1 Respondent Terminated

Status code 2.1 is returned when the respondent indicates that they are finished with the current ITB session (using language such as “I’m done”, “no more time”, etc.) The conversation is included in the response xml.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>2.1</status>
    <respondentId>EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID</respondentId>
    <conversation>
        <question timestamp="05/23/2013 09:32:30 AM">Do you have time to talk today?</question>
        <response timestamp="01/01/2009 09:32:52 AM">I do have time to talk today.</response>
        <question timestamp="05/23/2013 09:32:54 AM">Are you sure?</question>
    </conversation>
</itbResponse>

2.2 Respondent Unresponsive

Status code 2.2 is returned when the respondent is unresponsive (using empty or junk responses.) The conversation is included in the response xml.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>2.2</status>
    <respondentId>EXAMPLE-flGNpfoYD6rTrIESiFkg8JabMG9k3c-NOT-VALID</respondentId>
    <conversation>
        <question timestamp="05/23/2013 09:32:30 AM">What is the answer to life the universe and everything?</question>
        <question timestamp="05/23/2013 09:32:31 AM">I'm sorry ... I missed that ... please go on.</question>
        <question timestamp="05/23/2013 09:32:32 AM">I apologize, but I don't understand what you are trying to say ... please help me out.</question>
        <question timestamp="05/23/2013 09:32:33 AM">We still don't seem to be communicating very well ... our conversation will flow much more smoothly if you could provide more detail in your responses. Please tell me more.</question>
        <question timestamp="05/23/2013 09:32:34 AM">I'm sorry, Respondent, but I will not be able to continue our conversation unless you can help me understand your thoughts.</question>
        <question timestamp="05/23/2013 09:32:35 AM">It appears as though we are still not understanding each other ... let's try one more time before we end our conversation. Please help me understand your thoughts by providing a more detailed response, otherwise, I will need to terminate our interview.</question>
    </conversation>
</itbResponse>

3.0 Invalid ProjectId or RespondentId

Status code 3.0 is returned when an invalid projectId or respondentId is used to show the ITB.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>3.0</status>
</itbResponse>

3.1 SSL Is Not Enabled

Status code 3.1 is returned if you attempt to show the ITB using HTTP instead of HTTPS.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>3.1</status>
</itbResponse>

10.x Service Error

Status code 10.x is returned if a service error occurs during the respondent’s session with the ITB instance.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>10.0</status>
</itbResponse>

11.x Quester System Message

Status code 11.x is returned if a setup error is detected during the respondent’s session with the ITB instance. Perhaps the study has been closed or is no longer available. These messages generally indicate a setup problem and you should contact Quester for assistance resolving them.

<?xml version="1.0" encoding="UTF-8"?>
<itbResponse>
    <status>11.5</status>
</itbResponse>