@signageos/front-applet 7.2.0 → 8.0.0

package/docs/sos/sync.md

@@ -0,0 +1,298 @@
+# sync
+
+The `sos.sync` API groups together methods for synchronization of multiple devices. Devices are synchronized either through an external
+server or one of the devices becomes a master device.
+
+## Methods
+
+### broadcastValue()
+
+The `broadcastValue()` method sends a key-value pair to all other devices in a specified group.
+
+```ts expandable
+broadcastValue({ groupName, key, value }: {
+    groupName?: string;
+    key: string;
+    value: any;
+}): Promise<void>;
+```
+
+#### Possible errors
+
+The method throws an error if the value can't be sent
+
+<Separator />
+
+### cancelWait()
+
+The `cancelWait()` method aborts a wait on all devices in a group. Sometimes it's necessary to cancel a pending wait. One such
+situation would be when the group has to make a sudden change in content or another behavior but there's a risk that part of the group
+already called wait() and is waiting for the rest but the rest will never call it at this point. In order to gracefully cleanup any
+pending activity, use this method.
+
+Any pending wait will be canceled and the promise will be rejected with an error.
+
+```ts expandable
+cancelWait(groupName?: string): Promise<void>;
+```
+
+#### Example
+
+```ts
+sos.sync.wait('someData', 'someRandomNameGroup').catch((err) => {
+    // this will happend once cancelWait is called
+    console.error('wait failed', err);
+});
+
+// this will cause above wait promise to reject
+await sos.sync.cancelWait('someRandomNameGroup');
+```
+
+<Separator />
+
+### close()
+
+The `close()` method disconnects the device from synchronization server and other devices. Recommended to call this method after the
+synchronization is not required any longer.
+
+```ts expandable
+close(): Promise<void>;
+```
+
+<Separator />
+
+### connect(options)
+
+The `connect()` method initializes the device and connects it to the rest of the devices. This initializes the connection and is
+mandatory to call, since synchronization is an optional feature and doesn’t get initialized by default to save resources and bandwidth.
+You can optionally specify a custom sync server URI in case you are running the sync server in a custom location.
+
+:::info
+
+All devices, that should be synchronized together, must select the same engine. Otherwise they won't be able to communicate with each
+other.
+
+:::
+
+```ts expandable
+connect(options?: ConnectSyncServerOptions | ConnectP2PLocalOptions | ConnectUdpOptions): Promise<void>;
+// show-more
+interface ConnectSyncServerOptions {
+    engine?: SyncEngine.SyncServer;
+    uri?: string;
+}
+
+enum SyncEngine {
+    /** Use external sync server. Device will connect to the server via websocket. */
+    SyncServer = "sync-server",
+    /** Synchronize directly with other devices in the local network via UDP and TCP. */
+    P2PLocal = "p2p-local",
+    /**
+     * Synchronize directly with other devices in the local network via UDP.
+     * @deprecated use {@link P2PLocal}
+     */
+    Udp = "udp"
+}
+
+interface ConnectP2PLocalOptions {
+    engine: SyncEngine.P2PLocal;
+}
+
+/** @deprecated use SyncEngine.P2PLocal and ConnectP2PLocalOptions */
+interface ConnectUdpOptions {
+    engine: SyncEngine.Udp;
+}
+
+```
+
+#### Params
+
+| Name                       | Type             | Description                                                                                                    |
+|----------------------------|------------------|----------------------------------------------------------------------------------------------------------------|
+| `options.engine`           | `SyncEngine.Udp` | Synchronization engine to use.                                                                                 |
+| `options.uri` *(optional)* | `string`         | Address of the sync server engine. Only relevant for sync-server. If omitted, the default server will be used. |
+
+#### Possible errors
+
+The method throws an error if unable to connect.
+
+#### Example
+
+```ts
+// use default engine
+await sos.sync.connect();
+
+// use sync-server engine and default server
+await sos.sync.connect({ engine: 'sync-server' });
+
+// use sync-server engine and custom server
+await sos.sync.connect({ engine: 'sync-server', uri: syncServerUri });
+
+// use p2p-local engine
+await sos.sync.connect({ engine: 'p2p-local' });
+```
+
+<Separator />
+
+### isMaster()
+
+Returns true if the device is currently the master of the group.
+
+```ts expandable
+isMaster(groupName?: string): Promise<boolean>;
+```
+
+#### Params
+
+| Name                     | Type     | Description                                                               |
+|--------------------------|----------|---------------------------------------------------------------------------|
+| `groupName` *(optional)* | `string` | The group name to check for master status. Defaults to the default group. |
+
+<Separator />
+
+### joinGroup()
+
+The `joinGroup()` method joins a group of other devices. This method has to be called after `connect()` call. Before any communication
+takes place, all participating devices have to be connected and recognize one another. Recommended to call this method early.
+
+```ts expandable
+joinGroup(options: {
+    groupName?: string;
+    deviceIdentification?: string;
+}): Promise<void>;
+```
+
+#### Params
+
+| Name                                        | Type     | Description                                                                                                                      |
+|---------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|
+| `options.groupName` *(optional)*            | `string` | By default, all devices will be synced together. To create groups of devices, independent from each other,
+specify a group name. |
+| `options.deviceIdentification` *(optional)* | `string` | Identification of a device connected to `groupName` group.                                                                       |
+
+<Separator />
+
+### leaveGroup()
+
+The `leaveMethod` method leaves a group of devices.
+
+```ts expandable
+leaveGroup(groupName?: string): Promise<void>;
+```
+
+<Separator />
+
+### onClosed()
+
+The `onStatus()` method sets up a listener, which is called whenever the device is disconnected from the sync. If it closed because
+`close()` was called, it will emit without any arguments. if it closed because of an error, it will emit with an error object as the
+first argument.
+
+```ts expandable
+onClosed(listener: (error?: Error) => void): void;
+```
+
+<Separator />
+
+### onStatus()
+
+The `onStatus()` method sets up a listener, which is called periodically or whenever there is a change (i.e. new device
+connects/disconnects to/from the group).
+
+```ts expandable
+onStatus(listener: (status: StatusEvent) => void): void;
+// show-more
+interface StatusEvent {
+    groupName?: string;
+    /** Array of device identifications connected to the group. */
+    connectedPeers: string[];
+    /** True if this device is currently master of the group (this may change over time). */
+    isMaster: boolean;
+}
+
+```
+
+<Separator />
+
+### onValue()
+
+The `onValue()` method sets up a listener, which is called whenever the device receives a broadcasted message.
+
+```ts expandable
+onValue(listener: (key: string, value: any, groupName?: string) => void): void;
+```
+
+<Separator />
+
+### removeEventListeners()
+
+The `removeEventListeners()` method removes all listeners set up on `sos.sync` object.
+
+```ts expandable
+removeEventListeners(): void;
+```
+
+<Separator />
+
+### wait()
+
+The `wait()` method synchronizes with other devices by waiting for other devices before proceeding.
+
+One way to synchronize devices is to make them wait for each other at a certain moment. This would be most commonly used before the
+device hits “play” on a video, to make it wait for other devices so they all start playing the video at the same time.
+
+This method returns a promise that resolves once all the devices meet and are ready to continue together. Any action that results in
+visible synchronized behavior should be triggered immediately after and any related background preparations should be called before to
+prevent delays.
+
+Sometimes devices might go out of sync due to unpredictable conditions like loss of internet connection. To ensure re-sync of an out of
+sync device, you can pass some data as the first argument. This can be any data that informs the whole group about what content is
+about to play next. Once all devices are ready, data from the master device is passed to everyone and the rest of the data is ignored.
+Therefore, when implementing your applet you should rely on the result data and not the data that is passed to the wait method as an
+argument.
+
+```ts expandable
+wait(data?: any, groupName?: string, timeout?: number): Promise<any>;
+```
+
+<Separator />
+
+### ~connect(options)~
+
+:::danger
+
+This method was deprecated. Use `connect({ engine: 'sync-server' })` instead.
+
+:::
+
+```ts expandable
+connect(options?: string): Promise<void>;
+```
+
+<Separator />
+
+### ~init()~
+
+:::danger
+
+This method was deprecated. use `sos.sync.joinGroup()` instead.
+
+:::
+
+```ts expandable
+init(groupName?: string, deviceIdentification?: string): Promise<void>;
+```
+
+<Separator />
+
+### ~setValue()~
+
+:::danger
+
+This method was deprecated. use `sos.sync.broadcastValue()` instead.
+
+:::
+
+```ts expandable
+setValue(key: string, value: any, groupName?: string): Promise<void>;
+```

