Construct 3 icon

Construct 3

Documentation

Browser

Published 23 Aug, 2017
1,481 words
~6-10 mins

The Browser object accesses features of the browser or platform running the project. It also provides features like switching to and from fullscreen mode, detecting if an update is available, and determining 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 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.
  • By default, code is minified on export. If you do not write JavaScript that is compatible with the minifier, 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 Addon SDK is almost always a more elegant way of including custom JavaScript in Construct projects. If at all possible, write your JavaScripot in an addon using the SDK.

Browser conditions

Cookies enabled

True if the user has cookies enabled in their browser.

Is online

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

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 offline ready

Triggers the first time the project runs when it has finished downloading and is ready to use offline.

On update found

Triggers when an update is detected. The update will download in the background and trigger On update ready when it is ready to be used.

On update ready

Triggered when 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.

On resized

Triggered when the browser window displaying the game is resized. This includes when changing orientation on a mobile device.

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 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 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 project, 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 project 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 mode project property.

Browser expressions

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.

Platform

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

UserAgent

Return the full user agent string for the browser, e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.101 Safari/537.36.

Title

The current HTML document's title.

Domain

The current domain, e.g. construct.net.

Hash

The string after the hash at the end of the URL, including the hash. For example, if the current URL is https://construct.net/mygame/index.html#teapot, this returns #teapot.

PathName

The path relative to the domain in the URL. For example the path name of https://construct.net/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=ban, QueryParam("foo") returns bar and QueryParam("baz") returns ban.

QueryString

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

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.