---
sidebar_position: 0
---

# 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)
:::

<details>
    <summary>Device Browser Capabilities</summary>
		| 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).
</details>

## Methods

### close()

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

```ts expandable
close(): Promise<void>;
```

#### Return value

A promise that resolves when the browser is closed.

#### Example

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

<Separator />

### 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.

```ts expandable
onClose(listener: (event: CloseEvent) => void): () => void;
// show-more
/**
 * Interface representing a close event in the browser.
 */
interface CloseEvent extends Event<EventType.CLOSE> {
    /**
     * The reason for the browser being closed.
     */
    reason: CloseReason;
}

enum EventType {
    CLOSE = "close"
}

enum CloseReason {
    API = "API",
    USER = "USER",
    TIMEOUT = "TIMEOUT"
}

type Event<TType extends EventType = EventType> = {
    type: TType;
};

```

#### Params

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

#### Return value

A callback which removes the listener.

<Separator />

### open()

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

```ts expandable
open(uri: string, options?: IOpenLinkOptions): Promise<void>;
// show-more
/**
 * Interface defines the options for opening a link in the browser.
 */
interface IOpenLinkOptions {
    aclDomains?: string[];
    aclMode?: 'blacklist' | 'whitelist';
    readOnlyAddressBar?: boolean;
    idleTimeout?: number;
    coordinates?: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    theme?: ITheme;
    headlessMode?: boolean;
    clearData?: boolean;
    canUserClose?: boolean;
    /**
     * Method of opening the link.
     * @default 'native'
     */
    method?: 'native' | 'iframe';
}

type ITheme = {
    base?: 'light' | 'dark';
    shape?: {
        cornerSize?: number;
    };
    colors?: {
        primary?: Color;
        background?: Color;
        control?: Color;
    };
    widgets?: {
        editAddress?: {
            colors?: {
                background?: Color;
                text?: Color;
            };
        };
        buttonClose?: {
            colors?: {
                background?: Color | '@primary';
                text?: Color;
                icon?: Color;
            };
            icon?: 'none' | 'exit_to_app' | 'close' | 'cancel';
            text?: string;
        };
        progress?: {
            color?: Color | '@primary';
        };
    };
};

```

#### Params

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

```ts
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,
});
```

:::note[GitHub Example]

- [ Example of Applet for using browser on Android ](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/browser)

:::

<Separator />

### ~openLink()~

:::danger Deprecated

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

:::

```ts expandable
openLink(uri: string, options?: IDeprecatedOpenLinkOptions): Promise<void>;
// show-more
/** @deprecated */
interface IDeprecatedOpenLinkOptions {
    acl?: RegExp[];
    aclMode?: 'blacklist' | 'whitelist';
    readOnlyAddressBar?: boolean;
    idleTimeout?: number;
    theme?: ITheme;
}

type ITheme = {
    base?: 'light' | 'dark';
    shape?: {
        cornerSize?: number;
    };
    colors?: {
        primary?: Color;
        background?: Color;
        control?: Color;
    };
    widgets?: {
        editAddress?: {
            colors?: {
                background?: Color;
                text?: Color;
            };
        };
        buttonClose?: {
            colors?: {
                background?: Color | '@primary';
                text?: Color;
                icon?: Color;
            };
            icon?: 'none' | 'exit_to_app' | 'close' | 'cancel';
            text?: string;
        };
        progress?: {
            color?: Color | '@primary';
        };
    };
};

```

## API Example

```ts
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
});

```