Unity plugin: quick reference
This section provides a quick reference guide for the VERA Unity plugin, summarizing its key components and features for easy access. For a more detailed overview of the VERA Unity plugin, refer to the Unity plugin: overview section.
Setup and general management
VERA Unity package import and URL
The VERA Unity plugin is distributed as a Unity Package Manager (UPM) package. To import the package into your Unity project, use the following UPM package URL:
VERA Unity package URL
You can add this package to your project by navigating to Window > Package Management > Package Manager in Unity. Click the + icon in the top left corner and select Add package from git URL…. Paste the UPM package URL into the dialog box and click Add to import the VERA Unity plugin into your project.
VERA settings and authentication
To access the VERA Settings window, navigate to VERA > Settings in the Unity menu bar.
In this window, you can authenticate your Unity project with your VERA account, select your active experiment, and configure other general settings.
VERA help guide
To access the VERA Help Guide window, navigate to VERA > Help in the Unity menu bar.
In this window, you’ll find a quick reference guide for the VERA Unity plugin, as well as links to the full documentation and other helpful resources.
Files and data logging
VERAFiles and preprocessor directives
A static Unity C# class is automatically generated for each file type you define on the web interface for your selected experiment. These classes and their associated functions allow you to log data directly from your Unity application. They will be named with the prefix VERAFile_, followed by the name of your file (e.g., VERAFile_MyFile).
There is always a preprocessor directive available to check if a particular generated file exists: #if VERAFile_[YourFileName]. This can be useful to prevent compiler issues when swapping experiments.
// Example of using a preprocessor directive to conditionally run code based on the existence of a VERAFIle
#if VERAFile_MyFile
// This code will only run if the "MyFile" VERAFIle exists
#endif
Logging data to VERAFiles
Use the static function VERAFile_[YourFileName].CreateCsvEntry([YourData]) to log a single CSV entry to the specified file. This function is strictly typed according to your file type, ensuring that the data you provide matches the expected format.
Data is automatically uploaded to the web interface every 3 seconds. You do not need to manually handle data uploads. You will be notified via the Unity console if there are any issues with data logging or uploading.
// Log a CSV entry to a file named "PlayerActions" with columns for Time (float) and Action (string)
#if VERAFile_PlayerActions
float currentTime = Time.time;
string actionPerformed = "Jump";
VERAFile_PlayerActions.CreateCsvEntry(currentTime, actionPerformed);
#endif
Session management
The VERA session manager
The VERA session manager is your primary interface for managing participant sessions.
You can access this static class, VERASessionManager, to conclude participant sessions, manage VERA initialization, and check session states.
Initialization and session states
The VERA session manager provides several events and variables to help you manage session states:
onInitialized: A UnityEvent that is triggered when VERA has been initialized and is ready for use.
initialized: A boolean variable indicating whether VERA has been initialized and is ready for use.
collecting: A boolean variable indicating whether data is able to be actively collected based on session state.
// Subscribe to the onInitialized event
VERASessionManager.onInitialized += OnVERAInitialized;
// Event handler for VERA initialization
private void OnVERAInitialized()
{
Debug.Log("VERA has been initialized and is ready for use.");
}
Participants and participant IDs
Each participant session is assigned a unique participant ID, which can be accessed via the VERASessionManager.participantID variable.
This ID is used to associate all logged data with the correct participant session on the web interface. It will be a short integer value, typically starting from 1 and incrementing for each new session.
This ID is handled automatically. You do not need to assign your own participant IDs, unless you have specific requirements for your experiment.
// Access the current participant ID
int currentParticipantID = VERASessionManager.participantID;
Finalizing a participant session
To properly conclude a participant session and ensure all data is uploaded, call the VERASessionManager.FinalizeSession() function. This will finalize the session and upload all recorded data to the web portal.
This function should always be called once at the end of the experiment. This will stop all data collection and ensure all data is properly synced with the web interface. If you are using VERA’s remote distribution features / WebXR interface, this function will also signal the participant’s browser to close the WebXR session.
// Finalize the current participant session
VERASessionManager.FinalizeSession();
Storing and retrieving memory between sessions
The VERA session manager provides functions for storing and retrieving lightweight string-based key-value memory between sessions. This memory is saved for the participant as a whole - it will remain stored between sessions, and changing the value of a key will change it across all sessions, not just the current session.
This can be useful for longitudinal experiments where storing information between sessions is useful, such as a participant’s group assignment, demographic information, or survey responses.
// Example: Store a participant's group assignment
VERASessionManager.SetMemoryKey("groupAssignment", "A");
// Example: Retrieve a participant's previously stored group assignment
VERASessionManager.GetMemoryKey("groupAssignment", (groupAssignment) => {
Debug.Log("Participant's group assignment: " + groupAssignment);
});
Custom WebXR URL parameters
VERA allows custom URL parameters to be passed from your participants’ WebXR sessions directly to Unity. This can be useful for passing participant-specific information to your experiment, such as encoded group assignment, custom IDs, or other information.
To pass a custom URL parameter, first simply append the parameter to your participant’s WebXR URL as you would any other URL parameter. For example, if you want to pass a custom parameter called “groupAssignment” with value “A”, and your custom remote distribution URL was “vera-xr.io/remote/abc123”, you could pass the parameter by appending the parameter like this:
vera-xr.io/remote/abc123?groupAssignment=A
Then, in Unity, you can use the VERASessionManager.GetUrlParameter(string key) function to get a specific URL parameter:
// Fetch the "groupAssignment" URL Parameter, if it exists
string groupAssignment = VERASessionManager.GetUrlParameter("groupAssignment");
Debug.Log("Group assignment: " + groupAssignment);
You can also use the GetAllUrlParameters function to get all URL parameters as a Dictionary. Additionally, an areUrlParametersReceived field and onUrlParametersReceived callback have been provided to ensure URL parameters have properly loaded if necessary before calling the getters.
Managing conditions
VERAIV classes and preprocessor directives
A static Unity C# class is automatically generated for each independent variable (IV) you define on the web interface for your selected experiment. These classes and their associated functions allow you to get the current value of an IV or set a new value for it. They will be named with the prefix VERAIV_, followed by the name of your IV (e.g., VERAIV_MyIV).
There is always a preprocessor directive available to check if a particular generated file exists: #if VERAIV_[YourIVName]. This can be useful to prevent compiler issues when swapping experiments.
// Example of using a preprocessor directive to conditionally run code based on the existence of a VERAIV
#if VERAIV_MyIV
// This code will only run if the "MyIV" VERAIV exists
#endif
IVValue enum
For each of your independent variables (IVs), an enum is generated to represent the possible values that IV can take. Getting and setting IV values is strictly typed using these enums.
Getting and setting IV values
Use the static functions VERAIV_[YourIVName].GetSelectedValue() and VERAIV_[YourIVName].SetSelectedValue([YourValue]) to get and set IV values, respectively.
// Get the current value of an IV named "Weather"
#if VERAIV_Weather
VERAIV_Weather.IVValue currentWeather = VERAIV_Weather.GetSelectedValue();
#endif
// Set a new value for an IV named "Weather"
#if VERAIV_Weather
VERAIV_Weather.SetSelectedValue(VERAIV_Weather.IVValue.Sunny);
#endif
Running questionnaires
The VERASurveyHelper
The VERASurveyHelper is a static Unity C# class that provides functions for running questionnaires that you have defined on the web interface.
It will have a VERASurveyReference enum value defined for every questionnaire you have added to your experiment on the web interface, which you can use to specify which questionnaire to run.
Running a questionnaire
Use the static function VERASurveyHelper.StartSurvey([YourSurveyReference]) to run a questionnaire in your Unity application. This will open the specified questionnaire in the participant’s web browser, allowing them to complete it.
// Run a survey named "PostExperimentSurvey"
VERASurveyHelper.StartSurvey(VERASurveyHelper.VERASurveyReference.PostExperimentSurvey);
Running code after questionnaires complete
The VERASurveyHelper.StartSurvey function has an optional parameter for a callback function that will be executed once the participant completes the questionnaire and submits their responses.
// Run a survey named "PostExperimentSurvey" and execute a callback function after completion
VERASurveyHelper.StartSurvey(VERASurveyHelper.VERASurveyReference.PostExperimentSurvey, onSurveyComplete: () =>
{
// Code to execute after the survey is completed
Debug.Log("Survey completed!");
});
Running questionnaires in the web browser
The VERASurveyHelper.StartSurvey function has an optional runInWeb parameter which can be set to run the questionnaire in the web browser or in immersive VR mode. By default, this is set to false, meaning the questionnaire will be run in immersive VR mode.
Questionnaires run in the web browser will be displayed in the participant’s native device browser, which may be more convenient or easier to fill out, but might not be as immersive as running the questionnaire in immersive VR mode.
Fetching survey 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.
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 and wait for the onSurveyComplete callback to be called.
// 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);
});