URL Messaging System

UniWebView provides two messaging systems for communication between web content and Unity:

  1. URL Scheme Messaging (Traditional) - Simple, one-way communication using custom URL schemes
  2. Channel Messaging System (New) - Advanced, bidirectional communication with structured data support

Choosing the Right System

FeatureURL Scheme MessagingChannel Messaging System
ComplexitySimple, easy setupMore powerful, slightly more complex
CommunicationOne-way (Web → Unity)Bidirectional (Web ↔ Unity)
Data FormatURL query parametersStructured JSON data
Response SupportNoYes (sync and async)
Data Size Limit~16KBMuch larger (no URL length limits)
PerformanceGood for simple messagesBetter for complex data
Type SafetyString-based parsingNative object serialization
Use CasesSimple actions, notificationsComplex data exchange, API-like interactions

Recommendation:

  • Use URL Scheme Messaging for simple, fire-and-forget messages
  • Use Channel Messaging System for complex data exchange and when you need responses

NEW FEATURE

The Channel Messaging System is available starting from UniWebView v6. It provides more powerful communication capabilities. Learn more in the Channel Message Guide.

In this guide, we focus on the URL Scheme Messaging.


URL Scheme Messaging

This traditional messaging system enables one-way communication from web views to Unity using custom URL schemes, with a safe data transfer limit of about 16KB per message.

Send and Receive

You can send a message from the web view to UniWebView. It helps you implement a way to "control" your game from the web page.

UniWebView inspects all links starts from uniwebview:// by default. That means if your user taps a link starting with "uniwebview://", an OnMessageReceived event will be raised with a UniWebViewMessage as its parameter.

If you have this on your page:

<a href="uniwebview://action?key=value&anotherKey=anotherValue">Tap Me</a>

And you have this event listener in Unity:

webView.OnMessageReceived += (view, message) => {
    print(message.RawMessage);
};

When the link is tapped, it prints:

uniwebview://action?key=value&anotherKey=anotherValue

NAVIGATION

Besides of an HTML link, a location.href JavaScript will also send a message to UniWebView and trigger the event. The code below is identical to example above:

location.href = "uniwebview://action?key=value&anotherKey=anotherValue";

Message Object

UniWebView parses the input and pass it to you in the OnMessageReceived event, as the message parameter. In the example above, you have:

message.Scheme // "uniwebview"
message.Path   // "action"
message.Args   // {"key": "value", "anotherKey": "anotherValue"}

Using a Valid URL

From iOS 15.4, Apple applied a limitation that an invalid URL is not triggering the necessary events for UniWebView to deliver the message anymore. That means you cannot use things like location.href = "uniwebview://{\"title\":\"hello\"}" to send a message. Instead, you need to make sure to pass a valid URL, like location.href = "uniwebview://event?title=hello" or location.href = "uniwebview://event?payload={\"title\":\"hello\"}".

Furthermore, if you prefer an HTML link instead of the location.href above, remember to encode your URL query:

<a href="uniwebview://event?payload=%7B%22title%22:%22hello%22%7D">Hello</a>

For more about what is a "valid URL", please check RFC 3986open in new window and other related specifications.

DUPLICATED KEY

If you are using a same key for multiple values in the URL query, UniWebViewMessage will parse them to the same key as well, with the values concatenated by a comma. For example, a URL like uniwebview://action?key=1&key=2 will be parsed to a message with Args as {"key": "1,2"}.

Adding your own scheme

By default, "uniwebview" is inspected in UniWebView Messaging System. You can also add your own URL schemes. Call AddUrlScheme with the one you need:

// Start to inspect all `myscheme://` URLs.
webView.AddUrlScheme("myscheme");

A tricky thing here is, you can even set http and https as the scheme. It will prevent all loading of web resources. A use case is that you do not want your user to leave the current page: first load your page, then, in the OnPageFinished event, disable all navigating by adding the "http(s)" scheme:

webView.Load("https://yourpage.com");

webView.OnPageFinished += (view, statusCode, url) => {
    webView.AddUrlScheme("http");
    webView.AddUrlScheme("https");

    // Now your user will not be able to navigate to other pages hosted on HTTP or HTTPS.
};

Limitation

The URL scheme messaging system is built on URL and Unity's message sender. It means you cannot send the unlimited size of data at once. The allowed max length of a URL is different from devices and system versions. But a safe length is ~16KB for a URL. If you have something huge to send from the web page to Unity and encountered some problems, it would be better to split them into smaller pieces or switch to the Channel Messaging System.

Migrating to Channel Messaging System

If you find the URL scheme messaging limitations restrictive, consider migrating to the Channel Messaging System. Here's a simple example:

Before (URL Scheme)

// JavaScript - Limited data size, no response
location.href = "uniwebview://updateScore?score=1500&level=3&bonus=true";
// Unity - String parsing required
webView.OnMessageReceived += (view, message) => {
    if (message.Scheme == "uniwebview" && message.Path == "updateScore") {
        var score = int.Parse(message.Args["score"]);
        var level = int.Parse(message.Args["level"]);
        var bonus = bool.Parse(message.Args["bonus"]);
        UpdateScore(score, level, bonus);
    }
};

After (Channel Message)

// JavaScript - Structured data, can get response
const result = window.uniwebview.call("updateScore", {
  score: 1500,
  level: 3,
  bonus: true,
});

console.log("Score updated:", result);
// Unity - Type-safe object serialization
webView.OnChannelMessageReceived += (view, message) => {
    if (message.action == "updateScore") {
        var data = message.GetData<ScoreData>();
        var result = UpdateScore(data.score, data.level, data.bonus);
        return UniWebViewChannelMessageResponse.Success(result);
    }
    return null;
};

[System.Serializable]
public class ScoreData {
    public int score;
    public int level;
    public bool bonus;
}

NEXT STEPS

Ready to use the more powerful Channel Messaging System? Check out the Channel Message Guide for complete documentation and examples.