browser

There are several use cases when you need to open a web browser on a touch-enabled device (also known as a tablet). For these cases, you can use a custom web browser we built. Default URL can be opened and even the whitelisting/blacklisting of certain domains is supported.

info

This API is currently available on:

• Android devices with Android 5+ (Philips, Benq, Sharp, generic Android device)

With some limitations, you can also use this API on

• Samsung Tizen (SSSP 4 and above); where the website is just in fullscreen without an address bar or theme options (headless mode)
• LG webOS (webOS 3.0 and above); where the website is just in fullscreen without an address bar or theme options (headless mode)
• Linux (Fedora, Ubuntu), Raspberry Pi, NEC Compute Module; where the website is just in fullscreen without an address bar or theme options (headless mode)
• BrightSign; where the website is just in fullscreen without an address bar or theme options (headless mode)

Device Browser Capabilities

| Capability | Description | |:------------|:-------------| | `BROWSER` | If device can open browser with custom URL |

	If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).

Methods

close()

The close() method closes the browser window opened by the open() method.

close(): Promise<void>;

Return value

A promise that resolves when the browser is closed.

Example

await sos.browser.open('https://www.signageos.io', {
	readOnlyAddressBar: true,
});
// some time later
await sos.browser.close();

onClose()

The onClose() method sets up a listener, which is called whenever a browser window is closed. This can happen by an API call, by a user request or after a timeout. This doesn't fire between open calls or on subsequent close calls.

onClose(listener: (event: CloseEvent) => void): () => void;

Params

Name	Type	Required	Description
listener	(event: CloseEvent) => void	Yes	The listener to be called when the browser is closed.

Return value

A callback which removes the listener.

open()

The open() method opens the specified url in a browser window.

open(uri: string, options?: IOpenLinkOptions): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	The URL to open in the browser.
options	IOpenLinkOptions	No	Optional parameters to configure the browser window.
options.aclDomains	string[] | undefined	No	List of domains to be interpreted according to aclMode. Example: signageos.io, www.example.com
options.aclMode	"blacklist" | "whitelist" | undefined	No	blacklist – Allow access to all domains except those in aclDomains and their subdomains, whitelist – Allow access only to domains in aclDomains and their subdomains.
options.readOnlyAddressBar	boolean | undefined	No	If true, the address bar is read-only, if false the user can navigate away by entering a URL in the address bar.
options.idleTimeout	number | undefined	No	The browser will automatically close after a specified period of inactivity (in milliseconds).
options.coordinates	{ x: number; y: number; width: number; height: number; } | undefined	No	Size and position of the browser window. Defaults to fullscreen.
options.theme	ITheme | undefined	No	Specify custom UI theme. (Android only)
options.headlessMode	boolean | undefined	No	Headless mode hides the entire address bar. (Android only)
options.canUserClose	boolean | undefined	No	Whether the user can manually close the browser. (default if headless false, else true)
options.clearData	boolean | undefined	No	Clear cache after the browser closes. (default if headless false, else true)
options.method	"native" | "iframe" | undefined	No	Can only be native (which opens a new, fully sandboxed fullscreen window) or iframe (which opens a configurable-sized window). (only Linux)

Return value

A promise that resolves when the browser is opened.

Possible errors

• If the uri is not a valid URL or string.
• If the options are not valid.
• If unexpected error occurred when opening link.

Example

await sos.browser.open('https://www.signageos.io', {
	aclDomains: ['google.com', 'yahoo.com'],
	aclMode: 'blacklist', // or 'whitelist'
	readOnlyAddressBar: true,
	coordinates: { // Supported only on Linux and Android
		x: 0,
		y: 0,
		height: 500,
		width: 500,
	},
	// theme: { ... }
	headlessMode: false,
});

GitHub Example

• Example of Applet for using browser on Android

openLink()

Deprecated

This method was deprecated. use sos.browser.open() instead

openLink(uri: string, options?: IDeprecatedOpenLinkOptions): Promise<void>;

API Example

import { sos } from '@signageos/front-applet';

void sos.onReady(async () => {
	await sos.browser.open('https://www.signageos.io', {
		aclDomains: ['google.com', 'yahoo.com'],
		aclMode: 'blacklist', // or 'whitelist'
		readOnlyAddressBar: true,
		coordinates: {
			// Supported only on Linux and Android
			x: 0,
			y: 0,
			height: 500,
			width: 500,
		},
		// theme: { ... } // supported only on Android
		headlessMode: false, // supported only on Android
	});

	await sos.browser.close(); // Close the browser
});