Legacy Documentation: Version 4.5
Previous
HTML code to load Unity content
Next
Customizing the Unity Web Player loading screen

Working with UnityObject2

UnityObject2 is a JavaScript script that simplifies Unity content embedding into HTML and allows you to customize the install process. Having a custom install UI that matches your game and website, will create a more engaging and pleasurable experience for the end-user. It has functions to detect the Unity Web Player plugin, initiate Web Player installation and embed Unity content. Although it’s possible to deploy UnityObject2.js file on the web server alongside the HTML file it’s best to load it directly from the Unity server at http://webplayer.unity3d.com/download_webplayer–3.x/3.0/uo/UnityObject2.js or https://ssl-webplayer.unity3d.com/download_webplayer–3.x/3.0/uo/UnityObject2.js for https support. That way you will always reference the most up to date version of UnityObject2. Please note that the UnityObject2.js file hosted on the Unity server is minified to make it smaller and save traffic. If you want to explore the source code you can find the original file in the Data\Resources folder on Windows and the Contents/Resources folder on Mac OS X. UnityObject2 by default sends anonymous data to GoogleAnalytics which is used to help us identify installation type and conversion rate. UnityObject2 depends on jQuery.

Constructor

You will need to create a new instance of the unityObject2 for each Unity content present on the page.

Parameters:

  • configuration - An object containing the configuration for this instance. Those are the available members:
    • width - Default: 100%, Width of Unity content. Can be specified in pixel values (e.g. 600, “450”) or in percentage values (e.g. “50%”, “100%”). Note that percentage values are relative to the parent element.
    • height - Default: 100%, Height of Unity content. Can be specified in pixel values (e.g. 600, “450”) or in percentage values (e.g. “50%”, “100%”). Note that percentage values are relative to the parent element.
    • fullInstall - Default: false, Installs the full Web Player if not available. Normally only a small part of the Web Player is installed and the remaining files are automatically downloaded later.
    • enableJava - Default: true, Enables Java based installation. Some platforms doesn’t support this feature.
    • enableClickOnce - Default: true, Enables ClickOnce based installation. Only works on Internet Explorer browsers.
    • enableUnityAnalytics - Default: true, Notifies Unity about Web Player installation. This doesn’t do anything if the Web Player is already installed.
    • enableGoogleAnalytics -Default: true, Notifies Unity about Web Player installation using Google Analytics. This doesn’t do anything if the Web Player is already installed.
    • params - Default: {}, Extra parameters to be used when embedding the Player. Those are usefull to customize the Unity experience:
      • backgroundcolor - Default: “FFFFFF”, The background color of the web player content display region during loading, the default is white. Pro Only
      • bordercolor - Default: “FFFFFF”, The color of the one pixel border drawn around the web player content display region during loading. Pro Only
      • textcolor - Default: “000000”, The color of error message text (when data file fails to load for example). Pro Only
      • logoimage - Default: unity Logo, The path to a custom logo image, the logo image is drawn centered within the web player content display region during loading. Pro Only
      • progressbarimage - The path to a custom image used as the progress bar during loading. The progress bar image width is clipped based on the amount of file loading completed, therefore it starts with a zero pixel width and animates to its original width when the loading is complete. The progress bar is drawn beneath the logo image. Pro Only
      • progressframeimage - The path to a custom image used to frame the progress bar during loading. Pro Only
      • disableContextMenu - This parameter controls whether or not the Unity Web Player displays a context menu when the user right- or control-clicks on the content. Setting it to true prevents the context menu from appearing and allows content to utilize right-mouse behavior. To enable the context menu don’t include this parameter.
      • disableExternalCall - This parameter controls whether or not the Unity Web Player allows content to communicate with browser-based JavaScript. Setting it to true prevents browser communication and so content cannot call or execute JavaScript in the browser, the default is false.
      • disableFullscreen - This parameter controls whether or not the Unity Web Player allows content to be viewed in fullscreen mode. Setting it to true prevents fullscreen viewing and removes the “Go Fullscreen” entry from the context menu, the default is false.
    • attributes - Default: {}, Object containing list of attributes. These will be added to underlying <object> or <embed> tag depending on the browser.
    • debugLevel - Default: 0, Enables/Disables logging, useful when developing to be able to see the progress on the browser console. Set it greater to 0 to enable.

Notes: All color values provided must be 6-digit hexidecimal colors, (eg. FFFFFF, 020F16, etc.). The image paths provided can be either relative or absolute links and all image files must be RGB (without transparency) or RGBA (with transparency) 8-bit/channel PNG files. Finally, the progressframeimage and the progressbarimage should be the same height.

