Contents

Interaction.ShowSurvey

Method

ShowSurvey

ModuleInteraction
LibraryCore
Action

Display a pop-up survey to one or more user sessions.

The pop-up includes questions text followed by a set of selectable choices, and an optional free text box.

Parameters









AllowFreeText (boolean): Indicates whether a text box should be included with the survey to allow input of free text comments.

If set to true and free text is supplied in the user response, then it is returned in the FreeText field.

Async (boolean): Whether to run the method synchronously or asynchronously.

In synchronous mode the method will only return once all user sessions have responded or have timed out.
In asynchronous mode, the method returns immediately and results will appear as events as user sessions respond or timeout.

Choices (string): A table of ordered choices to be displayed as part of this pop-up survey.

The table consists of rows of Text strings, and optionally a Color value may be associated with each entry.
The Color value can be either a RGB hex code such as '#bf930f' or a color description such as 'blue'.
The order of the choices determines the response value that is returned when a choice is made; for details see ResponseValue below.

FreeTextLabel (string): If AllowFreeText is true, then this can be used to set an alternative label for the free text field of the survey.

Default value; "Anything more you'd like to tell us?"

Link (string): A URL which will appear as a 'Click here to find out more' link within the survey.

Name (string): Name of the survey.

This is used to uniquely identify the survey, and prevent repeat showing of the same survey.

Question (string): Question text that will be displayed as part of this survey.

ResponseValidityMinutes (integer): A Response validity period in minutes.

The maximum value allowed is 129600 minutes (90 days). Default is 0 which means survey maximum validity period of 90 days will apply.

Response Validity is a way to avoid repeatedly presenting a user with the same survey. When a user provides an answer to a survey, the response they give is deemed to be "valid" for the duration specified here. You may then use the Interaction.GetActiveResponses method to test whether there is already a valid answer for a particular user/survey; if there is, you may wish to avoid calling Interaction.ShowSurvey and instead use their existing answer.

Once the response validity period has elapsed, the response is no longer marked as valid, and will not appear in the table returned by Interaction.GetActiveResponses.

You can force the one or more responses to be invalidated for a user/survey immediately by using the Interaction.InvalidateResponse method.

TimeoutSeconds (integer): The number of seconds before the survey will timeout.

Minimum value is 30 seconds, maximum value is 900 seconds and default value is 60 seconds.

Topic (string): In asynchronous mode, this must be supplied and is the name of the event that will be raised when a user response is obtained.

In synchronous mode this is not relevant and should not be supplied.

UserName (string): Username of the session to which this survey should be directed. If Username is not supplied then the survey will be directed at all active user sessions.
Return values

FreeText (string): Free text that was supplied as part of the user response.

Response (string): Text of the selected choice.

ResponseType (string): Indicates whether the user responded or failed to respond before the survey timed out.

Values are: "dismissed", "responded", "snoozed", "timed out", "invalid".

ResponseValue (double): The value of the response chosen by the user.

The highest ordered choice (first in the table of choices) will have a response value of 1.
The lowest ordered choice (last in the table of choices) will have a response value of 0.
Those in between will be allocated a fractional value between 1 and 0 relative to their position.
For example, if the choices are: (Great, Good, Average, Poor, Terrible) then these will be scored:
Great=1.0, Good=0.75, Average=0.5, Poor=0.25, Terrible=0.

UserName (string): Username of the logon session associated with this response.
Example
@a = SELECT "Very Happy" AS Text, "green" AS Color
     UNION ALL
     SELECT "Happy" AS Text, "#bf930f" AS Color
     UNION ALL
     SELECT "Indifferent" AS Text, "blue" AS Color
     UNION ALL
     SELECT "Quite unhappy" AS Text, "orange" AS Color
     UNION ALL
     SELECT "Very Unhappy" AS Text, "red" AS Color;

// Synchronous survey to a single user session.
Interaction.ShowSurvey(Async:false, Choices : @a, Name:"User Experience Survey",
        Question : "How happy are you with your user experience?",
        UserName:"acme\\development", AllowFreeText: true, FreeTextLabel: "Please elaborate");

// Asynchronous survey to all user sessions on this device and include a free text box.
Interaction.ShowSurvey(Async:true, Choices : @a, Name:"User Experience Survey",
        Question : "How happy are you with your user experience?",
        AllowFreeText: true, FreeTextLabel: "Please elaborate", Topic:"MyExperienceSurvey");
Platforms
  • Windows
Notes

Available from v5.1.