package/docs/sos/video.md

@@ -0,0 +1,285 @@
+# video
+
+The `sos.video` API groups together methods for video playback.
+
+:::warning
+First 5 parameters (uri, x, y, width, height) are unique identifiers for playing the video using play, stop, resume and pause methods.
+:::
+
+## Methods
+
+### onceEnded()
+
+The `onceEnded()` method returns a promise which is resolved after the specified video ended.
+
+```ts expandable
+onceEnded(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+<Separator />
+
+### onceStop()
+
+The `onceEnded()` method returns a promise which is resolved after the specified video have been stopped.
+
+```ts expandable
+onceStop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+<Separator />
+
+### onEnded()
+
+The `onEnded()` method sets up a listener, which is called whenever a video finished playing successfully.
+
+```ts expandable
+onEnded(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onError()
+
+The `onError()` method sets up a listener, which is called whenever a video failed to finish playing.
+
+```ts expandable
+onError(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onPause()
+
+The `onPause()` method sets up a listener, which is called whenever a video is paused
+
+```ts expandable
+onPause(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onPlay()
+
+The `onPlay()` method sets up a listener, which is called whenever a video starts to play.
+
+```ts expandable
+onPlay(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onPrepare()
+
+The `onPrepare()` method sets up a listener, which is called whenever a video started to be prepared.
+
+```ts expandable
+onPrepare(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onResume()
+
+The `onResume()` method sets up a listener, which is called whenever a video is resumed
+
+```ts expandable
+onResume(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### onStop()
+
+The `onStop()` method sets up a listener, which is called whenever a video has been stopped.
+
+```ts expandable
+onStop(listener: (event: IVideoEvent) => void): void;
+// show-more
+interface IVideoEvent {
+    type: VideoEventType;
+    srcArguments: IVideoProperties;
+}
+
+type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
+
+interface IVideoProperties {
+    uri: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+```
+
+<Separator />
+
+### pause()
+
+The `pause()` method pauses the video, playback can be resumed with `resume()`.
+
+```ts expandable
+pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+<Separator />
+
+### play()
+
+The `play()` method starts the playback of a video previously prepared by `prepare()` method.
+
+```ts expandable
+play(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+<Separator />
+
+### prepare()
+
+The `play()` method loads the video into memory and prepares it for a playback.
+
+```ts expandable
+prepare(uri: string, x: number, y: number, width: number, height: number, options?: IOptions): Promise<void>;
+// show-more
+interface IOptions {
+    /** @deprecated */
+    '4k'?: boolean;
+    background?: boolean;
+    volume?: number;
+}
+
+```
+
+#### Params
+
+| Name                              | Type      | Description                                                                   |
+|-----------------------------------|-----------|-------------------------------------------------------------------------------|
+| `options.`                        | `boolean` | 4k Support for 4k video (Deprecated since Tizen Core App v2.1.0)              |
+| `options.background` *(optional)* | `boolean` | Bring video behind the applet html (similar to z-index: -1)                   |
+| `options.volume` *(optional)*     | `number`  | Adjust volume of playing video itself (doesn't adjust display speaker volume) |
+
+<Separator />
+
+### removeEventListeners()
+
+The `removeEventListeners()` method removes all listeners set up for all videos.
+
+```ts expandable
+removeEventListeners(): void;
+```
+
+<Separator />
+
+### resume()
+
+The `resume()` method resumes the video paused by `pause()`.
+
+```ts expandable
+resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+<Separator />
+
+### stop()
+
+The `stop()` method stops the video, it can't be resumed with `resume()`.
+
+```ts expandable
+stop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```

package/docs/sos_management/app.md

@@ -0,0 +1,102 @@
+# app
+
+The `sos.management.app` API groups together methods for managing the signageOS application installed on the system.
+
+## Methods
+
+### getType()
+
+The `getType()` method returns type of the platform the application is running on.
+
+:::info
+
+If you need to get specific Android brand or Raspberry Pi model, use the `sos.management.firmware.getType()`.
+
+:::
+
+```ts expandable
+getType(): Promise<AppType>;
+// show-more
+type AppType = 'android' | 'brightsign' | 'default' | 'linux' | 'sssp' | 'tizen' | 'webos' | 'windows' | 'chromeos' | AnyString;
+
+type AnyString = string & {};
+
+```
+
+<Separator />
+
+### getVersion()
+
+The `getVersion()` method returns version of the application currently running.
+
+:::info
+
+This API is only available for Applets deployed via Timing from Box or REST API.
+
+:::
+
+```ts expandable
+getVersion(): Promise<string>;
+```
+
+<Separator />
+
+### upgrade(appUri)
+
+The `upgrade(appUri)` method upgrades the signageOS application with provided appUri. Open users can upgrade app passing FQN
+uri where the application main file is located.
+
+This file type/extension differs for every platform. E.g.:
+- SSSP: http://example.com/apps/sssp_config.xml or http://example.com/apps/ApplicationName.zip
+- Tizen: http://example.com/apps/sssp_config.xml or http://example.com/apps/ApplicationName.wgt
+- Webos 1, 2: http://example.com/apps/ApplicationName.zip
+- Webos 3+: http://example.com/apps/ApplicationName.ipk
+- Brightsign: http://example.com/apps/ApplicationName.zip
+- Linux: http://example.com/apps/ApplicationName.apk
+- Android: http://example.com/apps/ApplicationName.apk
+
+```ts expandable
+upgrade(appUri: string): Promise<void>;
+```
+
+#### Params
+
+| Name     | Type     | Description                                         |
+|----------|----------|-----------------------------------------------------|
+| `appUri` | `string` | FQN uri where the application main file is located. |
+
+<Separator />
+
+### upgrade(baseUrl, version)
+
+The `upgrade(baseUrl, version)` does the same as `upgrade(version, baseUrl)`.
+
+```ts expandable
+upgrade(baseUrl: string, version: string): Promise<void>;
+```
+
+#### Params
+
+| Name      | Type     | Description                                         |
+|-----------|----------|-----------------------------------------------------|
+| `baseUrl` | `string` | The server URL where application files are located. |
+| `version` | `string` | The version of the application being installed.     |
+
+<Separator />
+
+### upgrade(version, baseUrl)
+
+The `upgrade(version, baseUrl?)` method upgrades the signageOS application using version and baseUrl. Platform users can install general
+application version directly with passing just version number. Optionally, the baseUrl can be passed as argument to specify server
+where the application files are accessible.
+
+```ts expandable
+upgrade(version: string, baseUrl?: string): Promise<void>;
+```
+
+#### Params
+
+| Name                   | Type     | Description                                                                                              |
+|------------------------|----------|----------------------------------------------------------------------------------------------------------|
+| `version`              | `string` | The version of the application being installed.                                                          |
+| `baseUrl` *(optional)* | `string` | Optional server URL where application files are located.<br/>(Default value: `"https://2.signageos.io"`) |

package/docs/sos_management/audio.md

@@ -0,0 +1,29 @@
+# audio
+
+The `sos.management.audio` API groups methods for managing audio settings.
+
+## Methods
+
+### getVolume()
+
+The `getVolume()` method returns current volume level of the device.
+
+```ts expandable
+getVolume(): Promise<number>;
+```
+
+<Separator />
+
+### setVolume()
+
+The `getVolume()` method set the volume level of the device.
+
+```ts expandable
+setVolume(volume: number): Promise<void>;
+```
+
+#### Params
+
+| Name     | Type     | Description              |
+|----------|----------|--------------------------|
+| `volume` | `number` | Value between 0 and 100. |