Unity plugin: running questionnaires

A primary feature of the VERA Unity plugin is the ability to display questionnaires during XR experiments. You can run questionnaires according to what you have set up for your experiment on the VERA web interface, and log participant responses directly from Unity.

Before beginning this section, it may be useful to review the Unity plugin: overview section, which provides an overview of the VERA Unity plugin and its features.

Key takeaways

  • The VERASurveyHelper static C# class provides functions to run questionnaires.

  • Call VERASurveyHelper.StartSurvey to start a questionnaire. There will be options according to the questionnaires you’ve defined on the web interface.

  • Optionally include a onSurveyComplete callback to run code when the participant finishes the questionnaire.

  • Optionally include a runInWeb parameter to control whether the questionnaire is run in the web browser or in VR.

  • VERA automatically handles the display, navigation, and response recording of questionnaires.

// EXAMPLE USAGE OF SURVEYS IN VERA

// Run the "CybersicknessQuestionnaire" survey
VERASurveyHelper.StartSurvey("CybersicknessQuestionnaire", onSurveyComplete: () =>
{
    // This code will run after the survey has completed
    Debug.Log("Participant has completed the survey!");
});

Understanding questionnaires in VERA

In VERA, you can define multiple questionnaires for your experiment during the setup process in the web interface. Each experiment can have any number of questionnaires associated with it, which can then be run at any time during your Unity experiment using the VERA Unity plugin.

A questionnaire can take many forms, such as a demographics questionnaire, a cybersickness questionnaire, a presence questionnaire, or any custom questionnaire you design.

The VERASurveyHelper

The VERA Unity plugin includes a built-in questionnaire helper, called the VERASurveyHelper, which provides a simple interface for running questionnaires during your Unity experiments. The VERASurveyHelper is a static class, meaning it can be accessed from anywhere in your Unity project without needing to create an instance of it.

To start a questionnaire, call the VERASurveyHelper.StartSurvey() function. You’ll need to provide the VERASurveyReference of the questionnaire you want to run - there will always be a VERASurveyReference with the same name as each questionnaire you set up on the web interface, which you can use to reference that questionnaire in your code. For example, if you have a questionnaire called “CybersicknessQuestionnaire” set up on the web interface, you can start that questionnaire in your Unity experiment by calling:

VERASurveyHelper.StartSurvey(VERASurveyReference.S_CybersicknessQuestionnaire);

This StartSurvey function has some optional parameters you can use to control how the questionnaire is displayed and run:

  • onSurveyComplete: A callback function that will run when the participant finishes the questionnaire. This can be used to trigger certain actions after the questionnaire is completed, such as starting the next part of your experiment. If you need to access the responses from the questionnaire, this callback optionally can provide the responses as well.

  • runInWeb: Whether to run the questionnaire in the web browser or in VR. By default, this is set to false, meaning the questionnaire will be run in VR.

  • transportToLobby: Whether to transport the participant to a temporary lobby environment while they are taking the questionnaire. This can be useful to prevent participants from interacting with the main experiment environment while taking the questionnaire.

  • dimEnvironment: Whether to dim the environment while the participant is taking the questionnaire. This can help participants focus on the questionnaire and reduce distractions from the environment.

  • heightOffset: The height offset to apply to the questionnaire UI. This can be used to adjust the position of the questionnaire in the participant’s view. Position is always relative to the participant’s head position.

  • distanceOffset: The distance offset to apply to the questionnaire UI. This can be used to adjust how far away the questionnaire appears from the participant. Distance is always relative to the participant’s head position.

// EXAMPLE USAGE OF SURVEYS IN VERA

// Run the "CybersicknessQuestionnaire" survey
VERASurveyHelper.StartSurvey("CybersicknessQuestionnaire", onSurveyComplete: () =>
{
    // This code will run after the survey has completed
    Debug.Log("Participant has completed the survey!");
});

Web questionnaires vs VR questionnaires

When you start a questionnaire with VERA, you can choose to run it in the web browser or in VR via the runInWeb parameter. By default, this is set to false, meaning the questionnaire will be run in VR.

If you set runInWeb to true, the questionnaire will be run in the web browser. Upon initiating the start questionnaire function in this way, the participant will be temporarily disconnected from immersive VR mode, and the questionnaire will be automatically displayed in the participant’s web browser. They are then asked to complete the questionnaire, and once they submit their final response, they will be automatically re-connected to immersive VR mode and placed back in your VR environment.

If you set runInWeb to false or use the default value, the questionnaire will be run in VR, fully in immersive mode. A world-space UI interface will be displayed in front of the participant, tracking their view direction and distance, and following them as they move around the environment. Participants will be asked to complete the questionnaire, navigating it using their hand controllers. Once they submit their final response, the questionnaire interface will automatically disappear, and the experiment may continue.

Both types of questionnaire displays are valid for different use cases; it might be easier for a participant to complete a questionnaire in the web browser, but it might be more immersive to display the questionnaire in VR. It is important to note that the questionnaire content will always be displayed in the same way regardless of whether it is run in the web browser or in VR - the only difference is the context in which the questionnaire is displayed.

Fetching existing questionnaire responses

To get the responses from an existing questionnaire, you can use the static function VERASurveyHelper.GetSurveyResponses. To use this function, provide the VERASurveyReference enum value for the questionnaire you want to fetch responses for, and the responses will be passed to the onSuccess callback.

Optionally, you can provide a sessionNumber to filter results to a specific session (i.e. 0, 1, 2…), or a specific instanceNumber to filter results to a particular run of that survey (1 for first run, 2 for second run, etc.). You can also optionally utilize the onFailure callback to handle failure of the operation.

// Fetch all responses from a survey named "MySurvey" for the current active participant
VERASurveyHelper.GetSurveyResponses(VERASurveyHelper.VERASurveyReference.MySurvey, (responses) => {
    Debug.Log("Survey responses: " + responses);
});

// Fetch the responses from a survey named "MySurvey" for the second instance of the second session for this participant
VERASurveyHelper.GetSurveyResponses(VERASurveyHelper.VERASurveyReference.MySurvey, sessionNumber: 2, instanceNumber: 2, (responses) => {
    Debug.Log("Survey responses for session 0: " + responses);
});

Note that this function will only fetch responses from questionnaires that have already been completed by the participant. If you want to fetch responses from a questionnaire that has not yet been completed, use the VERASurveyHelper.StartSurvey function as outlined above to get responses from a questionnaire when it is completed.

Next steps

Next, consider exploring the Unity plugin: logging data section, which explains how to log CSV data during your Unity experiments using the VERA plugin. Additionally, consider exploring the Unity plugin: managing conditions section, which explains how to set up and manage experimental conditions in your Unity experiments using the VERA plugin.

For a quick reference guide to using the VERA Unity plugin, which includes a list of the functions outlined above, see the Unity plugin: quick reference section.