StandaloneWebView

class : IWebView

Namespace: Vuplex.WebView

Additional feature interfaces: ?

StandaloneWebView is the IWebView implementation used by 3D WebView for Windows and macOS. It also includes additional APIs for Standalone-specific functionality.

Summary

Public methods

Public events

Public methods

CreatePdf

Task<string> CreatePdf(StandalonePdfOptions pdfOptions)

Like IWithPdfCreation.CreatePdf(), but accepts an additional parameter with options for formatting the PDF.

Example

#if UNITY_STANDALONE || UNITY_EDITOR
    var standaloneWebView = webViewPrefab.WebView as StandaloneWebView;
    var pdfFilePath = await standaloneWebView.CreatePdf(new StandalonePdfOptions {
        PageRanges = "1-3",
        PreferCssPageSize = true,
        PrintBackground = true
    });
    // Now that the PDF has been created, do something with it.
    // For example, you can move it to a different location.
    File.Move(pdfFilePath, someOtherLocation);
#endif

DeleteAllCookies

static Task<bool> DeleteAllCookies()

Deletes all cookies for all URLs and returns a Task<bool> indicating whether the deletion succeeded.

Example

#if UNITY_STANDALONE || UNITY_EDITOR
    var succeeded = await StandaloneWebView.DeleteAllCookies();
#endif

EnableRemoteDebugging

static void EnableRemoteDebugging(int portNumber)

Like Web.EnableRemoteDebugging(), but starts the DevTools session on the specified port instead of the default port 8080.

Example

void Awake() {
    StandaloneWebView.EnableRemoteDebugging(9000);
}

SendDevToolsMessage

void SendDevToolsMessage(string messageJson)

Sends a method call message over the Chrome DevTools protocol. The messageJson parameter is a JSON DevTools message that contains "id" (int), "method" (string), and "params" (dictionary, optional) values. See the DevTools protocol documentation for details of supported methods and the expected "params" dictionary contents.

Example

await webViewPrefab.WaitUntilInitialized();
#if UNITY_STANDALONE || UNITY_EDITOR
    var standaloneWebView = webViewPrefab.WebView as StandaloneWebView;
    var messageId = 0;
    standaloneWebView.SendDevToolsMessage(
        @$"{{
            ""id"": {messageId++},
            ""method"": ""Network.setUserAgentOverride"",
            ""params"": {{ ""userAgent"": ""a custom user agent"" }}
        }}"
    );
#endif

SetAcceleratedPaintEnabled

static void SetAcceleratedPaintEnabled(bool enabled)

Sets whether hardware accelerated rendering is enabled on Windows for the D3D11 graphics API. The default is true. This method has no effect for the D3D12 graphics API or for macOS.

By default, when running on Windows with the D3D11 graphics API, 3D WebView uses the most performant method of rendering, which involves using Chromium Embedded Framework's (CEF's) OnAcceleratedPaint() function. However, the application can call SetAcceleratedPaintEnabled(false) to make 3D WebView use CEF's less performant OnPaint() function instead.

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        StandaloneWebView.SetAcceleratedPaintEnabled(false);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

SetCachePath

static void SetCachePath(string absoluteFilePath)

By default, Chromium's cache is saved at the file path Application.persistentDataPath/Vuplex.WebView/chromium-cache, but you can call this method to specify a custom file path for the cache instead. This is useful, for example, to allow multiple instances of your app to run on the same machine, because multiple instances of Chromium cannot simultaneously share the same cache.

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        var customCachePath = Path.Combine(Application.persistentDataPath, "your-chromium-cache");
        StandaloneWebView.SetCachePath(customCachePath);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

SetChromiumLogLevel

static void SetChromiumLogLevel(ChromiumLogLevel level)

Sets the log level for the Chromium logs. The default is ChromiumLogLevel.Warning. For a description of where the Chromium logs are written to, see SetChromiumLogPath()

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        StandaloneWebView.SetChromiumLogLevel(ChromiumLogLevel.Disabled);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

See also: SetChromiumLogPath

SetChromiumLogPath

static void SetChromiumLogPath(string absoluteFilePath)

Overrides the absolute file path to which the Chromium debug log is written. By default, Chromium's log file is written to the following locations:

  • Windows editor: {ProjectPath}\Assets\Vuplex\WebView\Standalone\Windows\Plugins\VuplexWebViewChromium\log-chromium.txt~
  • Windows player: {AppPath}\{AppName}_Data\Plugins\{Architecture}\VuplexWebViewChromium\log-chromium.txt
  • macOS: ~/Library/Logs/Vuplex/log-chromium.txt

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        var customLogPath = Path.Combine(Application.persistentDataPath, "your-chromium-log.txt");
        StandaloneWebView.SetChromiumLogPath(customLogPath);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

See also: SetChromiumLogLevel

SetCommandLineArguments

static void SetCommandLineArguments(string args)

Sets additional command line arguments to pass to Chromium. For reference, here's an unofficial list of Chromium command line arguments.

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        StandaloneWebView.SetCommandLineArguments("--ignore-certificate-errors --disable-web-security");
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

SetNativeFileDialogEnabled

