Usage

WebView displays web content within your Unity mobile application

Essential Kit wraps native iOS WKWebView and Android WebView into a single Unity interface. WebView instances can display URLs, HTML strings, and local files with full JavaScript support.

Table of Contents

• Understanding Core Concepts

• Import Namespaces

• Event Registration

• Creating a WebView Instance

• Setting Frame Size

• Appearance Styles

• Loading Content

• Showing and Hiding WebView

• JavaScript Execution

• Web-to-Unity Communication

• Controlling Web View

• Monitoring Load Progress

• Data Properties

• Core APIs Reference

• Error Handling

• Advanced: Manual Initialization

• Related Guides

Understanding Core Concepts

• Single-instance model – Essential Kit surfaces one active web view at a time. Create it once, reuse it, and hide it when not in use.

• Frames and styles – Choose between full-screen, normalized, or pixel-perfect frames and pick the style (Default, Popup, Browser) that matches your UX.

• Content sources – Web views can render remote URLs, inline HTML strings, or local files bundled with your game.

• JavaScript bridge – RunJavaScript executes scripts asynchronously and custom URL schemes let the page talk back to Unity.

• Lifecycle – Register events for load, show, hide, and URL scheme matches so you can pause gameplay and resume when the user closes the web content.

Import Namespaces

using VoxelBusters.EssentialKit;
using VoxelBusters.CoreLibrary;

Event Registration

Register for web view events in OnEnable and unregister in OnDisable:

void OnEnable()
{
    WebView.OnShow += OnWebViewShow;
    WebView.OnHide += OnWebViewHide;
    WebView.OnLoadStart += OnWebViewLoadStart;
    WebView.OnLoadFinish += OnWebViewLoadFinish;
    WebView.OnURLSchemeMatchFound += OnURLSchemeMatchFound;
}

void OnDisable()
{
    WebView.OnShow -= OnWebViewShow;
    WebView.OnHide -= OnWebViewHide;
    WebView.OnLoadStart -= OnWebViewLoadStart;
    WebView.OnLoadFinish -= OnWebViewLoadFinish;
    WebView.OnURLSchemeMatchFound -= OnURLSchemeMatchFound;
}

Event	Trigger
OnShow	Web view becomes visible on screen
OnHide	Web view is hidden from screen
OnLoadStart	Web page begins loading
OnLoadFinish	Web page finishes loading (or fails with error)
OnURLSchemeMatchFound	Custom URL scheme is detected in web content

Creating a WebView Instance

Why WebView Instances are Needed

WebView instances represent individual web views with their own settings, content, and state. Create an instance before loading any web content.

private WebView webView;

void Start()
{
    // Create web view instance
    webView = WebView.CreateInstance();

    Debug.Log("WebView instance created");
}

Single Instance: Essential Kit supports one active web view at a time. Creating a new instance replaces any existing web view.

Setting Frame Size

Configure web view size and position before showing:

Full Screen

void SetupFullScreenWebView()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();
}

Normalized Coordinates (0.0 to 1.0)

void SetupNormalizedWebView()
{
    webView = WebView.CreateInstance();

    // Half screen centered
    webView.SetNormalizedFrame(new Rect(0.25f, 0.25f, 0.5f, 0.5f));
}

Screen Pixel Coordinates

void SetupCustomSizeWebView()
{
    webView = WebView.CreateInstance();

    // Custom pixel size
    webView.Frame = new Rect(0, 0, Screen.width, Screen.height - 100);
}

Appearance Styles

WebView supports three visual styles with different controls:

Default Style

No controls - clean web content display. Ideal for ads or embedded content.

webView.Style = WebViewStyle.Default;

Popup Style

Close button in top-right corner. User can dismiss web view by tapping.

webView.Style = WebViewStyle.Popup;

Browser Style

Full browser controls: back, forward, reload, and close buttons.

webView.Style = WebViewStyle.Browser;

Button	Action
Back	Navigate to previous page in history
Forward	Navigate to next page in history
Reload	Refresh current page
Close	Hide the web view

Loading Content

Loading Web URLs

void LoadWebPage()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();
    webView.Style = WebViewStyle.Browser;

    // Load URL
    webView.LoadURL(URLString.URLWithPath("https://www.example.com"));

    // Optionally auto-show when loaded
    webView.AutoShowOnLoadFinish = true;
}

Loading HTML Strings

void LoadCustomHTML()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();

    string htmlContent = @"
        <html>
        <head>
            <style>
                body { font-family: Arial; padding: 20px; }
                h1 { color: #4CAF50; }
            </style>
        </head>
        <body>
            <h1>Welcome to My Game!</h1>
            <p>This is custom HTML content.</p>
            <button onclick='window.location=""mygame://button-clicked""'>Click Me</button>
        </body>
        </html>
    ";

    webView.LoadHtmlString(htmlContent);
    webView.Show();
}

Loading Local HTML Files

