@signageos/front-applet 5.0.0-beta.7 → 5.0.0

package/docs/js-api/js-api-introduction.md

@@ -16,17 +16,12 @@ You can use the same functions across all devices with the same result. Applet J
 
 Applet JS API supports content-playback features and device management features.
 
-### About signageOS APIs
-
-In signageOS there are 2 main groups of APIs:
-- `Client-side` - JS API available for both **signageOS Open** and signageOS Platform plans
-- `Server-side` - REST API available in **signageOS Platform plan only**
-
 ::: alert alert--tip
 All APIs are standardized and available across all [supported devices](/category/supported-devices-guides).
 :::
 
-## Content-playback APIs
+## Content-playback JS APIs
+
 Content-playback API is an API for managing content on screen. 
 
 ::: table-responsive
@@ -34,25 +29,30 @@ Content-playback API is an API for managing content on screen.
 | ------ | ----------- |
 | **[Basic information](/api/js/content/js-applet-basics)** | General information required to use the signageOS JS API |
 | [Applet Resources](/api/js/content/js-applet-resources) | Pre-load necessary files required by your HTML5 player/Applet |
+| [Display](/api/js/content/js-display) | Query features supported by the display |
 | [Browser](/api/js/content/js-browser) | Opening managed web-browser on Android devices inc. whitelisting, blacklisting and other features |
 | [Command](/api/js/content/js-command) | Sending business or technical logs through signageOS in secured offline-ready way |
 | [File system](/api/js/content/js-file-system) | Full-featured file system API including ZIP and folder management |
+| [Fonts](/api/js/content/js-loading-fonts) | Make it easy to load additional fonts into SoC devices |
 | [Hardware](/api/js/content/js-hardware) | Hardware-specific APIs like LED lights on Philips 10BDL |
-| [Serial](/api/js/content/js-hardware-serial) | Control external devices via serial |
 | [Inputs](/api/js/content/js-input) | Controller inputs like IR remote unified under one API |
-| [Fonts](/api/js/content/js-loading-fonts) | Make it easy to load additional fonts into SoC devices |
+| [Monitors](/api/js/content/js-monitors) | Information about monitors |
+| [Sensors](/api/js/content/js-sensors) | Using sensors and IoT devices in your application  |
+| [Serial](/api/js/content/js-hardware-serial) | Control external devices via serial |
 | [Synchronized playback](/api/js/content/js-sync-playback) | API for creating synced playback and videowalls  |
-| [Timings](/api/js/content/js-timing) | Managing Timing/Applet switching from JS  |
 | [Video Inputs aka PiP](/api/js/content/js-video-inputs-internal-ports) | Show HDMI/DP/VGA as a part of your content via PiP feature |
 | [Video Playback](/api/js/content/js-video) | Playing accelerated gapless videos via native video player |
 | [Video Streams](/api/js/content/js-video-stream) | Playing video streams (RTSP, HLS, UDP) via native video player  |
-| [Sensors](/api/js/content/js-sensors) | Using sensors and IoT devices in your application  |
-| [Monitors](/api/js/content/js-monitors) | Information about monitors |
 :::
 
 ## Device management APIs
+
 Device management API is for managing, updating firmware, and other settings on the device.
 
