Browser

The Browser object accesses features of the web browser running the HTML5 game. It also switch to and from fullscreen mode, detect if the game is updating in the background, and determine if the page is visible.

Security limitations sometimes prevent browser actions. For example, the window Close action can only be used when the window was created by a javascript window.open call.

Risks with Javascript string execution

The Browser object provides two ways to run a string as Javascript code: the Execute Javascript action, and the ExecJS expression. While occasionally useful, these are widely regarded as dangerous.

Here are a couple of the problems you may experience with these features:

  • If you execute a string containing user input, it's possible the user can inject javascript to be executed. This can cause a security vulnerability, crash the game, or allow the user to cheat.
  • If you inadvertently use a feature only available on certain platforms, your game will crash on other platforms that do not support the feature. Construct 2 normally protects you from this since it's well-tested on many platforms, but it's an easy mistake to make if you execute Javascript by yourself. Certain non-browser platforms like CocoonJS have a very limited feature set available so are especially easy to break.
  • By default, code is minified on export. If you do not write Javascript that is compatible with Google Closure Compiler's ADVANCED mode, it may be broken and crash the game after export.
  • Executing strings of Javascript from events can often result in dense and unreadable code which is difficult to modify in future.

Using the official Javascript SDK is almost always a more elegant way of including custom Javascript in Construct 2 projects. If at all possible, write your javascript in a plugin using the SDK.

Browser conditions

Cookies enabled
True if the user has cookies enabled in their browser. (Typically it is rare for them to be disabled since many web sites rely on cookies to work properly.)

Is online
True if the browser currently has an active connection to the internet. Construct 2 games can work offline - see Offline games for more information.

On resized
Triggered when the browser window displaying the game is resized. This includes when changing orientation on a mobile device. The system expressions WindowWidth and WindowHeight will update to reflect the new size if a fullscreen mode is in use.

On went online
On went offline
Triggered if the connection to the internet is becomes available or unavailable during the running of the game. This is common on mobile devices which may be moving in and out of signal areas. The Is online condition also changes to reflect the connection status.

Is portrait/landscape
Determine if the current display is portrait (height is greater than width) or landscape (width is greater than height). This is performed by making a simple check on the window size of the browser, so also returns accordingly on a desktop browser depending on its dimensions.

On back button
Triggered when the user presses the device's 'Back' button. Note not all devices have this button (e.g. iOS devices only have a 'Home' button) and not all platforms support this trigger.

On menu button
Triggered when the user presses the device's 'Menu' button. Note not all devices have this button (e.g. iOS devices only have a 'Home' button) and not all platforms support this trigger.

On search button
Triggered when the user presses the device's 'Search' button. Note not all devices have this button (e.g. iOS devices only have a 'Home' button) and not all platforms support this trigger.

Is downloading update
True if the game is running from cache, but downloading an updated version in the background. This can be used to implement a simple auto-updater. See Offline games for more information.

On update ready
Triggered when the game is running from cache, but an updated version has finished downloading in the background. If the user is still on the game's menu or title screen, you may wish to prompt them to refresh the page (or just do it automatically) so the new version is loaded. See Offline games for more information.

Is fullscreen
True if the browser is running in fullscreen mode.

Page is visible
True if the page the HTML5 game is running on is currently visible. The page counts as hidden if the window is minimised, the page is in a different tab to the one being viewed, or on a mobile device when the app goes in to the background. When the page is hidden the game automatically pauses.

On suspended
On resumed
Triggered when the page's visibility changes, or when a mobile app is going in to the background or foreground. When invisible or in the background the app is suspended: all events stop running and all audio is muted.

Supports requesting fullscreen
True if the current platform supports the Request fullscreen action. This can be used to determine whether a fullscreen button should be shown.

Browser actions

Execute Javascript
Run a string of Javascript code. Great care is necessary to use this correctly - see the section 'Risks with Javascript string execution' above.

Start group
End group
Start or end a group in the browser error console. Groups appear indented, and the browser may give the option to expand/collapse the group easily. Groups can optionally be named. To create a group, use Start group, then a series of Log actions, then the End group action.

Log
Log a message, warning or error to the browser error console. This can be useful for debugging, testing and diagnostics.

Vibrate
Vibrate the device with a given pattern, if the device/platform supports vibration. The pattern is given as a comma-separated list of times in milliseconds, alternating between vibrate time and waiting. For example the string "200,100,200" specifies a 200ms vibration, 100ms pause, then another 200ms vibration. This allows a single action to specify a whole vibrate pattern.

Go back
Go forward
Move through the browser navigation history as if clicking the Back and Forward buttons on the browser.

Go home
Navigate to the browser's set homepage.

Go to URL
Navigate to a given URL. Note this uses the same window/tab as is showing the HTML5 game, so this action will end the game. The Target can be used to select which frame to redirect, which is only useful if the game is displayed within a frame (e.g. an iframe embed), and the frame has permission to redirect the parent frame (i.e. it is not sandboxed). Possible targets are:
Self: redirect only the frame that is currently showing the game.
Parent: redirect the parent frame.
Top: redirect the top level frame (only different to the parent if more than one frame is used)

