Using WebVR on WebXR Enabled Browsers

Oculus Browser 7.0 and later support WebXR by default, as this API has now stabilized. WebXR replaces the WebVR API, which although not a standard, was adopted by many browsers. As Oculus Browser and other browsers release with WebXR enabled, apps built against WebVR may stop working because they have code that supported earlier versions of WebXR, which is not compatible with the current WebXR specification. This document describes some compatibility issues that have been identified, and the steps you can take to help ensure your web apps continue to work with WebXR.

Identified Compatibility Issues

Some older versions of popular VR web development libraries have compatibility issues. Browser experiences that may not function as expected with WebXR include:

• Older versions of three.js, a JavaScript 3D library. Older versions of three.js can detect the presence of WebXR support in a browser, and will use it over WebVR, but there may be compatibility issues between the version of WebXR used in the browser and the version implemented by three.js.
• A-FRAME, a web framework for building virtual reality experiences because it is based on three.js.

There may be other experiences that have compatibility issues that have not been identified.

Test for Compatibility

To see if your VR web experiences have compatibility issues, you can test your web experiences with both WebXR and WebVR enabled.

For Oculus Browser or Google Chrome, go to chrome://flags and enable WebVR and WebXR (in Oculus Browser 7.0 this is the default setting). Other modern browsers should have similar settings.

Next, load your experience and try to enter VR. If your experience behaves as you expect, then you likely do not need to make any changes. You should try your experience in several browsers.

If it fails, the results may differ depending on the browser you are using. A failure you may see if you are using an older version of three.js is:

1. The Enter VR button does not appear.
2. A JS exception occurs when you enter VR.

For the test described, WebXR support is detected by the framework and an Enter XR button may appear, but when you click it, you receive an exception as described by issue #2.

Resolve Compatibility Issues

In general to fix compatibility issues, you can check for a newer version of any frameworks or tools that you are using in your web app, and whether the newer versions are compatible with WebXR. If so, migrate to the newer version.

If there is no newer version, or the newer version does not fully support WebXR, you may be able to modify open-source code to work in the latest browsers.

three.js Modification Example

For the three.js compatibility problem described in the previous section, you can do one of three things:

1. Migrate your experience to three.js r110 or later. This may be a more complicated fix as the API for three.js has changed between versions. However updating to r110 (or newer) is the recommended fix as many browser may remove support for WebVR soon.
2. Remove WebXR detection logic from the three.js version you are using; in this case, the experience will fall back to WebVR and work as expected. Note that WebVR support will be removed from Oculus Browser in the near future.
3. Modify the WebXR support in the version of three.js you are using to work with the latest browser support. This involves modifications of WebXRManager.js and WebVR.js files. This is a more complex work-around that requires knowledge about WebXR and three.js internal logic and is not described in this document.

Remove Detection Logic from three.js

The following is an example of how you could remove the WebXR detection logic from three.js for a custom version (you have already cloned and modified), or how to create a custom version and modify.

Remove WebXR Detection Logic from Custom three.js

The following steps apply if you are building a customized version of three.js yourself or you are using pre-built three.js. If you are using npm/yarn and the three.js module is downloaded from the original repo for you at build time, the following steps won’t work. In this case see “Customize three.js and remove WebXR dectection logic” section that follows.

To disable the obsolete WebXRManager in older three.js versions:

• If you are building three.js yourself, locate src/renders/WebGLRenderer.js
• If you are using pre-built three.js, meaning a single three.js file, search for function WebGLRenderer( in the file.

Then:

• Search for WebXRManager, and you should find a line like this:

  var vr = ( 'xr' in navigator ) ? new WebXRManager( _this ) : new WebVRManager( _this );
  

  Or in newer versions, find a line like the following:

  var vr = ( typeof navigator !== 'undefined' && 'xr' in navigator && 'sessionSupported' in navigator.xr ) ? new WebXRManager( _this, _gl ) : new WebVRManager( _this );
  

• Replace these lines with:

  var vr = new WebVRManager( _this );
  

Enter VR button

• If your experience relies on WebVR.js logic for Enter VR button, then:
  • Locate WebVR.js file in the examples/js/vr directory; alternatively, if not a part of the prebuilt three.js module, this file (or parts of it) could be copied into your project’s directory.
  • Find the line where the code decides whether to use the Enter XR or Enter VR button, like if ( 'xr' in navigator.
  • Remove the whole if (‘xr’... statement up to the line ‘else if ( 'getVRDisplays' in navigator ) {‘.
  • Change the following line to show the Enter VR button. Change:

      else if ( 'getVRDisplays' in navigator ) {
    

    to:

      if ( 'getVRDisplays' in navigator){
    

  • Build, test and publish your app.

Customize three.js and remove WebXR dectection logic

If your app is built using npm or yarn and if the three.js was not customized by you, meaning npm/yarn will download the three.js module from the original repository, you will need to create a custom version that you can modify. The high-level steps for this are:

1. In GitHub, clone the three.js version you need
2. Make the modifications described in the previous section
3. Build three.js with the following commands for npm:

 $ npm install
 $ npm run build-closure

or for yarn:

$ yarn install
$ yarn run build-closure

1. Publish your version of three.js in your own GitHub repository (including the build/three.* files).
2. Write down the hash of that last commit. The hash will be something like this: 1234d3a7a6d7f7399bafe7df681453d17d4c2c3c.
3. Go to your app, find the package.json / yarn.lock files and modify them to refer to the version of three.js with the hash from the previous step.
4. Delete node_modules directory and repeat step 3, building and running three.js Note, sometimes it may require to delete the cache for npm/yarn, usually located in .npm or .yarn sub-directories of your home directory.
5. After you run the install command, you should verify that node_modules/three contains the proper version of three.js with the modified logic.
6. Check if you need to modify the logic for the Enter VR button described in section above.
7. Build, test, publish, test again.