Unity plugin: managing sessions

A primary feature of the VERA Unity plugin is the ability to manage participant sessions during XR experiments. Participant sessions represent single individual participants taking part in your experiment. Each session is associated with a unique participant ID, which is used to track and log data for that specific participant.

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

  • A participant “session” is a single individual participant taking part in your experiment, associated with a unique participant ID (pID).

  • The VERA Unity plugin includes a built-in session manager, called the VERASessionManager.

  • Use VERASessionManager.participantID to get the participant’s ID.

  • Use VERASessionManager.initialized and .onInitialized to check if VERA is ready.

  • Always call VERASessionManager.FinalizeSession() to finish your participants’ sessions.

// EXAMPLE USAGE OF SESSION MANAGEMENT IN VERA

// Subscribe to the onInitialized event to know when VERA is ready
VERASessionManager.onInitialized.AddListener(() =>
{
    Debug.Log("VERA is initialized and ready to use!");

    // Get the participant's ID
    int participantID = VERASessionManager.participantID;

    // Finalize participant session and mark them as COMPLETE
    VERASessionManager.FinalizeSession();
});

Understanding VERA participant sessions

In VERA, a single Participant Session represents a single individual participant taking part in your experiment. Each session is associated with a unique participant ID (pID), which is used to track and log data for that specific participant.

When a participant begins your experiment, a new participant session is created on the VERA web interface, and all data logged during that session will be associated with that participant. When a participant completes your experiment, their session is marked as complete on the VERA web interface, and no new data can be recorded to that session.

Every participant session is marked with a particular status, which indicates the current state of that session. The possible statuses for a participant session are as follows:

  • Created: The session has been created, but the participant has not yet begun the experiment.

  • In Progress: The participant is currently taking part in the experiment, and data is being logged.

  • Completed: The participant has completed the experiment successfully, and no new data can be recorded to that session.

  • Incomplete: The participant has exited the experiment preamturely, lost connection, or otherwise failed to complete the experiment gracefully.

  • Withdrawn: The participant has chosen to withdraw from the experiment, and their data should not be used.

The VERASessionManager

The VERA Unity plugin includes a built-in session manager, called the VERASessionManager, which provides a simple interface for managing participant sessions during your Unity experiments. The VERASessionManager is a static class, meaning it can be accessed from anywhere in your Unity project without needing to create an instance of it.

The VERASessionManager allows you to get information about the state of the current participant session:

  • int participantId: Gets the unique participant ID (pID) for the current session.

  • UnityEvent onInitialized: An event that is invoked when the participant session has been successfully initialized.

  • bool initialized: A boolean value indicating whether the participant session has been initialized.

  • bool collecting: A boolean value indicating whether data is currently being collected for the participant session.

Here’s an example of how to use the VERASessionManager to check if VERA has been initialized and is ready to record data:

// 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.");
}

Here’s an example of how to use the VERASessionManager to get the current participant ID:

// 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 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. After finalizing a participant session, the participant will be marked as Completed on the VERA web interface.

If you fail to call this function at the end of your experiment, the participant session will likely be marked as Incomplete.

// Finalize the current participant session
VERASessionManager.FinalizeSession();

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.