void SetNativeFileDialogEnabled(bool enabled)

The native file picker for file input elements is enabled by default, but it can be disabled with this method.

Example

await webViewPrefab.WaitUntilInitialized();
#if UNITY_STANDALONE || UNITY_EDITOR
    var standaloneWebView = webViewPrefab.WebView as StandaloneWebView;
    standaloneWebView.SetNativeFileDialogEnabled(false);
#endif

SetScreenSharingEnabled

static void SetScreenSharingEnabled(bool enabled)

By default, web pages cannot share the device's screen via JavaScript. Invoking SetScreenSharingEnabled(true) allows all web pages to share the screen.

The screen that is shared is the default screen, and there isn't currently support for sharing a different screen or a specific application window. This is a limitation of Chromium Embedded Framework (CEF), which 3D WebView uses to embed Chromium.

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        StandaloneWebView.SetScreenSharingEnabled(true);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

SetTargetFrameRate

static void SetTargetFrameRate(uint targetFrameRate)

Sets the target web frame rate. The default is 60, which is also the maximum value. Specifying a target frame rate of 0 disables the frame rate limit.

Example

void Awake() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        // Disable the frame rate limit.
        StandaloneWebView.SetTargetFrameRate(0);
    #endif
}

Important note

This method cannot be executed while the Chromium browser process is running. So, you will likely need to call it from Awake() to ensure that it's executed before Chromium is started. Alternatively, you can manually terminate Chromium prior to calling this method using StandaloneWebView.TerminateBrowserProcess().

SetZoomLevel

void SetZoomLevel(float zoomLevel)

Sets the zoom level to the specified value. Specify 0.0 to reset the zoom level.

Example

// Set the zoom level to 1.75 after the page finishes loading.
await webViewPrefab.WaitUntilInitialized();
webViewPrefab.WebView.LoadProgressChanged += (sender, eventArgs) => {
    if (eventArgs.Type == ProgressChangeType.Finished) {
        #if UNITY_STANDALONE || UNITY_EDITOR
            var standaloneWebView = webViewPrefab.WebView as StandaloneWebView;
            standaloneWebView.SetZoomLevel(1.75f);
        #endif
    }
};

TerminateBrowserProcess

static Task TerminateBrowserProcess()

Terminates the Chromium browser process.

When 3D WebView for Windows and macOS initializes the application's first webview, it starts Chromium in a separate process. That Chromium process runs until the application closes, at which point 3D WebView automatically calls this method to terminate the Chromium process. However, in some rare cases, you may want your application to call this method manually to terminate Chromium while the app is still running. For example, some 3D WebView APIs like Web.ClearAllData() cannot be called while Chromium is running, but your application can use this method to terminate Chromium so that it can call those APIs. Prior to calling this method, your application must destroy all of the application's existing webviews (e.g. using WebViewPrefab.Destroy()). After Chromium finishes terminating, you can restart Chromium by creating new webview instances. (e.g. using WebViewPrefab.Instantiate()).

Example

async void ClearDataAtRuntime() {
    #if UNITY_STANDALONE || UNITY_EDITOR
        // 1. Destroy all the webviews in the application.
        var webViewPrefabs = GameObject.FindObjectsOfType<BaseWebViewPrefab>();
        foreach (var prefab in webViewPrefabs) {
            prefab.Destroy();
        }

        // 2. Terminate Chromium.
        await StandaloneWebView.TerminateBrowserProcess();

        // 3. Call the API that can't be called while Chromium is running.
        Web.ClearAllData();

        // 4. TODO: Create new webviews with WebViewPrefab.Instantiate() if needed.
    #else
        // On other platforms, Web.ClearAllData() can be called while the browser process is running.
        Web.ClearAllData();
    #endif
}

Public events

ClientCertificateRequested

EventHandler<StandaloneClientCertificateRequestedEventArgs> ClientCertificateRequested

Indicates that the web page has requested a client certificate for authentication, and allows the application to select which client certificate to use.

In order for the Chromium browser engine to be able to use a client certificate, the certificate must be installed in the system. By default, if a web page requests a client certificate and the application hasn't attached an event handler to this event, then Chromium automatically selects the first client certificate available. If the application attaches an event handler to this event, the event handler should call the eventArgs.Select() callback and pass one of the certificates from the eventArgs.Certificates array as an argument. Or the handler can call eventArgs.Select(null) to continue without using a certificate.

Example

await webViewPrefab.WaitUntilInitialized();
#if UNITY_STANDALONE || UNITY_EDITOR
    var standaloneWebView = webViewPrefab.WebView as StandaloneWebView;
    standaloneWebView.ClientCertificateRequested += (sender, eventArgs) => {
        if (eventArgs.Certificates.Length == 0) {
            Debug.Log("No matching client certificates are installed in the system; proceeding without a certificate.");
            eventArgs.Select(null);
            return;
        }
        // For your use case, you may want to select the certificate based on its fields,
        // such as Subject.CommonName or ValidStart.
        var certificate = eventArgs.Certificates[0];
        Debug.Log("Proceeding with client certificate: " + certificate);
        eventArgs.Select(certificate);
    };
#endif