Client Setup Guide

This guide provides configuration examples for CloudXR.js client devices, including browser setup, web server hosting options, and connection modes. These examples demonstrate common deployment scenarios you may encounter.

Web Application Hosting

CloudXR.js client applications can be hosted using either HTTP or HTTPS protocols. We provide examples for both modes to help you choose the right approach for your deployment.

HTTP Mode (Development)

This example demonstrates the simplest configuration for local development and testing.

Example command:

npm run dev-server

Access URLs:

  • Local: http://localhost:8080/
  • Network: http://<server-ip>:8080/

Characteristics:

  • Simplified setup with minimal configuration
  • Supports connections to both ws:// (direct) and wss:// (proxied) CloudXR Runtime endpoints
  • Requires browser security flags for WebXR functionality (see Browser Configuration)
  • Recommended for: Local development, trusted network environments

HTTPS Mode (Development and Production)

This example demonstrates HTTPS hosting, which is used for both development with WebXR devices and production deployments. It provides encrypted client connections and is required for secure WebSocket connections.

Example command:

npm run dev-server:https

Access URLs:

  • Local: https://localhost:8080/
  • Network: https://<server-ip>:8080/

Characteristics:

  • Automatically generates self-signed SSL certificates (for development) or custom certificates (for production)
  • Requires wss:// (secure WebSocket) connection to CloudXR Runtime
  • Browsers enforce mixed content policy, blocking ws:// connections from HTTPS pages
  • Requires certificate trust configuration in client browser
  • Recommended for: WebXR device testing, production deployments, remote access, security-sensitive environments

Connection Mode Examples

The following table shows example connection configurations between the web application server and CloudXR Runtime:

Client Web Server Runtime Connection Status Use Case
HTTP ws://server-ip:49100 ✅ Supported Local development (simplest path)
HTTP wss://proxy-ip:48322 ✅ Supported Testing proxy configuration
HTTPS ws://server-ip:49100 ❌ Blocked Mixed content security policy violation
HTTPS wss://proxy-ip:48322 ✅ Supported WebXR device testing, production deployment

Important: When using HTTPS mode for your web application, you must configure a WebSocket proxy with TLS support. See the Networking Setup Guide - WebSocket Proxy Setup for configuration details.

Meta Quest 3 Browser Configuration

This section provides configurations for Meta Quest 3 to enable WebXR functionality with CloudXR.js applications.

Configure Insecure Origins (HTTP Mode)

When using HTTP mode, the Meta Quest 3 browser needs explicit permission to access WebXR APIs from non-HTTPS origins. Here's how to configure it:

  1. Access Chrome flags:

    • Open the Meta Quest 3 Browser
    • Navigate to chrome://flags

  2. Enable insecure origins:

    • Search for "insecure" in the search field
    • Locate the flag: unsafely-treat-insecure-origin-as-secure
    • Set the flag to Enabled

  3. Add your development server:

    • In the text field below the flag, enter your web server URL
    • Format: http://<server-ip>:8080
    • Include the protocol (http://) and port number (:8080)
    • Multiple URLs can be separated by commas if needed

  4. Apply configuration:

    • Click or tap outside the text field to defocus
    • A "Relaunch" button will appear at the bottom of the screen
    • Click Relaunch to apply changes

  5. Verify configuration:

    • Return to chrome://flags after relaunch
    • Confirm the flag remains enabled and your URL is saved

Trust SSL Certificates (HTTPS Mode)

When using HTTPS mode with self-signed certificates (for the web server and the WebSocket proxy), you need to configure the browser to trust these certificates.

Note: Certificate trust settings persist across browser sessions. You only need to perform this configuration once per certificate.

Trust WebSocket Proxy Certificate

  1. Access the proxy endpoint:

    • In Meta Quest 3 Browser in the sample client page, fill in the proxy IP as server IP and corresponding port, and click "click xxx to accept cert" as shown below. Or you can directly navigate to https://<proxy-ip>:48322/

  2. Accept certificate warning:

    • Click Advanced

    • Click Proceed to <proxy-ip> (unsafe) or similar option

  3. Expected behavior:

    • The page may display a 501 Not Implemented error
    • This is expected - the proxy only handles WebSocket connections, not HTTP requests
    • The certificate is now trusted for WebSocket connections

Note: If you restart or recreate the proxy container (using the Docker HAProxy example with auto-generated certificates), a new self-signed certificate will be generated. You must repeat the certificate trust process by visiting https://<proxy-ip>:48322/ again and accepting the new certificate warning. If you mount your own certificate (see Networking Setup - Using Custom Certificates), the same certificate persists across restarts and you only need to trust it once.

Trust Web Application Certificate

  1. Access the web application:

    • Open Meta Quest 3 Browser
    • Navigate to https://<server-ip>:8080/

  2. Accept certificate warning:

    • Click Advanced

    • Click Proceed to <server-ip> (unsafe) or similar option

  3. Verify access:

    • The web application should load successfully

Verify WebXR Permissions

When connecting to a CloudXR.js application:

  1. The browser will prompt for WebXR permissions
  2. Select Allow when prompted
  3. The immersive session will begin after permission is granted

Tip: For rapid development and debugging, you can test your CloudXR.js application on a desktop browser before deploying to Meta Quest 3. Detailed setup instructions are provided in the Isaac Lab Client guide.

Network Configuration

For network and firewall configuration requirements, including port setup and bandwidth recommendations, see the Networking Setup Guide.

Common Issues and Solutions

WebXR API Not Available

Symptoms:

  • Application displays "WebXR not supported" or similar error
  • Connect button is disabled or missing

Solutions:

  • Verify browser flags are configured correctly (HTTP mode example)
  • Ensure you're accessing via the configured URL exactly as specified
  • Confirm the browser has been relaunched after changing flags
  • Try accessing via incognito/private browsing mode

Certificate Trust Issues

Symptoms:

  • Connection fails with security warnings
  • WebSocket connection shows "SSL certificate error"

Solutions:

  • Complete the certificate trust process for both web server and proxy
  • Verify you clicked "Proceed" on the certificate warning pages
  • Clear browser cache and retry the trust process
  • For persistent issues, regenerate certificates

Mixed Content Errors

Symptoms:

  • Console shows "blocked by mixed content policy" errors
  • WebSocket connection fails from HTTPS page

Solutions:

  • When using npm run dev-server:https, ensure runtime connection uses wss:// not ws://
  • Verify a WebSocket proxy is configured and running (see Networking Setup examples)
  • Check that proxy URL is accessible and trusted

Connection Drops or Instability

Symptoms:

  • Frequent disconnections during streaming
  • Poor video quality or high latency

Solutions:

  • Review Networking Setup Guide for bandwidth and latency requirements
  • Verify firewall allows traffic on required ports
  • Ensure Wi-Fi connection is on 5GHz or 6GHz band
  • Check for network congestion from other devices

Next Steps

Settings

Member Visibility

On This Page

Client Setup Guide