WebXR guide

WebXR is the primary interface used by VERA to run your XR experiments in a web browser. In this way, participants can access your experiments without needing to download or install any additional software.

This section provides a guide on how to build and run your experiments in WebXR using the VERA tools, including how to configure your Unity project for WebXR compatibility and how to upload your experiments to the VERA portal.

Note

For WebXR troubleshooting, scroll to the bottom of this page for a list of common issues and solutions.

Understanding WebXR

WebXR is a web API which allows the creation of immersive experiences that run directly in a web browser. These WebXR experiences can be accessed without needing to download or install any additional software, making them highly accessible and easy to use.

WebXR is built on top of the WebGL library, which allows easily rendering 3D graphics in a web browser. VERA uses WebXR to host and run your Unity experiments directly on the VERA web interface, allowing participants to access and take part in your experiments directly in their web browser without needing to download your experiment directly.

Unity does not have built-in support for WebXR, but there are various Unity plugins available which do provide this support. The VERA Unity plugin interfaces directly with the Unity WebXR Export plugin, a plugin which allows seamless export of Unity projects to WebXR. This WebXR Export plugin is installed automatically when exporting from the VERA Unity plugin, and is used to build your Unity project for WebXR.

Note

WebXR is highly recommended for use with VERA, as it greatly simplifies the process of building, distributing, and running your XR experiments, both on the researcher and participant side. It is also the primary method used by VERA to distribute experiments to participants remotely. However, if you need to distribute your experiment in a different way (e.g., in the Unity editor, standalone build, etc.), the VERA package also supports these distribution methods.

(Refer to the official WebXR documentation for more details on what WebXR is and how it works).

Limitations of WebXR

While WebXR is a powerful and flexible platform for running XR experiences in a web browser, it does have some limitations that you should be aware of when developing your experiments:

  • Performance: WebXR experiences may not perform as well as native applications, especially on lower-end devices. This can lead to lower frame rates and reduced visual quality compared to native applications. This should not be a significant issue for most VERA experiments, but it is something to keep in mind when designing your experiment.

  • Advanced features: Some advanced XR features may not be fully supported in WebXR, such as hand tracking, eye tracking, and certain haptic feedback capabilities. If your experiment relies heavily on these advanced features, you may need to consider alternative distribution methods.

Building and uploading experiments for WebXR

Once you are ready to export your Unity experiment for WebXR, follow these steps:

  1. Open the VERA Settings Window: In Unity, open the VERA Settings window by navigating to VERA > Settings in the Unity menu bar.

  2. Click the Button: In the VERA Settings window, if you are authenticated, you should see a Build and Upload Experiment button. Click this button to begin the build and upload process.

  3. Wait for Completion: VERA will automatically install any dependencies, adjust any settings, and ensure the proper environment necessary for WebXR. You can monitor the process in the Unity debug console. If any error occurs along the way, it will be displayed in the console alongside instructions on how to resolve it. When the build is done, a dialogue will appear indicating that the build was successful.

That’s it - you’re done! Your experiment is now built for WebXR and uploaded to the VERA portal.

Exported WebXR experiments are not stored on your local machine - they are hosted on the VERA portal. As such, you don’t need to worry about any cleanup, or managing locally built files on your system.

Note that the WebXR build process may take some time, depending on the size and complexity of your Unity project (sometimes upwards of 20 minutes). The first build often takes the longest, with subsequent builds being faster due to caching.

Additionally note that the experiment will be built only for the currently active experiment set in the VERA Settings window. If you wish to build a different experiment, you will need to select that experiment in the VERA Settings window before clicking the Build and Upload Experiment button.

Viewing and Running WebXR Experiments

Once your experiment is built for WebXR and uploaded to the VERA web interface, the experiment can be viewed and run directly in a web browser.

Your experiment’s specific unique URL will differ based on the distribution method you have chosen in the web interface for your experiment. Return to your experiment’s settings on the web interface to view and manage these distribution methods. It is here that you will find the particular link to your WebXR experiment, which can be distributed to participants.

For example, let’s say you have chosen to distribute your experiment remotely via manual link sharing. Your URL might look something like “vera-xr.io/remote/[yourid]”. Opening this link in a web browser will launch the participant experience, allowing the participant to take part in your experiment directly in their web browser.

The link for your experiment can be shared with participants according to your distribution method. For more details, see the Web interface: experiment distributions section.