+::: alert alert--tip
+For **Device Management** we strongly recommend using REST APIs. [See the REST API documentation here](https://api.docs.signageos.io).
+:::
+
 ::: table-responsive
 | Domain | Description |
 | ------ | ----------- |
@@ -63,6 +63,10 @@ Device management API is for managing, updating firmware, and other settings on
 | [Screen](/api/js/management/5-js-management-screen) | Manage brightness, orientation and resolution, display on/off |
 | [Time](/api/js/management/6-js-management-time) | Set time, timezone and get current settings |
 | [Volume](/api/js/management/7-js-management-volume) | Control system volume level |
+| [Package](/api/js/management/8-js-management-package) | Install and manage packages |
+| [Debug](/api/js/management/9-js-management-debug) | Enable/disable debug mode |
+| [Application](/api/js/management/10-js-management-application) | Get application version and upgrade application from remote location |
+| [Network](/api/js/management/11-js-management-network) | Manage network settings |
 | [Security](/api/js/management/12-js-management-security) | Control system security (PIN code) |
 | [Wi-Fi](/api/js/management/13-js-management-wifi) | Manage Wi-Fi |
 :::

package/docs/js-api/js-applet-basics.md

@@ -16,12 +16,16 @@ description: "[Content JS API] This thread contains basic methods of every Apple
 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
+
 ::: table-responsive
 | 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 |
 | `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`|
+| `capabilities`  | Enum of device-specific capabilities and features | `1.0.0`|
 :::
 
 ## Starting Applet
@@ -29,13 +33,33 @@ This thread contains basic methods of every Applet used to load necessary config
 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
+``` 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.
@@ -58,6 +82,17 @@ 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
@@ -88,6 +123,18 @@ It stops all video playback and clears out the memory. The following function sh
 
 ### 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);
@@ -117,7 +164,18 @@ window.addEventListener('sos.loaded', () => {
 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));
 });
@@ -132,6 +190,109 @@ You can pass CUSTOM key-value variables to the Applet. To do that, add your valu
 console.log(sos.config.mySecretID);
 console.log(sos.config.imgUrl);
 ```
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="/knowledge-base/applet-custom-config-on-device">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fas fa-hand-point-right svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Custom variables in Applet</h3>
+                <div class="wide-box__description">How to pass custom variables and cofiguration to your Applet</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
 
 ## 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.
+
+::: table-responsive
+| Capability                     | Description                                                                               |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| `FILE_SYSTEM_EXTERNAL_STORAGE` | Device file system supports [external storage](/api/js/content/js-file-system) (i.e. flash drives)                          |
+| `FILE_SYSTEM_FILE_CHECKSUM`    | Device is can [calculate a file checksum](/api/js/content/js-file-system#getfilechecksum) |
+| `VIDEO_4K`                     | Device is capable of [playing 4K video](/api/js/content/js-video)                                                     |
+| `SERIAL`                       | Device supports communication with peripherals over [serial](/api/js/content/js-hardware-serial)                                |
+:::
+
+#### Javascript example:
+
+```javascript
+if (await sos.display.supports('VIDEO_4K')) {
+	// play 4K video
+}
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/capabilities-content">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Content Capabilities</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+
+### Management capabilities
+
+Management capabilities refer to the capabilities of the display's internal state management.
+
+::: table-responsive
+| Capability                     | Description                                                                               |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| `BATTERY_STATUS` | Device can [report its battery status](/api/js/management/1-js-management#getbatterystatus). |
+| `WIFI` | Device can [connect to a Wi-Fi](/api/js/management/13-js-management-wifi#connect). |
+| `WIFI_SCAN` | Device can [scan surrounding Wi-Fi devices](/api/js/management/13-js-management-wifi#scandevices). |
+| `WIFI_AP` | Device is capable of [becoming a Wi-Fi endpoint](/api/js/management/13-js-management-wifi#enableap) that other devices can connect to. |
+| `SET_BRIGHTNESS` | Device can change its [screen brightness](/api/js/management/5-js-management-screen#setbrightness). |
+| `SET_TIME` | Device can change its [time settings](/api/js/management/6-js-management-time). |
+| `NTP_TIME` | Device can [synchronize its time with an NTP server](/api/js/management/6-js-management-time#setntp). |
+| `PACKAGE_INSTALL` | It's possible to [install additional packages](/api/js/management/8-js-management-package) on the device, managed by signageOS application. |
+| `SET_VOLUME` | Device can change its [audio volume](/api/js/management/7-js-management-volume). |
+| `SET_REMOTE_CONTROL_ENABLED` | Device can [disable control via IR remote](/api/js/management/3-js-management-remote-control) to increase security. |
+:::
+
+```javascript
+if (await sos.management.supports('WIFI')) {
+	// connect to wifi
+}
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/capabilities-management">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Management Capabilities</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>

package/docs/js-api/js-browser.md

@@ -21,14 +21,20 @@ Default URL can be opened and even the whitelisting/blacklisting of certain doma
 ::: table-responsive
 | Methods  | Description | Supported since |
 | ----------------- | ----------- | -----  | :---------------: |
-| `openLink()`        |   **Deprecated:** Use `open()` instead.          |    1.0.19       |
 | `open()`        | Open page in integrated browser |      4.0.0    |
+| `close()`        | Open page in integrated browser |      4.4.0    |
 :::
 
 ## open()
 
 ::: alert alert--info
-Only works for Android devices with Android 5+
+**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)
+- Raspberry Pi and NEC Compute Module; where the website is just in fullscreen without an address bar or theme options (headless mode)
 :::
 
 ### Javascript
@@ -49,6 +55,9 @@ Method `open()` also supports properties for browser. You can set height, width
 | `coordinates` | Object | Size of browser screen (only Raspberry Pi) |
 | `idleTimeout` | Number | Timeout in milliseconds for loading page |
 | `theme` | Object | Setting custom theme for 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` |
 :::
 
 
@@ -57,13 +66,14 @@ sos.browser.open('https://www.signageos.io', {
   aclDomains: ['google.com', 'yahoo.com'],
   aclMode: 'blacklist', // or 'whitelist'
   readOnlyAddressBar: true,
-  coordinates: { // Supported only on Raspberry Pi
+  coordinates: { // Supported only on Raspberry Pi and Android
     x: 0,
     y: 0,
     height: 500,
     width: 500,
   },
   // theme: { ... } // supported only on Android
+  headlessMode: false, // supported only on Android
 ```
 
 <div class="row d-flex align-content-stretch force-padding-20">
@@ -82,9 +92,13 @@ sos.browser.open('https://www.signageos.io', {
     </div>
 </div>
 
-## Usage with Typescript
+### Browser themes usage with Typescript
 You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
 
+::: alert alert--info
+Browser themes are only available on Android devices.
+:::
+
 ```typescript
 type Color = string;
 
@@ -130,19 +144,33 @@ interface IOpenLinkOptions {
 		width: number;
 		height: number;
 	};
-	theme?: ITheme; // supported since 5.0.0
+	theme?: ITheme;
+	headlessMode?: boolean;
+	clearData?: boolean;
+	canUserClose?: boolean;
 }
 
 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.
 
 ::: table-responsive
 | Code | Type | Message |
 | ---- | ---- | ------- |
-| 40301 | AppletBrowserUriError | Property argument uri must be a string |
-| 50301 | InternalBrowserOpenLinkError | Unexpected error occurred when opening $$LINK$$ |
+| 40301 | AppletBrowserUriError | Property argument `uri` must be a string |
+| 50301 | InternalBrowserOpenLinkError | Unexpected error occurred when opening `$$LINK$$` |
 :::
 

package/docs/js-api/js-command.md

@@ -13,35 +13,61 @@ description: "[Content JS API] In some cases, you might be interested in a compl
 
 # Command
 
-## Command dispatching
 In some cases, you might be interested in a complete log of what the device was doing during its operation. All of your business or technical logs can be stored in our storage for later usage. You can identify which events happened or even trigger self-repairing logic.
 
-All commands will be available in Device Monitoring REST API or:
-* In Box as a debugging stream
-* For pre-defined monitoring metric
-* It can be just downloaded historically as CSV export
+All commands will be available in [Applet Command REST API](https://api.docs.signageos.io/#8e7a8814-e612-1fad-0152-72f37591c7f2) and can be downloaded [historically as CSV export](https://api.docs.signageos.io/#5dceec58-ac4f-7a0c-f5ef-0854f9376e6d).
 
+## All methods
 ::: table-responsive
 | Methods  | Description | Supported since |
-| ----------------- | ----------- | -----  | :---------------: |
-| `dispatch()`  | Dispatch method for logging |    1.0.3       |
+| ----------------- | ----------- | -----  |
+| `dispatch()`  | Dispatch method for sending logs and data from device | 1.0.3 |
+| `onCommand()`  | Event listener for incoming commands from server | 1.0.3 |
+
+:::
+
+## dispatch()
+
+Dispatch() is used for sending your custom logs or data from device to signageOS.
 
 ### Parameters
 ::: table-responsive
 |   Parameter    | Type | Required |  Description  |
 | -------------- | -------------| :----------------: | ------------- |
-| `type`     | String  | <div class="red">Yes</div> | Event type |
-| `fileName` | String  | <div class="red">Yes</div> | Name of the file  |
-| `fileType` | String  | <div class="red">Yes</div> | Type of file |
+| `type`     | String  | <div class="red">Yes</div> | Event type; can be any string **up to 100 characters**|
+| custom `parameter` | String  | No | Custom parameters and values that you need to be dispatched  |
 :::
 
 ### Javascript example
 ```javascript
+
+/*
+Example of dispatching information about file download
+*/
+await sos.command.dispatch({
+  type: 'Files.StartLoading', // mandatory *type* with custom value
+  fileName: 'my-file', // custom parameter and value
+  fileType: 'txt' // custom parameter and value
+});
+
+/*
+Example of dispatching applet heartbeat
+*/
 await sos.command.dispatch({
-  type: 'Files.StartLoading',
-  fileName: 'my-file',
-  fileType: 'txt'
+  type: 'Heartbeat' // mandatory *type* with custom value
 });
+
+/*
+Example of dispatching applet new data
+*/
+const myCMSJSON = {playlist: "myPlaylist", items: [...]};
+
+await sos.command.dispatch({
+  type: 'Content.update', // mandatory *type* with custom value
+  content: JSON.stringify(myCMSJSON) // custom parameter and value
+});
+
+
 ```
 
 <div class="row d-flex align-content-stretch force-padding-20">
@@ -80,27 +106,41 @@ dispatch(command: ICommand): void;
 
 <div class="row d-flex align-content-stretch force-padding-20">
     <div class="col-12 d-flex">
-        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" href="/api/rest/device-monitoring/3-device-appletcommand-get-many">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" href="https://api.docs.signageos.io/#8e7a8814-e612-1fad-0152-72f37591c7f2">
             <div>
                 <div class="wide-box__image d-flex align-items-center">
                     <i class="fas fa-server svg-black"></i>
                 </div>
             <div>
-                <h3 class="wide-box__title wide-box__title__small pl-85">Rest API: Monitoring</h3>
-                <div class="wide-box__description">Receiving monitoring data</div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Rest API: Get Commands</h3>
+                <div class="wide-box__description">Receiving your data dispatched from devices</div>
             </div>
             </div>
         </a>
     </div>
 </div>
 
-## Command receiving
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" href="https://api.docs.signageos.io/#5dceec58-ac4f-7a0c-f5ef-0854f9376e6d">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fas fa-server svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Rest API: Monitoring/Device Reports</h3>
+                <div class="wide-box__description">Receiving historical data</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## onCommand()
 Used for sending custom messages to online connected devices. 
-This can be done through the REST API by [POST new applet command](https://docs.signageos.io/api/device-monitoring-api/#Send_Device_Applet_Command_to_device). 
+This can be done through the REST API by [POST new applet command](https://api.docs.signageos.io/#511e18f3-b61b-a049-6395-8541132adc44). 
 The command will be dispatched to the device & the applet can set up the logic by subscribing `onCommand` method.
 
-Dispatched commands will are available in Device Monitoring REST API.
-
 **Parameters:**
 ::: table-responsive
 |      Param     | Type   | Required | Description  |
@@ -142,7 +182,7 @@ onCommand(listener: (command: ICommand) => void): void;
 
 <div class="row d-flex align-content-stretch force-padding-20">
     <div class="col-12 d-flex">
-        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" href="/api/rest/device-monitoring/4-device-appletcommand-post-one">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" href="https://api.docs.signageos.io/#511e18f3-b61b-a049-6395-8541132adc44">
             <div>
                 <div class="wide-box__image d-flex align-items-center">
                     <i class="fas fa-server svg-black"></i>

package/docs/js-api/js-display.md

@@ -0,0 +1,48 @@
+---
+title:  Display
+author: Michal Artazov
+date:   12.4.2021
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- display
+- js_api
+description: "[Content JS API] Display API allows you to query the display to find out, which features it supports."
+---
+
+# Display
+
+Display API allows you to query the display to find out, which features it supports.
+That way your applet can handle cases, when a certain feature isn't supported by a particular display.
+
+## All methods
+
+::: table-responsive
+| Method             | Description            | Supported since |
+| ------------------ | ---------------------- | :-------------: |
+| `supports()` | Query, whether a certain feature is supported by the display | 3.1.0 |
+:::
+
+## supports()
+
+Query the display to find out, whether a certain feature is supported.
+To let you know, when you should call this method, we will warn you throughout the content JS API documentation
+with a warning message like this one:
+
+::: alert alert--warning
+* Before using this API, ensure that the display supports serial via `sos.display.supports("SERIAL")`.
+* More info [**HERE**](/api/js/content/js-display#supports).
+:::
+
+::: table-responsive
+| Param        | Type   | Required                   | Description     |
+| ------------ | ------ | :------------------------: | --------------- |
+| `capability` | string | <div class="red">Yes</div> | Capability name |
+:::
+
+### Javascript example
+```javascript
+const serialPort = await sos.display.supports("SERIAL");
+```