Functions

observeProgress

You can register a callback that will receive notifications during the plugin installation and/or initialization.

Parameters:

  • callback - Callback function that will receive information about the plugin installation/initialization. This callback will receive an progress object.
    • progress - It contains information about the current step of the plugin installation/initialization.
      • pluginStatus - Will contain a string identifying the plugin status, can be one of those:
        • unsupported` - The current Browser/OS is not supported
        • missing - Supported platform, but the plugin haven’t be installed yet.
        • installed - The plugin have finished installing, or was already installed.
        • first - called after the plugin have been installed at the first frame of the game is played (This will not be called if the plugin was already installed previously)
      • targetEl - The DOM Element serving as a container for the webplayer (This is the same element you pass to UnityObject2.initPlugin)
      • bestMethod - If the plugin is missing will contain the best installation path for the current platform, can be one of the following strings:
        • JavaInstall - It will use our “One Click” Java Applet to install the plugin
        • ClickOnceIE - It will use Internet Explorer’s Click Once install
        • Manual - It will ask the user to download a file and install it manually.
      • unityObj- A reference to the previously created unityObject2 instance responsible for this callback
      • ua - Contains some User Agent information used to decide the pluginStatus and bestMethod.

initPlugin

This will actually try to start up your game. And call the callback you previously registered at the appropriated moments. Note that

Parameters:

  • containerElement - The DOM Element serving as a container for the webplayer
  • gameURL - URL to the web player data file (.unity3d). Can be relative or absolute.

Notes: This function should be called after the containerElement is present on the DOM, to be safe, you could wait for the DOM to load completely before calling it.

installPlugin

Tries to install the plugin using the specified method. If no method is passed, it will try to use this.getBestInstallMethod().

Parameters:

  • method - Default: this.getBestInstallMethod(). A string specifying which method to use for installation. It can be one of the following values: JavaInstall, ClickOnceIE, Manual.

Notes: Not all methods are available in every platform/browser. Manual will download an exe/dmg installer and the user will need to perform a manual installation.

getUnity

This will return a reference to the player, so you can Call SendMessage from it for instance.

Notes: Will return null if the WebPlayer has not been initialized yet.

Example: This exemplifies a very simple UnityObject2 usage. If the user already has the plugin installed, the WebPlayer will load normally, otherwise it will reveal a hidden div.missing and attach a click event to the install button. After installation is succeeded, the screen is hidden, and the webplayer is loaded normally.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Unity Web Player | "Sample"</title>
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
    <script type="text/javascript">
        <!--
        var unityObjectUrl = "http://webplayer.unity3d.com/download_webplayer-3.x/3.0/uo/UnityObject2.js";
        if (document.location.protocol == 'https:')
            unityObjectUrl = unityObjectUrl.replace("http://", "https://ssl-");
        document.write('<script type="text\/javascript" src="' + unityObjectUrl + '"><\/script>');
        -->
    </script>
        <script type="text/javascript">
        var u = new UnityObject2();
        u.observeProgress(function (progress) {
            var $missingScreen = jQuery(progress.targetEl).find(".missing");
            switch(progress.pluginStatus) {
                case "unsupported":
                    showUnsupported();
                break;
                case "broken":
                    alert("You will need to restart your browser after installation.");
                break;
                case "missing":
                    $missingScreen.find("a").click(function (e) {
                        e.stopPropagation();
                        e.preventDefault();
                        u.installPlugin();
                        return false;
                    });
                    $missingScreen.show();
                break;
                case "installed":
                    $missingScreen.remove();
                break;
                case "first":
                break;
            }
        });
        jQuery(function(){
            u.initPlugin(jQuery("#unityPlayer")[0], "Example.unity3d");
        });
        </script>
    </head>
    <body>
        <p class="header">
            <span>Unity Web Player | </span>WebPlayer
        </p>
        <div class="content">
            <div id="unityPlayer">
                <div class="missing">
                    <a href="http://unity3d.com/webplayer/" title="Unity Web Player. Install now!">
                        <img alt="Unity Web Player. Install now!" src="http://webplayer.unity3d.com/installation/getunity.png" width="193" height="63" />
                    </a>
                </div>
            </div>
        </div>
        <p class="footer">&laquo; created with <a href="http://unity3d.com/unity/" title="Go to unity3d.com">Unity</a> &raquo;</p>
    </body>
</html>


Previous
HTML code to load Unity content
Next
Customizing the Unity Web Player loading screen