Additional WebXR features

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

Or, if you were using Prolific, and you already had custom parameters injected into the URL, giving a base URL something like vera-xr.io/remote/abc123?PROLIFIC_PID=xyz987, you could append it like the following:

  • vera-xr.io/remote/abc123?PROLIFIC_PID=xyz987&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.

Troubleshooting and frequently asked questions

Everything is pink

If your WebXR experiment is launching but everything appears pink, it is likely an issue with URP incompatabilities.

To resolve this issue, make sure you are actually using the Universal Render Pipeline. If you do not have a URP Asset but have chosen URP as your render pipeline, click Create > Rendering > URP Asset (With Universal Renderer) to create one; go to your project settings and assign that asset under Graphics > Default render pipeline.

If everything is still pink, even in URP, try upgrading your materials. Go to Window > Rendering > Rendering Pipeline Converter > Convert materials.

If you do not want to use URP, WebXR does support the built-in render pipeline, with some extra steps. See the Depanther WebXR documentation for more details: https://github.com/De-Panther/unity-webxr-export/blob/master/Documentation/Getting-Started.md

WebXR build is taking a long time

The first build of WebXR can take upwards of 20 minutes, especially for larger projects. However, once you build your project for the first time, subsequent builds should be much faster, sometimes even under 10 seconds.

Reducing the complexity of your project can aid in reducing build times. For example, removing unnecessary assets, optimizing your scenes, and using simpler materials can all help speed up the build process.

Only one eye is rendering

If only one eye is rendering your WebXR experience, try enabling compatability mode. Go to Project Settings > Graphics > Enable Compatability Mode (Render Graph Disabled). This should resolve the issue and allow both eyes to render properly.

My hand controllers aren’t tracking

If your hand controllers aren’t tracking properly in WebXR, try switching XR providers from OpenXR to Oculus.

If this does not work, it may be an issue with the particular version of the Unity Input System you are using. Try adding a “Tracked Pose Driver” component to your hand controller objects, and set the device to “Generic XR Controller” and the pose source to “Left Controller” or “Right Controller” as appropriate. This should allow your hand controllers to track properly in WebXR.

Note that this is different from the “Tracked Pose Driver (Input System)” component provided by the Unity XRI package, which might not work properly with WebXR depending on your version of the Unity Input System. You should be able to have both of these Tracked Pose Driver variants present on your hand controllers simultaneously without issue - just make sure to use the non-Input System variant if you are having tracking issues in WebXR.

I’m too tall

If your WebXR experience is launching but you are too tall in the environment, try removing any y-offsets from your camera rig, and if using an XR Origin, set the Tracking Origin Mode to “Floor”.

XRI and many other toolkits add a y-offset to the camera to handle heights; WebXR handles this offset by default - so any XRI / toolkit offsets will “double up” with WebXR’s own height handling, and may make you taller than intended.

My video players aren’t working

Unity WebGL builds do not support VideoPlayer components set to use the “Video Clip” source mode, due to how WebGL builds are packaged.

In order to use videos in WebXR, you will need to set your VideoPlayer components to use the “URL” source mode, and provide a URL to the video you wish to use. This can be a remote URL (e.g., a YouTube video, or a video hosted on your own server), or if you have your own video file (i.e. .mp4 or something similar), you can access it in WebXR by placing the video file in your Unity project’s “StreamingAssets” folder, and providing a URL to that video using the Application.streamingAssetsPath variable (e.g., videoPlayer.url = Application.streamingAssetsPath + “/myVideo.mp4”).

For example, say you have a VideoPlayer component set to “Video Clip” source mode which is currently not working for your WebXR build. To fix this, simply:

  1. Change the VideoPlayer’s source mode to “URL”.

  2. Place your video file (e.g., “myVideo.mp4”) in your Unity project’s “StreamingAssets” folder (create this folder in the Assets directory if it doesn’t already exist, i.e. “Assets/StreamingAssets/myVideo.mp4”).

  3. In a C# script, get a reference to your VideoPlayer component, and set the videoPlayer.url to Application.streamingAssetsPath + “/myVideo.mp4”.

public VideoPlayer videoPlayer; // assign this in the inspector

void Start() {
  videoPlayer.source = VideoSource.Url;
  videoPlayer.url = Application.streamingAssetsPath + "/myVideo.mp4";
}