void LoadLocalFile()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();

    // Load from StreamingAssets or persistent path
    string filePath = Application.streamingAssetsPath + "/terms.html";
    webView.LoadURL(URLString.FileURLWithPath(filePath));

    webView.Show();
}

Loading Binary Data

void LoadImageData()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();

    Texture2D texture = GetGameTexture();
    string mimeType, textEncodingName;
    byte[] data = texture.Encode(TextureEncodingFormat.JPG, out mimeType, out textEncodingName);

    webView.LoadData(data, mimeType, textEncodingName);
    webView.Show();
}

Showing and Hiding WebView

Manual Show/Hide

void ShowWebView()
{
    webView.Show();
}

void HideWebView()
{
    webView.Hide();
}

Auto-Show on Load

void LoadAndAutoShow()
{
    webView = WebView.CreateInstance();
    webView.SetFullScreen();
    webView.AutoShowOnLoadFinish = true; // Show automatically when loaded

    webView.LoadURL(URLString.URLWithPath("https://www.example.com"));
}

Handling Show/Hide Events

void OnWebViewShow(WebView view)
{
    if (webView == view)
    {
        Debug.Log("WebView is now visible");
        Debug.Log("Pause gameplay while the web view is active.");
    }
}

void OnWebViewHide(WebView view)
{
    if (webView == view)
    {
        Debug.Log("WebView was hidden");
        Debug.Log("Resume gameplay after closing the web view.");
    }
}

JavaScript Execution

Enabling JavaScript

void SetupJavaScriptWebView()
{
    webView = WebView.CreateInstance();
    webView.JavaScriptEnabled = true; // Required for RunJavaScript()
}

Running JavaScript Code

void ExecuteJavaScript()
{
    webView.JavaScriptEnabled = true;

    string script = @"
        function getMessage() {
            return 'Hello from JavaScript!';
        }
        getMessage();
    ";

    webView.RunJavaScript(script, (result, error) =>
    {
        if (error == null)
        {
            Debug.Log($"JavaScript result: {result.Result}");
        }
        else
        {
            Debug.LogError($"JavaScript error: {error}");
        }
    });
}

JavaScript with Parameters

void CallJavaScriptFunction()
{
    string playerName = "Alice";
    int playerScore = 1000;

    string script = $@"
        function updateLeaderboard(name, score) {{
            document.getElementById('player-name').innerText = name;
            document.getElementById('player-score').innerText = score;
            return 'Updated: ' + name + ' - ' + score;
        }}
        updateLeaderboard('{playerName}', {playerScore});
    ";

    webView.RunJavaScript(script, (result, error) =>
    {
        if (error == null)
        {
            Debug.Log($"Leaderboard updated: {result.Result}");
        }
    });
}

Web-to-Unity Communication

Understanding URL Schemes