Invoke download
Invoke a URL as a file download in the browser. Even if this points to a web page or document, it will be downloaded as a file in the browser interface. The URL can point to any address on the Internet, or it can be the name of any imported project file, or it can be a data URL (useful for downloading canvas snapshots). The filename parameter allows you to choose the filename the browser gives to the download, which can be different to the name of the resource being downloaded.

Invoke download of string
As with Invoke download, but instead of providing a URL to download, a string of the actual data to download as a file is used. A data URI combining the MIME type and data is created, then passed to the browser to download. This is convenient for downloading strings in JSON format as files, e.g. object data from the AsJSON expression.

Open URL in new window
Navigate to a given URL in a new window (or tab if the browser settings override). This continues to run the HTML5 game in the old window or tab.

Reload
Force the page to refresh. This effectively restarts the game.

Alert
Bring up a simple 'alert' message box.

Blur
Unfocus the browser window.

Cancel fullscreen
Return to windowed mode if the browser is currently in fullscreen mode.

Close
Close the current window, if the script has permission to do so.

Focus
Focus the browser window.

Lock orientation
Unlock orientation
Lock the display of the game to a portrait or landscape mode only, if the current platform supports this. This only has effect on mobile devices. The game may have to already be displaying in fullscreen (using the Request fullscreen action) before the orientation can be locked. Unlocking the orientation restores whatever behavior was set before locking, such as automatically changing orientation depending on the way the device is being held.

Request fullscreen
Request that the browser enter fullscreen mode. Note the browser may ignore this request unless the action is in a user-initiated event, such as a mouse click, key press, touch event or button press. The fullscreen modes that can be entered correspond to the Fullscreen in browser project property. For more information see supporting multiple screen sizes. Note not all platforms support requesting fullscreen - use the Supports requesting fullscreen condition to check for availability.

Browser expressions

BatteryLevel
Return the current battery charge level from 0 (discharged) to 1 (fully charged). For example, to get the battery level as a percentage, use round(Browser.BatteryLevel * 100). If the device does not have a battery or the level is unknown, returns 1.

BatteryTimeLeft
If the device has a battery and the remaining time is known, returns the estimated time in seconds until the system will have to shut down due to battery discharge. If no battery is present or the time left is unknown, returns infinity.

ExecJS
Run a string of Javascript code, and return the result if it is a string or a number. Great care is necessary to use this correctly - see the section 'Risks with Javascript string execution' above.

Language
Get the browser's current language setting, e.g. en-US.

Name
Get the name the browser reports for itself. This may be inaccurate for backwards compatibility reasons, e.g. Google Chrome reports its name as Netscape.

Platform
Get the current platform the browser reports itself running on, e.g. Win32 for Windows.

Product
Get the product the browser reports for itself. This may be inaccurate for backwards compatibility reasons, e.g. Google Chrome reports its product as Gecko.

UserAgent
Return the full user agent string for the browser, e.g. Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.63.

Vendor
Get the vendor the browser reports for itself, e.g. Google Inc. for Google Chrome.

Version
Get the version the browser reports for itself as a string. This can simply be a subset of the user agent string.

Bandwidth
The estimated available bandwidth in megabits per second of the detected connection technology. Note this may not be a reliable value - for example if the browser detects it is connected via Ethernet it may report the estimated Ethernet bandwidth, whereas further up the network is a router with a lower bandwidth. If the bandwidth is unknown, it returns positive infinity.

ConnectionType
The type of connection technology in use if it is known. This can be "bluetooth", "cellular", "ethernet", "wifi", "wimax", "other", "unknown" or "none" (indicating offline mode).

DevicePixelRatio
The number of physical display pixels per CSS pixel. This can be a useful indicator of display density. For example, 'retina' displays report the value as 2, whereas ordinary displays report the value as 1.

ScreenWidth
ScreenHeight
Retrieve the dimensions of the entire device screen. This is the complete display area available to the operating system.

Title
The current HTML document's title.

Domain
The current domain, e.g. scirra.com.

Hash
The string after the hash at the end of the URL, including the hash. For example, if the current URL is http://scirra.com/mygame/index.html#teapot, this returns #teapot.

PathName
The path relative to the domain in the URL. For example the path name of http://scirra.com/mygame/index.html#teapot is /mygame/index.html.

Protocol
The current protocol, usually either http: or https:.

QueryParam
Return a query string parameter by name. For example, if the URL ends with index.html?foo=bar&baz=wan, QueryParam("foo") returns bar and QueryParam("baz") returns wan.

QueryString
Return the full URL query string including the question mark. For example, if the URL ends with index.html?foo=bar&baz=wan, this returns ?foo=bar&baz=wan.

Referrer
Get the previous page that linked to this page, if any.

URL
Get the complete current URL in the browser address bar, including the protocol.

Tags: