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().

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[]	No	List of domains to be interpreted according to aclMode. Example: signageos.io, www.example.com
options.aclMode	"blacklist" | "whitelist"	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	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	No	The browser will automatically close after a specified period of inactivity (in milliseconds).
options.coordinates	{ x: number; y: number; width: number; height: number; }	No	Size and position of the browser window. Defaults to fullscreen.
options.theme	ITheme	No	Specify custom UI theme. (Android only)
options.headlessMode	boolean	No	Headless mode hides the entire address bar. (Android only)
options.canUserClose	boolean	No	Whether the user can manually close the browser. (default if headless false, else true)
options.clearData	boolean	No	Clear cache after the browser closes. (default if headless false, else true)
options.method	"native" | "iframe"	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
});