Browser

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.

Scripting

This object has no script interface, because when using JavaScript or TypeScript coding you can use the browser built-in APIs to access the same features.

Warning about executing JavaScript

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 can be dangerous if mis-used. 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.
  • It can be difficult to write lots of code, or read what has been written, since it must fit inside an expression.

There are two alternatives to using the Browser plugin to run JavaScript code which are usually better options:

  1. Use the scripting feature of Construct, which is a dedicated way to enter JavaScript code in the editor. This has much better editing tools, is safer, and better supported.
  2. Use the Addon SDK to write a custom plugin or behavior that runs your JavaScript code. You can add actions, conditions and expressions to access the feature, making it work naturally with the rest of the event system. However there is additional work involved in setting up an addon.

Wherever possible, prefer to write your JavaScript code using one of the above options rather than using the Browser object.

Browser conditions

Cookies enabled
True if the user has cookies enabled in their browser.
Is online
True if the browser thinks it currently has an active connection to the Internet. Construct projects can work offline - see Offline games for more information.
On went online
On went offline
Triggered when the browser thinks the connection to the Internet has become available or unavailable during the running of the project. 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 hash change
Triggered when the part of the URL after the hash character (e.g. example.com/index.html#hashpart) changes. The Hash expression will return the new value.
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 project'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 after using the Request fullscreen action.
On resized
Triggered when the browser window displaying the project 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.
Load stylesheet
Load a Cascading Style Sheet (CSS) from a URL and applies its styles to the document. This can be useful for styling form controls and other DOM elements. The URL can also be the name of a project file, such as "myfile.css", to load a CSS file included in the project.
Set CSS style
Set a CSS style on the style attribute of some HTML elements in the document, based on a CSS property name and a string for its value. Setting the value to an empty string will remove the property from the style attribute. The element to change the style for is set by a CSS selector, e.g. ".myclass" will mean to update the CSS style of an element with the class myclass; if the Type is set to all, it will update the style of all elements matching the selector.
Get CSS style
Retrieve a string with the computed style value for a CSS property on an element given by a CSS selector. When the action finishes, the value is returned by the CSSStyleValue expression. A tag is used to identify different CSS style values.
Go back
Go forward
Move through the browser navigation history as if clicking the Back and Forward buttons on the browser.
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 project. The Target can be used to select which frame to redirect, which is only useful if the project 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 project.

  • 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 project.
Set hash
Set the part of the URL after the hash character (e.g. example.com/index.html#hashpart). Note this does not reload the page, so the hash part of the URL can be used as a kind of mode or identifier that can be changed while the project is running.
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 project to a portrait or landscape mode only, if the current platform supports this. This only has effect on mobile devices. The project 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. Navigation UI where supported sets whether the browser should show browser elements such as back buttons or the address bar, or hide them (for a true fullscreen experience). Typically this setting only affects mobile browsers.
Set window size
Set window position
Set the size and position of the main window. This is only applicable on desktop-style systems - mobile devices typically use fullscreen apps and therefore windows cannot be repositioned or resized.

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.
CSSStyleValue(tag)
Get the CSS style value retrieved from a prior call to the Get CSS style action. Once the action has finished (using Wait for previous actions to complete), pass the same tag as the action was called with to retrieve the result.
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 example.com/index.html#hashpart, this returns #hashpart.
PathName
The path relative to the domain in the URL. For example the path name of https://construct.net/myproject/index.html#teapot is /myproject/index.html.
Port
A string of the port specified in the URL, if any. Note while ports are numbers, this expression returns a string, since if no port is specified in the URL it will return an empty string.
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.
Construct 3 Manual 2024-02-16