@signageos/front-applet 7.2.0 → 8.0.0

package/docs/applet-basics.md

@@ -1,272 +0,0 @@
----
-title:  Applet Basics
-author: Miroslav Behina
-date:   22.11.2018
-type:   js-api
-tags:
-- applet
-- applet_api
-- api
-- js_api
-description: "[Content JS API] This thread contains basic methods of every Applet used to load necessary configuration or device identifications and how to create Applet."
----
-
-# Applet Basics
-
-This thread contains basic methods of every Applet used to load necessary configuration or device identifications and how to create Applet.
-
-## All methods and properties
-
-
-| Methods/Property  | Description | Supported since |
-| ----------------- | ----------- | :---------------: |
-| `onReady()`         | This method will wait until sOS object library and all dependencies are ready to be used. | 1.0.0 |
-| `restore()`         | Clear all previously played videos, streams, clear display view. | 1.0.0 |
-| `refresh()`         | This method will refresh the applet data and launch it again | 5.8.0 |
-| `appletVersion`  | Returns current Applet version | JS API `4.5.0`, Front-display `7.8.0`|
-| `config` object  | Returns object with key-values set via Timing or as a bundled config| JS API `1.5.0`, Front-display `6.8.0`|
-| `config` object  | Returns object with key-values set via Timing or as a bundled config| `1.0.0`|
-| `authHash` token  | Returns string with unique device identifier | `1.0.0`|
-| `capabilities`  | Enum of device-specific capabilities and features | `1.0.0`
-
-## Starting Applet
-
-Your applet logic should be started **after sOS object is loaded and ready**. To start your applet you can use this example snippet.
-
-### Javascript example:
-``` javascript
-/* 
-CLI generated Applet 
-*/
-sos.onReady().then(async function () {
-  startYourApplet(); // Example method to run
-  // Any other code
-}
-
-/* 
-Deprecated single file Applet options
-*/
-
-// option A
-window.addEventListener('sos.loaded', () => {
-  sos.onReady().then(() => {
-    startYourApplet(); // Example method to run
-    // Any other code
-  });
-});
-
-// option B
-async function startApplet() {
-			await sos.onReady();
-      // Any other code
-}
-window.addEventListener('sos.loaded', startApplet);
-```
-
-After sOS object is ready, there are global properties available, which can be used for Applet customization and device identification.
-
-### Javascript syntax:
-```javascript
-// Authentication hash string to secure access to device resources in REST API
-console.log(sos.authHash);
- 
-// Parsed JSON object passed to Timing for current applet & current device together
-console.log(sos.config);
-```
-
-## onReady()
-This method will wait until sOS object library and all dependencies are ready to be used.
-
-:::danger
-Every Applet must contain this method, otherwise it won't work.
-:::
-
-### Javascript example:
-```javascript
-/* 
-CLI generated Applet 
-*/
-sos.onReady().then(async function () {
-  console.log('sos is ready', sos); // Print sOS object into console
-    // Any other methods to prepare your content and applet
-}
-
-/* 
-Deprecated single file Applet options
-*/
-window.addEventListener('sos.loaded',() => {
-  sos.onReady().then(() => {
-    console.log('sos is ready', sos); // Print sOS object into console
-    // Any other methods to prepare your content and applet
-  });
-});
-```
-
-:::note[GitHub Example]
-[Example of Applet for basic start](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/restore)
-:::
-
-## restore()
-The typical case of usage for digital signage is playing a loop with some specified duration. This method should be called always when the loop is changed. It will clear all previously played videos, streams, clear display views, and notify for garbage collection.  
-It stops all video playback and clears out the memory. The following function should be triggered **only** in a case the whole playback needs to be restarted as it's completely switching the playback 'loop/playlist'.
-
-### Javascript example:
-```javascript
-/* 
-CLI generated Applet 
-*/
-sos.onReady().then(async function () {
-  console.log('sos is ready', sos);
-  // Any other methods to prepare, load and run content on screen
-  sos.restore();
-}
-
-/* 
-Deprecated single file Applet options
-*/
-window.addEventListener('sos.loaded', () => {
-  sos.onReady().then(() => {
-    console.log('sos is ready', sos);
-    // Any other methods to prepare, load and run content on screen
-    sos.restore();
-  });
-});
-```
-
-:::note[GitHub Example]
-[Example of Applet with restore() method](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/restore)
-:::
-
-## refresh()
-AFter calling this method applet is freshly launched.
-
-### Javascript example:
-```javascript
-await sos.refresh()
-```
-
-## appletVersion
-This property returns current active Applet version.
-
-### Javascript example:
-
-```javascript
-/* 
-CLI generated Applet 
-*/
-sos.onReady().then(async function () {
-  console.log('Your applet version is ' + sos.appletVersion));
-}
-
-/* 
-Deprecated single file Applet options
-*/
-window.addEventListener('sos.loaded',() => {
-  sos.onReady().then(() => console.log('Your applet version is ' + sos.appletVersion));
-});
-```
-
-## Custom variables in Applet
-
-You can pass CUSTOM key-value variables to the Applet. To do that, add your values as a Timing configuration (over Box of [Timings API](https://docs.signageos.io/hc/en-us/articles/4405238989458)). Then you can access your values via `sos.config` object.
-
-```javascript
-// Parsed JSON object passed to Timing for current applet & current device together
-console.log(sos.config.mySecretID);
-console.log(sos.config.imgUrl);
-```
-
-:::note[Guide]
-[Custom variables in Applet](https://developers.signageos.io/docs/devspace-extras/env-variables-configuration)
-
-How to pass custom variables and configuration to your Applet.
-:::
-
-## The authHash for unique device identification
-
-The `sos.authHash` is an alternative device identifier designed for secure pairing and locating devices through the REST API.
-
-1. The `authHash` is commonly used as a link between the Applet deployed on the device and the device in device management.
-1. The `authHash` is unique and can be revoked upon request.
-1. The `authHash` can be used as a universal identifier for your Applet application.
-
-The `authHash` can be retrieved from the JS SDK API - it's available as `sos.authHash`. 
-
-```javascript
-async function startApplet() {
-			await sos.onReady();
-      console.log(sos.authHash);
-}
-window.addEventListener('sos.loaded', startApplet);
-```
-
-:::note[Guide]
-[Using authHash for device identification](https://developers.signageos.io/docs/devspace-extras/sos-authhash-device-pairing.md)
-
-How to get `authHash` and use it in the REST API for device identification.
-:::
-
-## Applet JS API version
-
-Each feature has “Supported since” that states for the Applet JS API version. The Applet JS API component is called Front-Applet and its version can be selected under the Applet editor.
-
-## Capabilities
-
-Even tough we do our best to support as many features as possible on every platform, it's not possible to use certain features on certain platforms.
-That's why we also provide a capabilities API that allows you to check, if the particular device supports a feature before you try to use it.
-It's recommended that you always include capability checks in your code to prevent unexpected behavior or errors in your application.
-
-There are two kinds of capabilities - display and management.
-
-### Display capabilities
-
-Display capabilities refer to the capabilities of the display in terms of content, playback, peripherals, etc.
-
-
-| Capability                     | Description                                                                               |
-| ------------------------------ | ----------------------------------------------------------------------------------------- |
-| `FILE_SYSTEM_EXTERNAL_STORAGE` | Device file system supports [external storage](content/js-file-system) (i.e. flash drives)                          |
-| `FILE_SYSTEM_FILE_CHECKSUM`    | Device is can [calculate a file checksum](content/js-file-system#getfilechecksum) |
-| `VIDEO_4K`                     | Device is capable of [playing 4K video](content/js-video)                                                     |
-| `SERIAL`                       | Device supports communication with peripherals over [serial](content/js-serial)                                
-
-#### Javascript example:
-
-```javascript
-if (await sos.display.supports('VIDEO_4K')) {
-	// play 4K video
-}
-```
-
-:::note[GitHub Example]
-[Example of Content Capabilities](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/capabilities-content)
-:::
-
-
-### Management capabilities
-
-Management capabilities refer to the capabilities of the display's internal state management.
-
-
-| Capability                     | Description                                                                               |
-| ------------------------------ | ----------------------------------------------------------------------------------------- |
-| `BATTERY_STATUS` | Device can [report its battery status](management/js-management-management#getbatterystatus). |
-| `WIFI` | Device can [connect to a Wi-Fi](management/js-management-wifi#connect). |
-| `WIFI_SCAN` | Device can [scan surrounding Wi-Fi devices](management/js-management-wifi#scandevices). |
-| `WIFI_AP` | Device is capable of [becoming a Wi-Fi endpoint](management/js-management-wifi#enableap) that other devices can connect to. |
-| `SET_BRIGHTNESS` | Device can change its [screen brightness](management/js-management-screen#setbrightness). |
-| `SET_TIME` | Device can change its [time settings](management/js-management-time). |
-| `NTP_TIME` | Device can [synchronize its time with an NTP server](management/js-management-time#setntp). |
-| `PACKAGE_INSTALL` | It's possible to [install additional packages](management/js-management-package) on the device, managed by signageOS application. |
-| `SET_VOLUME` | Device can change its [audio volume](management/js-management-audio). |
-| `SET_REMOTE_CONTROL_ENABLED` | Device can [disable control via IR remote](management/js-management-remote-control) to increase security. 
-
-```javascript
-if (await sos.management.supports('WIFI')) {
-	// connect to wifi
-}
-```
-
-:::note[GitHub Example]
-[Example of Management Capabilities](https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/capabilities-management)
-:::

package/docs/content/js-applet-resources.md

@@ -1,154 +0,0 @@
----
-title:  Applet Resources
-author: Miroslav Behina
-date:   22.11.2018
-type:   js-api
-tags:
-- applet
-- applet_api
-- api
-- js_api
-description: "[Content JS API] Often there are some JavaScripts and CSS styles necessary to be loaded for your Applet. It can be libraries like jQuery or even your whole application code. For these necessities offline API for saving, storing & loading files are ready."
----
-
-# Applet Resources
-
-Often there are some JavaScripts and CSS styles necessary to be loaded for your Applet. 
-It can be libraries like jQuery or even your whole application code. For these necessities offline API for saving, storing & loading files are ready.
-
-| Methods | Description | Supported since |
-| ------- | ----------- | ------ |
-| `addFile()` | Add single file to Applet before starting it. | 1.0.0 |
-| `addFiles()` | Add files to Applet before starting it. | 1.0.0 |
-| `addFilesSync()` | Add files to Applet before starting it in the set order to prevent race condition. | 1.0.0 
-
-### File object
-Every method above, accept single object or array of objects depending by type. Every object **must have** these keys.
-
-
-| Key | Type | Required | Description |
-| :-----: | :-----: | :----: | ------- |
-| `uri` | String | <div class="red">Yes</div> | URL of file |
-| `uid` | String | <div class="red">Yes</div> | Unique ID in Applet for future manage |
-| `type` | String | <div class="red">Yes</div> | Type of file. Example: `sos.offline.types.javascript`, `sos.offline.types.css`, `sos.offline.types.video` |
-|||| ^^ |
-| `flags` | Array | <div class="red">Yes</div> | Special flag for file |
-| `headers` | Array | <div class="yellow">No</div> |  Authorization headers 
-
-:::info
-* The file URL must point to a file. If your URI leads to a 303 redirect (e.g. from http to http**s**), the API will not work.
-* There are some limitations for [Emulator](https://docs.signageos.io/hc/en-us/articles/4405238997138). 
-:::
-
-## addFile()
-Method `addFile()` will allow you to load single resource into applet. If you want to load more resource, use `addFiles()`.
-
-### Javascript Example
-```javascript
-const file = { // File that will be loaded into an applet
-    "uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
-    "uid": "jquery-2.2.4.min.js",
-    "type": sos.offline.types.javascript,
-    "flags": [sos.offline.flags.append(document.body)]
-}
-
-await sos.offline.addFile(file); // And finally load file
-```
-
-## addFiles()
-Method `addFiles()` will allow you to load array of your resources into Applet. Files are load in random order.
-
-### Javascript Example
-```javascript
-const files = [ // Array of files
-	{
-		"uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
-		"uid": "jquery-2.2.4.min.js",
-		"type": sos.offline.types.javascript,
-		"flags": [sos.offline.flags.append(document.body)]
-	},
-	{
-		"uri": "https://signageostest.blob.core.windows.net/test/applet-examples/benchmark-styles.css?v=1.0.0",
-		"uid": "benchmark-styles.css-v1.0.0",
-		"type": sos.offline.types.css,
-		"headers": { "Authorization": "Basic Zm9vOmJhcg==" },
-		"flags": [sos.offline.flags.append(document.head)]
-	}
-];
-
-await sos.offline.addFiles(files);
-```
-
-:::note[GitHub Example]
-[Example of Applet that save files and load them in one file](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-resources)
-:::
-
-## addFilesSync()
-Method `addFilesSync()` works same as method above, but all files are loaded in correct order. Otherwise, files are loaded in random order by file size.
-
-### Javascript example
-```javascript
-const files = [
-	{
-		"uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
-		"uid": "jquery-2.2.4.min.js",
-		"type": sos.offline.types.javascript,
-		"flags": [sos.offline.flags.append(document.body)]
-	},
-	{
-		"uri": "https://signageostest.blob.core.windows.net/test/applet-examples/benchmark-styles.css?v=1.0.0",
-		"uid": "benchmark-styles.css-v1.0.0",
-		"type": sos.offline.types.css,
-		"headers": { "Authorization": "Basic Zm9vOmJhcg==" },
-		"flags": [sos.offline.flags.append(document.head)]
-	}
-];
-
-sos.offline.addFilesSync(files).then(() => {
-	console.log('Now you can use jQuery and CSS file');
-	jQuery('#do').something();
-});
-```
-
-## Usage with Typescript
-You can also use all these methods with [signageOS TypeScript](https://docs.signageos.io/hc/en-us/articles/4405069154962#signageos-typescript).
-
-```typescript
-interface ISaveFile {
-	uid: string;
-	uri: string;
-	type: string;
-	headers?: { [key: string]: string };
-	flags?: IFlag[];
-}
-
-addFile(files: ISaveFile[]): Promise<void>;
-addFiles(files: ISaveFile[]): Promise<void>;
-addFilesSync(files: ISaveFile[]): Promise<void>;
-```
-
-Flags that can be optionally passed to the file object are available in flags property.
-
-```typescript
-interface IFlag {
-	type: 'append';
-	element: IElement;
-}
-```
-
-## Errors
-Although we are doing our best, following errors may occur when working with the Applet Resources.
-
-
-| Code | Type | Message |
-| ---- | ---- | ------- |
-| 40101 | AppletResourcesError | File needs to be object |
-| 40102 | AppletResourcesError | File UID needs to be defined |
-| 40103 | AppletResourcesError | File flags needs to be Array |
-| 40104 | AppletResourcesError | File flag needs to be object |
-| 40105 | AppletResourcesError | Already loading file: `FILE_NAME` |
-|^^|^^| Your code has probably multiple occurrences of addFile/s methods. |
-| 40106 | AppletResourcesError | Already existing file: `FILE_NAME` |
-|^^|^^| File is already loaded or exists in Applet |
-| 49901 | FileNotFoundError    | File `FILE_ID` was not found |
-|^^|^^| Applet can not get file. URL is invalid. 

package/docs/content/js-browser.md

@@ -1,163 +0,0 @@
----
-title:  Browser
-author: Miroslav Behina
-date:   22.11.2018
-type:   js-api
-tags:
-- applet
-- applet_api
-- api
-- js_api
-description: "[Content JS API] 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."
----
-
-# 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.
-
-## All methods
-
-| Methods  | Description | Supported since |
-| ----------------- | ----------- | :---------------: |
-| `open()`        | Open page in integrated browser |      4.0.0    |
-| `close()`        | Open page in integrated browser |      4.4.0
-
-## open()
-
-:::info
-**This API is currently available on:**
-- Android devices with Android 5+ (Philips, Benq, Sharp, generic Android device)
-
-**With some limitation you can use this API also 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)
-:::
-
-### Javascript
-Simple opening some page ex. our main company page.
-```javascript
-sos.browser.open('https://www.signageos.io'); // Open link in the browser
-```
-<br/>
-
-Method `open()` also supports properties for browser, all of which are optional.
-
-| Property             | Type    | Description                                                                                                                                                                                                 |
-|----------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `aclDomains`         | Array   | List of domains to be interpreted according to `aclMode`. Example: `signageos.io`, `www.example.com`                                                                                                         |
-| `aclMode`            | String  | <ul><li>`blacklist` – Allow access to all domains _except_ those in `aclDomains` and their subdomains.</li><li>`whitelist` – Allow access _only_ to domains in `aclDomains` and their subdomains.</li></ul> 
-| `readOnlyAddressBar` | Boolean | <ul><li>`true` – The address bar is read-only.</li><li>`false` – The user can navigate away by entering a URL in the address bar.</li></ul>                                                                 |
-| `coordinates`        | Object  | Size and position of the browser window. Defaults to fullscreen. (Android, Linux)                                                                                                                           
-| `idleTimeout`        | Number  | The browser will automatically close after a specified period of inactivity (in milliseconds).                                                                                                              |
-| `theme`              | Object  | Specify custom UI theme. (Android)                                                                                                                                                                          |
-| `headlessMode`       | Boolean | Headless mode hides the entire address bar (default)                                                                                                                                                        |
-| `canUserClose`       | Boolean | Whether the user can manually close the browser. Default:<br/>**Headless:** `false`<br/>**With UI:** `true`                                                                                                 |
-| `clearData`          | Boolean | Clear cache after the browser closes. Default:<br/>**Headless:** `false`<br/>**With UI:** `true`                                                                                                            |
-| `method`             | String  | Can only be **native** (which opens a new, fully sandboxed fullscreen window) or **iframe** (which opens a configurable-sized window). (only Linux)                                                         |
-
-```javascript
-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
-});
-```
-
-:::note[GitHub Example]
-[Example of Applet for using browser on Android](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/browser)
-:::
-
-### Browser themes usage with Typescript
-You can also use all these methods with [signageOS TypeScript](https://docs.signageos.io/hc/en-us/articles/4405069154962#signageos-typescript).
-
-:::info
-Browser themes are only available on Android devices.
-:::
-
-```typescript
-type Color = string;
-
-export type ITheme = {
-	base?: 'light' | 'dark'; // Default light
-	shape?: {
-		cornerSize?: number; // Default 2
-	};
-	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';
-		};
-	};
-};
-
-interface IOpenLinkOptions {
-	aclDomains?: string[];
-	aclMode?: 'blacklist' | 'whitelist';
-	readOnlyAddressBar?: boolean;
-	coordinates?: {
-		x: number;
-		y: number;
-		width: number;
-		height: number;
-	};
-	theme?: ITheme;
-	headlessMode?: boolean;
-	clearData?: boolean;
-	canUserClose?: boolean;
-	method?: 'native' | 'iframe'
-}
-
-open(uri: string, options?: IOpenLinkOptions): void;
-```
-
-## close()
-
-Closing the Browser instance. The whole page is closed. If you call `open()` again, the page will be loaded from the beginning.
-
-### Javascript
-Simple opening some page ex. our main company page.
-```javascript
-sos.browser.close(); // Close the browser
-```
-<br/>
-
-## Errors
-Although we are doing our best, following errors may occur when opening a link.
-
-
-| Code | Type | Message |
-| ---- | ---- | ------- |
-| 40301 | AppletBrowserUriError | Property argument `uri` must be a string |
-| 50301 | InternalBrowserOpenLinkError | Unexpected error occurred when opening `$$LINK$$`
-