VisionOSWebView

class : IWebView

Namespace: Vuplex.WebView

Additional feature interfaces: ?

VisionOSWebView is the IWebView implementation used by 3D WebView for visionOS. It also includes additional APIs for visionOS-specific functionality.

Summary

Public properties

Public methods

Public properties

Window

VisionOSWindow Window

If the webview was created via CreateInWindow(), this property is a VisionOSWindow instance that provides APIs to manipulate the native SwiftUI window, such as closing and re-opening it. If the webview was not created via CreateInWindow() (e.g. it was created via a CanvasWebViewPrefab), then this property is null.

Example

#if UNITY_VISIONOS && !UNITY_EDITOR
    var webView = await VisionOSWebView.CreateInWindow();
    // Add an event handler to detect when the user closes the window.
    webView.Window.Closed += (sender, eventArgs) => {
        Debug.Log("window closed");
    };
#endif

Public methods

CreateInWindow

Task<VisionOSWebView> CreateInWindow()

When running in Unity's RealityKit app mode, the application can use this method to open a webview in a native visionOS (SwiftUI) window, which the user can reposition, resize, and close using visionOS's native windowing controls. The application can also manipulate the webview's window programmatically via the VisionOSWebView.Window property (for example, to close and reopen the window, or detect when it has been closed by the user). This native window approach provides the best performance, and since it supports hovering over elements in the web page via eye tracking, it also provides the best user experience. The tradeoff is that the application is unable to control the webview's position or size after it is opened because those aspects are controlled by the user. This version of CreateInWindow() opens the webview's window using the system's default size (1280 x 720 px) and position (in front of the user). To customize the window's initial size and position, use CreateInWindow(VisionOSWindowOptions) instead.

Additional notes:

  • For a full example, please see the visionOS RealityKit WebView Example project.
  • CreateInWindow() is only supported when the application's app mode is set to RealityKit, and it throws an InvalidOperationException if invoked when the app mode is set to Metal or Windowed.
  • When the window is closed (i.e. due to the user pressing its close button or the application calling Window.Close()), the webview is not automatically destroyed; the webview remains running and the window can be reopened by calling Window.Open(). The webview is only destroyed if the application calls IWebView.Dispose(). So, unless the application uses Window.Open() to reopen a webview after it has been closed by the user, it's recommended to attach an event handler to the Window.Closed event that calls IWebView.Dispose() when the user has closes the window. This approach is demonstrated in the example below.

Example

#if UNITY_VISIONOS && !UNITY_EDITOR
    var webView = await VisionOSWebView.CreateInWindow();
    // The webview has been displayed to the user in a native window,
    // and now you can use IWebView APIs like LoadUrl() and LoadHtml().
    webView.LoadUrl("https://vuplex.com");
    // Add an event handler that destroys the webview when the user closes the window.
    webView.Window.Closed += (sender, eventArgs) => {
        webView.Dispose();
    };
#endif
See also:

CreateInWindow

Task<VisionOSWebView> CreateInWindow(VisionOSWindowOptions options)

Like CreateInWindow(), except it also accepts a VisionOSWindowOptions parameter for customizing the window's initial size and position.

Example

#if UNITY_VISIONOS && !UNITY_EDITOR
    var webView = await VisionOSWebView.CreateInWindow(
        new VisionOSWindowOptions {
            Size = new Vector2Int(1000, 1000),
            Position = new VisionOSWindowPosition(
                VisionOSWindowPositionType.Trailing,
                VisionOSWindowPosition.UnityBoundedSceneID
            )
        }
    );
    // The webview has been displayed to the user in a native window,
    // and now you can use IWebView APIs like LoadUrl() and LoadHtml().
    webView.LoadUrl("https://vuplex.com");
    // Add an event handler that destroys the webview when the user closes the window.
    webView.Window.Closed += (sender, eventArgs) => {
        webView.Dispose();
    };
#endif

Important note

The VisionOSWindowsOptions.Size and Position options require visionOS 2.0. On visionOS 1.x, the Size and Position options are ignored, and a window always uses the system's default size and position.

GetNativeWebView

IntPtr GetNativeWebView()

Returns an Objective-C pointer to the instance's underlying native WKWebView. The application can use this to utilize native iOS APIs for which 3D WebView doesn't yet have dedicated C# equivalents. To utilize the pointer, the application must pass it to a native function defined in an Objective-C (.m) file like illustrated in the example below.

Objective-C Example

// Example of defining a native Objective-C function that sets WKWebView.allowsLinkPreview.
// Place this in a .m file in your project, like Assets/Plugins/WebViewCustom.m
#import <Foundation/Foundation.h>
#import <WebKit/WebKit.h>

void WebViewCustom_setAllowsLinkPreview(WKWebView *webView, BOOL allowsLinkPreview) {

    webView.allowsLinkPreview = allowsLinkPreview;
}

C# Example

// Example of calling the native Objective-C function from C#.
async void EnableLinkPreviews(WebViewPrefab webViewPrefab) {

    await webViewPrefab.WaitUntilInitialized();
    #if UNITY_VISIONOS && !UNITY_EDITOR
        var wkWebViewPtr = (webViewPrefab.WebView as VisionOSWebView).GetNativeWebView();
        WebViewCustom_setAllowsLinkPreview(wkWebViewPtr, true);
    #endif
}

[System.Runtime.InteropServices.DllImport("__Internal")]
static extern void WebViewCustom_setAllowsLinkPreview(System.IntPtr webViewPtr, bool allowsLinkPreview);

Important note

Adding code that interacts with the native WKWebView directly may interfere with 3D WebView's functionality and vice versa. So, it's highly recommended to stick to 3D WebView's C# APIs whenever possible and only use GetNativeWebView() if truly necessary. If 3D WebView is missing an API that you need, feel free to contact us.

SetCameraEnabled

static void SetCameraEnabled(bool enabled)

Like Web.SetCameraAndMicrophoneEnabled(), but enables only the camera without enabling the microphone. In addition to calling this method, you must also complete the additional steps described here in order to successfully enable the camera.

Example

void Awake() {
    #if UNITY_VISIONOS && !UNITY_EDITOR
        VisionOSWebView.SetCameraEnabled(true);
    #endif
}

SetMicrophoneEnabled

static void SetMicrophoneEnabled(bool enabled)

Like Web.SetCameraAndMicrophoneEnabled(), but enables only the microphone without enabling the camera. In addition to calling this method, you must also complete the additional steps described here in order to successfully enable the microphone.

Example

void Awake() {
    #if UNITY_VISIONOS && !UNITY_EDITOR
        VisionOSWebView.SetMicrophoneEnabled(true);
    #endif
}

SetTargetFrameRate

void SetTargetFrameRate(uint targetFrameRate)

Sets the target web frame rate. The default is 30, which is also the maximum value. This method can be used to lower the target web frame rate in order to decrease energy and CPU usage. 3D WebView's rendering speed is limited by the speed of the underlying visionOS APIs, so the actual web frame rate achieved is always lower than the default target of 30 FPS.

Example

await webViewPrefab.WaitUntilInitialized();
#if UNITY_VISIONOS && !UNITY_EDITOR
    var visionOSWebView = webViewPrefab.WebView as VisionOSWebView;
    visionOSWebView.SetTargetFrameRate(15);
#endif