@signageos/front-applet 7.1.1 → 8.0.0

package/docs/sos_management/power.md

@@ -0,0 +1,136 @@
+# power
+
+The `sos.management.power` API groups together methods related to the power state of the device. Such as rebooting, shutting down,
+setting timers.
+
+## Methods
+
+### appRestart()
+
+The `appRestart()` method initializes a restart of the signageOS app.
+
+```ts expandable
+appRestart(): Promise<void>;
+```
+
+<Separator />
+
+### getProprietaryTimers()
+
+The `getProprietaryTimers()` method returns a list of currently set
+[proprietary timers](https://docs.signageos.io/hc/en-us/articles/4416384202642-Timers#h_01HCD14GEDP96AZV58NRSN2HNQ).
+
+```ts expandable
+getProprietaryTimers(): Promise<IProprietaryTimer[]>;
+// show-more
+interface IProprietaryTimer {
+    type: ProprietaryTimerType;
+    timeOn: string | null;
+    timeOff: string | null;
+    weekdays: string[];
+}
+
+```
+
+<Separator />
+
+### getTimers()
+
+The `getTimers()` method returns a list of currently set native timers.
+
+```ts expandable
+getTimers(): Promise<ITimer[]>;
+// show-more
+interface ITimer {
+    type: keyof typeof TimerType;
+    timeOn: string | null;
+    timeOff: string | null;
+    weekdays: string[];
+    volume: number;
+}
+
+```
+
+<Separator />
+
+### setProprietaryTimer()
+
+The `setProprietaryTimer()` method creates or updates a
+[proprietary timer](https://docs.signageos.io/hc/en-us/articles/4416384202642-Timers#h_01HCD14GEDP96AZV58NRSN2HNQ).
+
+```ts expandable
+setProprietaryTimer(type: ProprietaryTimerType, timeOn: string | null, timeOff: string | null, weekdays: string[], keepAppletRunning?: boolean): Promise<void>;
+```
+
+#### Params
+
+| Name                             | Type                | Description                                                                             |
+|----------------------------------|---------------------|-----------------------------------------------------------------------------------------|
+| `type`                           | ``TIMER_${number}`` | The type of the timer (`TIMER_1`, ..., `TIMER_7`).                                      |
+| `timeOn`                         | `string \| null`    | The time when the device should turn on.                                                |
+| `timeOff`                        | `string \| null`    | The time when the device should turn off.                                               |
+| `weekdays`                       | `string[]`          | The days of the week when the timer should be active (`mon`, ..., `sun`).               |
+| `keepAppletRunning` *(optional)* | `boolean`           | If `true`, the applet will be kept running when the timer is active on certain devices. |
+
+<Separator />
+
+### setTimer()
+
+The `setTimers()` method creates or updates a native timer.
+
+```ts expandable
+setTimer(type: keyof typeof TimerType, timeOn: string | null, timeOff: string | null, weekdays: string[], volume: number): Promise<void>;
+```
+
+#### Params
+
+| Name       | Type                                                                                      | Description                                                               |
+|------------|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| `type`     | `"TIMER_1" \| "TIMER_2" \| "TIMER_3" \| "TIMER_4" \| "TIMER_5" \| "TIMER_6" \| "TIMER_7"` | The type of the timer (`TIMER_1`, ..., `TIMER_7`).                        |
+| `timeOn`   | `string \| null`                                                                          | The time when the device should turn on.                                  |
+| `timeOff`  | `string \| null`                                                                          | The time when the device should turn off.                                 |
+| `weekdays` | `string[]`                                                                                | The days of the week when the timer should be active (`mon`, ..., `sun`). |
+| `volume`   | `number`                                                                                  | The volume level set when the device is turned on.                        |
+
+<Separator />
+
+### systemReboot()
+
+The `systemReboot()` method initializes a system reboot.
+
+```ts expandable
+systemReboot(): Promise<void>;
+```
+
+<Separator />
+
+### unsetProprietaryTimer()
+
+The `unsetProprietaryTimer()` method removes the specified
+[proprietary timer](https://docs.signageos.io/hc/en-us/articles/4416384202642-Timers#h_01HCD14GEDP96AZV58NRSN2HNQ).
+
+```ts expandable
+unsetProprietaryTimer(type: ProprietaryTimerType): Promise<void>;
+```
+
+#### Params
+
+| Name   | Type                | Description                                        |
+|--------|---------------------|----------------------------------------------------|
+| `type` | ``TIMER_${number}`` | The type of the timer (`TIMER_1`, ..., `TIMER_7`). |
+
+<Separator />
+
+### unsetTimer()
+
+The `unsetTimer()` method removes the specified native timer.
+
+```ts expandable
+unsetTimer(type: keyof typeof TimerType): Promise<void>;
+```
+
+#### Params
+
+| Name   | Type                                                                                      | Description                                        |
+|--------|-------------------------------------------------------------------------------------------|----------------------------------------------------|
+| `type` | `"TIMER_1" \| "TIMER_2" \| "TIMER_3" \| "TIMER_4" \| "TIMER_5" \| "TIMER_6" \| "TIMER_7"` | The type of the timer (`TIMER_1`, ..., `TIMER_7`). |

package/docs/sos_management/proxy.md

@@ -0,0 +1,41 @@
+# proxy
+
+## Methods
+
+### disable()
+
+The `disable()` method disables the proxy on the device.
+
+```ts expandable
+disable(): Promise<void>;
+```
+
+<Separator />
+
+### getConnectedTo()
+
+The `getConnectedTo()` methods returns the current connected proxy server uri on the device.
+
+```ts expandable
+getConnectedTo(): Promise<string>;
+```
+
+<Separator />
+
+### isEnabled()
+
+The `isEnabled()` method returns whether the proxy is enabled on the device.
+
+```ts expandable
+isEnabled(): Promise<boolean>;
+```
+
+<Separator />
+
+### setManual()
+
+The `setManual()` method sets the proxy on the device.
+
+```ts expandable
+setManual(uri: string, port: number, username?: string, password?: string): Promise<void>;
+```

package/docs/sos_management/remoteControl.md

@@ -0,0 +1,72 @@
+# remoteControl
+
+The `sos.management.remoteControl` groups together methods for enabling or disabling control of the device using IR remote controller (TV controller).
+
+## Methods
+
+### disable()
+
+The `disable()` method disables remote control.
+
+```ts expandable
+disable(): Promise<void>;
+```
+
+<Separator />
+
+### enable()
+
+The `enable()` method enables remote control.
+
+:::warning
+
+**Android:** In order to prevent Android from displaying Android homepage and thus not showing your content, you
+must Enable Kiosk Mode (or Lock Remote Control) either through Box device settings or through API.
+
+Always set the Remote Control Lock to `enable` after the deployment.
+
+:::
+
+```ts expandable
+enable(): Promise<void>;
+```
+
+<Separator />
+
+### isEnabled()
+
+The `isEnabled()` method returns whether the remote control is enabled.
+
+```ts expandable
+isEnabled(): Promise<boolean>;
+```
+
+<Separator />
+
+### isLocked()
+
+The `isLocked()` method returns whether the remote control is locked (disabled).
+
+```ts expandable
+isLocked(): Promise<boolean>;
+```
+
+<Separator />
+
+### lock()
+
+The `lock()` method is an alias for the `disable()` method.
+
+```ts expandable
+lock(): Promise<void>;
+```
+
+<Separator />
+
+### unlock()
+
+The `unlock()` method is an alias for the `enable()` method.
+
+```ts expandable
+unlock(): Promise<void>;
+```

package/docs/sos_management/screen.md

@@ -0,0 +1,198 @@
+# screen
+
+The `sos.management.screen` API groups together methods for controlling the screen of the device. It allows to manipulate the screen
+resolution or orientation, set brightness, retrieve the current brightness of the display and manipulate the power mode.
+
+:::warning
+
+This method only turns on/off the display/backlight. It will **not** set any power-saving mode. We also strongly recommend to reboot any
+device once a day.
+
+:::
+
+:::info
+
+There is a specific behavior based on the device type you operate:
+**On SoC displays** (e.g. Samsung Tizen, LG webOS, Android-based SoC displays from Sony, Vestel Philips,...)
+- `powerOn()` and `powerOff()` are turning the display backlight and the panel off
+
+**On external media players** (e.g. BrightSign, Windows PC, Android players, Raspberry Pi)
+- `powerOn()` and `powerOff()` are turning off the video output (typically HDMI-out); the connected display backlight is not managed by this functionality and needs to be controlled via RS232 or another way.
+
+:::
+
+## Methods
+
+### getBrightness()
+
+The `getBrightness()` method returns information about the currently set brightness values.
+
+```ts expandable
+getBrightness(): Promise<IBrightness>;
+// show-more
+interface IBrightness {
+    timeFrom1: string;
+    brightness1: number;
+    timeFrom2: string;
+    brightness2: number;
+}
+
+```
+
+<Separator />
+
+### getOrientation()
+
+The `getOrientation()` method returns the current orientation of the screen.
+
+```ts expandable
+getOrientation(): Promise<IOrientation>;
+// show-more
+interface IOrientation {
+    screenOrientation: Orientation;
+}
+
+type Orientation = 'LANDSCAPE' | 'PORTRAIT' | 'LANDSCAPE_FLIPPED' | 'PORTRAIT_FLIPPED' | 'AUTO';
+
+```
+
+<Separator />
+
+### isPoweredOn()
+
+The `isPoweredOn()` method returns whether the screen is on.
+
+```ts expandable
+isPoweredOn(): Promise<boolean>;
+```
+
+<Separator />
+
+### powerOff()
+
+The `powerOff()` method turn the screen off.
+
+:::warning
+
+On Android devices, `powerOff()` also shuts down the webview and the Applet. It's default Android behavior that cannot be changed. Once
+the Applet is off, you cannot call `powerOn()` to resume the playback.
+
+To manage the display On/Off state, use [REST API Power Actions](https://developers.signageos.io/api/#tag/DevicePower-Actions) instead.
+
+:::
+
+```ts expandable
+powerOff(): Promise<void>;
+```
+
+<Separator />
+
+### powerOn()
+
+The `powerOn()` method turns the screen on.
+
+```ts expandable
+powerOn(): Promise<void>;
+```
+
+<Separator />
+
+### resize()
+
+The `resize()` method changes resolution and orientation of the display.
+
+:::info
+
+For Tizen, you have to provide `baseUrl` which points to the Core App for Tizen which will be downloaded to the device [Read more how to upload your Core Apps here.](https://docs.signageos.io/hc/en-us/articles/4405245195666).
+
+:::
+
+```ts expandable
+resize(baseUrl: string, orientation: string, resolution: string, currentVersion: string, videoOrientation?: string): Promise<void>;
+```
+
+#### Params
+
+| Name                            | Type     | Description                                                                                                                          |
+|---------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `baseUrl`                       | `string` | SSSP & Tizen devices requires to install a orientation-specific Core App if you want to switch orientation to portrait or landscape. |
+| `orientation`                   | `string` | Screen orientation                                                                                                                   |
+| `resolution`                    | `string` | Where it applies (mainly SSSP 2/3)                                                                                                   |
+| `currentVersion`                | `string` | Core App version                                                                                                                     |
+| `videoOrientation` *(optional)* | `string` | If the video has different orientation than the HTML5 content                                                                        |
+
+#### Example
+
+```ts
+// for Tizen
+await sos.management.screen.resize(
+    "https://cdn.your-cms.com/tizen/1.0.4",
+    "PORTRAIT",
+    "FULL_READY",
+    "1.0.4"
+);
+
+// for all other supported device
+await sos.management.screen.resize(
+    "",
+    "PORTRAIT",
+    "HD_READY",
+    ""
+);
+```
+
+:::note[GitHub Example]
+
+- [How to resize screen on device](https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/resize/)
+
+:::
+
+<Separator />
+
+### setBrightness()
+
+The `setBrightness()` method sets the brightness of the screen. It supports 2 different brightness values for 2 time points in the day.
+
+```ts expandable
+setBrightness(timeFrom1: string, brightness1: number, timeFrom2: string, brightness2: number): Promise<void>;
+```
+
+#### Params
+
+| Name          | Type     | Description                        |
+|---------------|----------|------------------------------------|
+| `timeFrom1`   | `string` | Time in the XX:XX format           |
+| `brightness1` | `number` | Brightness value between 0 and 100 |
+| `timeFrom2`   | `string` | Time in the XX:XX format           |
+| `brightness2` | `number` | Brightness value between 0 and 100 |
+
+#### Example
+
+```ts
+await sos.management.screen.setBrightness(
+    '00:00',
+    '10',
+    '17:00',
+    '30'
+);
+```
+
+<Separator />
+
+### takeAndUploadScreenshot()
+
+The `takeAndUploadScreenshot()` method takes a screenshot and uploads it to a specified url. This can be either a signageOS upload url
+(`https://upload.signageos.io`) or a dedicated server url for uploading screenshots. Format in which the screenshot is uploaded may be
+different for every platform.
+
+To implement a custom screenshot upload server, it needs to implement these endpoints:
+- POST `/upload/file?prefix=screenshot/` - Endpoint for receiving screenshot using form data, with the image set to the `file` field.
+- POST `/upload/raw?prefix=screenshot/` - Endpoint for receiving screenshots as a raw data.
+- POST `/upload/image-data-uri?prefix=screenshot/` - Endpoint for receiving screenshots encoded as a data url.
+
+signageOS provides standalone server which is implements all of those methods. It is provided to all of our partners through the
+[support ticketing system](https://box.signageos.io/support/).
+
+```ts expandable
+takeAndUploadScreenshot(uploadBaseUrl: string): Promise<string>;
+```

package/docs/sos_management/security.md

@@ -0,0 +1,47 @@
+# security
+
+The `sos.management.security` API groups together methods for management of a security PIN code of the device.
+
+## Methods
+
+### generateRandomPinCode()
+
+The `getPinCode()` method sets the PIN code to a randomly generated one.
+
+```ts expandable
+generateRandomPinCode(): Promise<void>;
+```
+
+<Separator />
+
+### getPinCode()
+
+The `getPinCode()` method returns the currently set PIN code.
+
+```ts expandable
+getPinCode(): Promise<string>;
+```
+
+#### Possible errors
+
+The method throws an error **41703**: Get PIN code failed because the PIN code has not been set yet.
+
+<Separator />
+
+### setPinCode()
+
+The `setPinCode()` method sets the pin code.
+
+```ts expandable
+setPinCode(pinCode: string): Promise<void>;
+```
+
+#### Params
+
+| Name      | Type     | Description             |
+|-----------|----------|-------------------------|
+| `pinCode` | `string` | The PIN code to be set. |
+
+#### Possible errors
+
+The method throws an error **41701**: Invalid PIN code format (has to be 4-digits string).

package/docs/sos_management/time.md

@@ -0,0 +1,101 @@
+# time
+
+The `sos.management.time` API groups together methods for working with the system time.
+
+## Methods
+
+### get()
+
+The `get()` method returns currently set time info.
+
+```ts expandable
+get(): Promise<IGetTime>;
+// show-more
+interface IGetTime {
+    currentDate: Date;
+    timezone?: string;
+    ntpServer?: string;
+}
+
+```
+
+<Separator />
+
+### setManual(dateTime, timezone)
+
+The `setManual()` method sets the system time and the system timezone.
+
+:::warning
+
+This method will disable NTP server settings.
+
+:::
+
+```ts expandable
+setManual(dateTime: DateTime, timezone: string): Promise<void>;
+// show-more
+/**
+ * All values are raw, none are zero-indexed.
+ */
+interface DateTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+
+```
+
+#### Params
+
+| Name       | Type       | Description               |
+|------------|------------|---------------------------|
+| `dateTime` | `DateTime` | The date and time to set. |
+| `timezone` | `string`   | The timezone to set.      |
+
+<Separator />
+
+### setNTP()
+
+The `setNTP()` method sets the NTP server and the system timezone.
+
+```ts expandable
+setNTP(ntpServer: string, timezone: string): Promise<void>;
+```
+
+#### Params
+
+| Name        | Type     | Description            |
+|-------------|----------|------------------------|
+| `ntpServer` | `string` | The NTP server to set. |
+| `timezone`  | `string` | The timezone to set.   |
+
+<Separator />
+
+### ~set()~
+
+:::danger
+
+This method was deprecated. Use `setManual(dateTime, timezone)` instead.
+
+:::
+
+```ts expandable
+set(currentDate: Date, timezone: string): Promise<void>;
+```
+
+<Separator />
+
+### ~setManual(currentDate, timezone)~
+
+:::danger
+
+This method was deprecated. Use `setManual(dateTime, timezone)` instead.
+
+:::
+
+```ts expandable
+setManual(currentDate: Date, timezone: string): Promise<void>;
+```