URL schemes enable web content to send messages to Unity. Register a custom scheme (like mygame://) and Essential Kit intercepts matching URLs.

Registering URL Schemes

void SetupURLScheme()
{
    webView = WebView.CreateInstance();
    webView.JavaScriptEnabled = true;

    // Register custom scheme
    webView.AddURLScheme("mygame");

    string html = @"
        <html>
        <body>
            <h1>Game Communication</h1>
            <button onclick='window.location=""mygame://level-complete?score=1500""'>
                Complete Level
            </button>
            <button onclick='window.location=""mygame://purchase?item=sword""'>
                Buy Sword
            </button>
        </body>
        </html>
    ";

    webView.LoadHtmlString(html);
    webView.Show();
}

void OnURLSchemeMatchFound(string url)
{
    Debug.Log($"Received URL from web: {url}");

    if (url.Contains("mygame://level-complete"))
    {
        // Parse query parameters
        int score = ParseScoreFromURL(url);
        Debug.Log($"Complete level with score {score}.");
    }
    else if (url.Contains("mygame://purchase"))
    {
        string item = ParseItemFromURL(url);
        Debug.Log($"Handle purchase for item: {item}.");
    }
}

Parsing URL Parameters

int ParseScoreFromURL(string url)
{
    // Example: mygame://level-complete?score=1500
    var uri = new System.Uri(url);
    string query = uri.Query.TrimStart('?');
    var parameters = System.Web.HttpUtility.ParseQueryString(query);
    return int.Parse(parameters["score"]);
}

Controlling Web View

Reload Current Page

void ReloadPage()
{
    webView.Reload();
    Debug.Log("Reloading web page");
}

Stop Loading

void CancelLoading()
{
    webView.StopLoading();
    Debug.Log("Stopped loading web page");
}

Clear Cache

void ClearBrowserCache()
{
    webView.ClearCache();
    Debug.Log("Web view cache cleared");
}

ClearCache() Impact: Clearing cache affects all web view instances globally, not just the current one. Use carefully as it may slow down subsequent page loads.

Monitoring Load Progress

Track Loading State

void CheckLoadingState()
{
    if (webView.IsLoading)
    {
        double progress = webView.Progress; // 0.0 to 1.0
        Debug.Log($"Loading: {progress * 100}%");
        Debug.Log($"Update progress bar to {progress * 100}%.");
    }
}

void OnWebViewLoadStart(WebView view)
{
    if (webView == view)
    {
        Debug.Log($"Started loading: {view.URL}");
        Debug.Log("Show loading indicator.");
    }
}

void OnWebViewLoadFinish(WebView view, Error error)
{
    if (webView == view)
    {
        if (error == null)
        {
            Debug.Log("Page loaded successfully");
            Debug.Log("Hide loading indicator.");
        }
        else
        {
            Debug.LogError($"Page load failed: {error.Description}");
            Debug.LogError("Show in-game error message to the player.");
        }
    }
}

Data Properties

Property	Type	Notes
WebView.URL	string	Last URL that finished loading. Useful for analytics or resuming content after a hide/show cycle.
WebView.IsLoading	bool	true while the page is still loading. Pair it with Progress to drive loading indicators.
WebView.Progress	double	Normalized progress (0–1) reported by native web views.
WebView.ScalesPageToFit	bool	Enable to allow pinch-to-zoom and automatic scaling on both platforms.
WebView.CanBounce	bool	Controls the iOS rubber-band effect. Disable for full-screen kiosk experiences.
WebView.BackgroundColor	Color	Fills the view while content is loading—set it to match your brand palette.

void ConfigureWebViewProperties()
{
    webView.ScalesPageToFit = true; // Enable zoom
    webView.CanBounce = true; // Enable bounce effect
    webView.BackgroundColor = Color.white; // White loading background
}

Core APIs Reference

API	Purpose	Returns
WebView.CreateInstance(settings)	Create new web view instance	WebView instance
webView.SetFullScreen()	Set web view to full screen	void
webView.SetNormalizedFrame(rect)	Set size using normalized coordinates	void
webView.LoadURL(url)	Load web URL into web view	void
webView.LoadHtmlString(html)	Load HTML string into web view	void
webView.LoadData(data, mimeType, encoding)	Load binary data into web view	void
webView.Show()	Display web view on screen	void
webView.Hide()	Hide web view from screen	void
webView.RunJavaScript(script, callback)	Execute JavaScript and get result	void - result via callback
webView.AddURLScheme(scheme)	Register custom URL scheme for web-to-Unity messaging	void
webView.Reload()	Reload current page	void
webView.StopLoading()	Cancel current page load	void
webView.ClearCache()	Clear all cached web content	void

Error Handling

Handle load errors in the OnLoadFinish event:

void OnWebViewLoadFinish(WebView view, Error error)
{
    if (error != null)
    {
        Debug.LogError($"Web view load error: {error.Description}");

        // Show user-friendly error
        Debug.LogError("Display dialog: Page Load Failed - Unable to load the requested page. Please check your internet connection.");

        // Hide web view on error
        webView.Hide();
    }
}

Common error scenarios:

• No Internet: Network connection unavailable

• Invalid URL: Malformed URL or unreachable host

• SSL Error: Certificate validation failure (HTTPS)

• Timeout: Page took too long to load

Advanced: Manual Initialization

Manual initialization is only needed for specific runtime scenarios. For most games, Essential Kit's automatic initialization handles everything. Skip this section unless you need runtime configuration or per-instance custom settings.

Understanding Manual Initialization

Default Behavior: Essential Kit automatically initializes WebView using global settings from the ScriptableObject configured in Unity Editor.

Advanced Usage: Override settings at runtime or per-instance when you need:

• Dynamic camera/microphone permissions based on web content

• Different back button behavior for different web views

• Server-driven feature configuration

Implementation

Configure global settings:

void Awake()
{
    var globalSettings = new WebViewUnitySettings(
        isEnabled: true,
        androidProperties: new WebViewUnitySettings.AndroidPlatformProperties(
            usesCamera: true,
            usesMicrophone: false,
            allowBackNavigationKey: true)
    );

    WebView.Initialize(globalSettings);
}

Create instance with custom settings:

void CreateCustomWebView()
{
    var instanceSettings = new WebViewUnitySettings(
        isEnabled: true,
        androidProperties: new WebViewUnitySettings.AndroidPlatformProperties(
            usesCamera: false, // Override global setting
            usesMicrophone: false,
            allowBackNavigationKey: false)
    );

    webView = WebView.CreateInstance(instanceSettings);
}

Call Initialize() once before creating instances. Most games should use the standard setup configured in Essential Kit Settings instead.

Related Guides

• Demo scene: Assets/Plugins/VoxelBusters/EssentialKit/Examples/Scenes/WebViewDemo.unity

• Use with Sharing Services to share web content

• Pair with Network Services to detect offline status before loading URLs

• See Testing Guide for device testing checklist