ZFBrowser Documentation

ZFBrowser Documentation

This asset allows you to embed a full copy of Chromium, the open-source core of Google Chrome, inside your game!

Product Page | Unity Asset Store | Changelog | Get Help

Documentation for v1.1.0.

Copyright © 2015-2017 Zen Fulcrum LLC

Quick Start

Basic Browser:

Embedded assets:

Congratulations! You now have a browser in your game!

General

Important Note

This library is made possible by a number of third-party open source software projects!

Include a copy of ThirdPartyNotices.txt with your distributed product.

Supported Platforms

This plugin is available for the given platforms and architectures:

Browsers can be previewed when running inside the Unity Editor on the following platforms:

At present, you must use the same OS you are targeting to preview in the Unity Editor. For example, you must be running the 64-bit Windows Unity Editor to preview browsers when targeting Windows Standalone x64.

A 64-bit Linux port is partially completed but too unstable for distribution at this time. If you're excited to see this reach completion, send me an email.

This Asset does not includes licenses for proprietary or patent-encumbered codecs such as h.264 and mp3. Consider re-encoding your content with an open codec supported by Chromium or use consider using Adobe Flash to play your content.

OS X Users

Scripting

You can send and receive messages from the currently loaded browser page.

A word about JavaScript

Browsers run JavaScript, specifically, ECMAScript. JavaScript has a .js extension. Unity runs .NET languages, in particular: C# (.cs), Boo (.boo), and UnityScript (.js). Due to a terrible historical mistake, UnityScript has been, and often still is, called "JavaScript". To be clear:

UnityScript IS NOT JavaScript.

In this package all references to "JavaScript" refer to what web browsers run. Beware that UnityScript and JavaScript files both have the same .js extension. In general, files in Assets/ with a .js extension will be treated as UnityScript and files in BrowserAssets/ with a .js extension will be treated as JavaScript.

Scripting Intro

Browsers have a Browser MonoBehaviour. You can call functions in the page by invoking CallFunction:

using ZenFulcrum.EmbeddedBrowser;
...
var browser = GetComponent<Browser>();//assuming we are a MonoBehaviour attached to the same GameObject as the Browser

//calls window.setPlayerStats("myPlayerName", 2, 4200, false) in the browser
browser.CallFunction("setPlayerStats", "myPlayerName", 2, 4200, false);

Functions are resolved in the global scope of the top frame of the browser and executed with the given arguments. You can pass basic types (strings, integers, bools, etc.) without any extra effort.

You can also use EvalJS to run any JavaScript you'd like in the context of the page:

browser.EvalJS("if (someCondition()) someVar = 42;");

To query the page for data, you can look at the return value. EvalJS and CallFunction don't execute immediately, they are asynchronous, therefore they return promises:

browser.EvalJS("document.title").Then(ret => Debug.Log("Document title: " + ret));
browser.CallFunction("doSomeFoo", 1, 2, 3).Then(ret => Debug.Log("Result: " + ret));

If you are in a Unity corountine, you can wait for the promises to finish before continuing:

var promise = browser.EvalJS("document.title");
yield return promise.ToWaitFor();
Debug.Log("Document title: " + promise.Value);

This can be much easier to deal with in cases where you are chaining a lot of tasks.

See the promise section for more details on the promise library.

To receive events pushed from the page, you can expose a function callback. Do this with RegisterFunction:

browser.RegisterFunction("confirmClicked", args => Debug.Log("Button clicked: " + args[0] + " val: " + (int)args[1]));

Then you can call it from your page:

<!-- When this is clicked, Unity will log "Button clicked: button3 val: 13" -->
<button onclick="confirmClicked('button3', 13)">Confirm Things</button>

Notes

Promises

ZFBrowser uses this promise library made by Real Serious Games with some small changes.

Original documentation can be found here or online here.

This copy has been modified a bit from the version you can get from GitHub, namely:

The promise library is covered by the MIT license, as noted in ThirdPartyNoticies.txt.

Embedded Resources

You can embed web resources (HTML, JS, CSS, images, etc.) with your game and access them without the need for an external web server.

Place these resources in a folder named BrowserAssets next to your Assets folder, then access them with localGame://index.html instead of the usual http://example.com/index.html.

Notes

Input

All mouse/keyboard input events are collected in Unity and forwarded to the underlying browser. How this input is sent can be customized.

Customization

Debugging

Page Debugging

Often during development, you will find your pages need debugging.

Tip: You don't always have to restart the game to test a change, in some cases you can simply refresh the page. (Unity inspector -> browser instance -> Refresh or Page inspector -> ctrl+r).

Here's a few way to go about it:

Page Inspector

You can access the Webkit/Chromium inspector, which opens in a new window beside the running game.

External Page Inspector

You can access the page inspector from another browser.

Ordinary Browser

You can also load your pages in an ordinary browser and debug them there. If you do, you may find it useful to create small "log what happened" stubs for the functions you expose from Unity. Call functions you want to test from the JavaScript console.

Visual Studio Tools for Unity

Chromium/CEF don't play nice with Visual Studio Tools for Unity. If you want to use C# debugging with this tool, push Chromium out of process.

Chromium out of Process

Under the Windows Unity Editor we host the root Chromium process within the Unity Editor. This gives us better performance, but causes some issues such as inspector and debugger stability/usability.

If you are having issues, you can push Chromium out of the Editor process. It's a bit slower, but should be more stable for these use cases. To do this, open up BrowserNative.cs and find where PROXY_BROWSER_API is defined. Add UNITY_EDITOR_WIN to the list of conditions that trigger it and restart the Editor.

On OS X and Linux, the root Chromium process always runs outside the editor.

On builds, the root Chromium process always runs within your game for best performance.

Cookies

Notes

Latency/Performance

The browser is rendered offscreen in a separate process and the resulting pixels are transferred to a texture. Performance will not be as good as native Chromium, but should be fine when using either small textures or minimal animation.

Latency:

Performance:

Adobe Flash

This version of ZFBrowser includes experimental support for Adobe Flash. Enabling it requires some extra steps.

Do I need it?

The Web is an evolving place and ever-increasingly interactive web sties don't need Flash to support media-rich content.

You need Flash if you want to:

For myself (manual install)

If you are developing locally, prototyping, or will only distribute your application to computers that you control, use this method.

Instructions:

You'll need to install Flash on every computer you distribute your application to.

For anyone (distribute Flash)

To distribute Flash with your application, you'll need to get permission from Adobe and run their installer with your installer.

General flow: Untested, let me know how it goes!

Known issues

Ideas

Get Help

Need help? https://zenfulcrum.com/contact