@signageos/front-applet 7.2.0 → 8.0.0

package/docs/sos/offline/cache.md

@@ -0,0 +1,183 @@
+# cache
+
+The `sos.offline` API groups together methods used to download and save arbitrary files, which can be accessed even if the device is offline.
+
+:::warning
+
+Emulator has certain limitations while handling offline files. [Read more here](https://docs.signageos.io/hc/en-us/articles/4405238997138)
+
+:::
+
+## Methods
+
+### decompressFile()
+
+The `decompressFile()` decompresses the file specified by `uid` into a new file specified by `destinationUid`.
+
+```ts expandable
+decompressFile(uid: string, destinationUid: string, method: 'zip'): Promise<void>;
+```
+
+#### Possible errors
+
+The method throws an error if the uid does not exist.
+
+<Separator />
+
+### deleteContent()
+
+The `deleteContent() method removes the value specified by `uid` key.
+
+```ts expandable
+deleteContent(uid: string): Promise<void>;
+```
+
+<Separator />
+
+### deleteFile()
+
+The `deleteFile()` method removes the file specified by `uid`.
+
+```ts expandable
+deleteFile(uid: string): Promise<void>;
+```
+
+#### Possible errors
+
+The method throws an error if the uid does not exist.
+
+<Separator />
+
+### getChecksumFile()
+
+The `getChecksumFile()` computes a checksum of the file specified by `uid`.
+
+```ts expandable
+getChecksumFile(uid: string, hashType: HashAlgorithm): Promise<string>;
+// show-more
+type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha384' | 'sha512' | 'crc32' | AnyString;
+
+type AnyString = string & {};
+
+```
+
+#### Possible errors
+
+The method throws an error if the uid does not exist or the hashing algorithm is not supported.
+
+<Separator />
+
+### listContents()
+
+The `listContent()` method lists all values saved by `saveContent()` method.
+
+```ts expandable
+listContents(): Promise<string[]>;
+```
+
+<Separator />
+
+### listFiles()
+
+The `listFiles()` method list all currently cached files.
+
+```ts expandable
+listFiles(): Promise<string[]>;
+```
+
+<Separator />
+
+### loadContent()
+
+The `loadContent()` method gets the value specified by `uid`, which was previously saved by `saveContent()`.
+
+```ts expandable
+loadContent(uid: string): Promise<string>;
+```
+
+<Separator />
+
+### loadFile()
+
+The `loadFile()` method loads cached file, which was previously saved by `saveFile()` or `loadOrSaveFile()` methods.
+
+```ts expandable
+loadFile(uid: string): Promise<IFile>;
+// show-more
+interface IFile {
+    filePath: string;
+}
+
+```
+
+#### Possible errors
+
+The method throws an error if the uid does not exists
+
+<Separator />
+
+### loadOrSaveFile()
+
+The loadOrSaveFile() method loads the file from the cache, or downloads it if it's not already cached.
+
+```ts expandable
+loadOrSaveFile(uid: string, uri: string, headers?: {
+    [key: string]: string;
+}): Promise<IFile>;
+// show-more
+interface IFile {
+    filePath: string;
+}
+
+```
+
+<Separator />
+
+### saveContent()
+
+The `saveContent()` method saves a string value to the cache.
+
+```ts expandable
+saveContent(uid: string, content: string): Promise<void>;
+```
+
+<Separator />
+
+### saveFile()
+
+The `saveFile()` method downloads file from `uri` and saves it to the offline cache.
+
+:::warning
+
+`uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+
+:::
+
+```ts expandable
+saveFile(uid: string, uri: string, headers?: {
+    [key: string]: string;
+}): Promise<void>;
+```
+
+#### Possible errors
+
+The method throws an error if the network request fails or a file with the same uid is already cached
+
+<Separator />
+
+### validateChecksumFile()
+
+The `validateChecksumFile()` method validates whether the file, specified by `uid`, has the correct checksum.
+
+```ts expandable
+validateChecksumFile(uid: string, hash: string, hashType: HashAlgorithm): Promise<boolean>;
+// show-more
+type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha384' | 'sha512' | 'crc32' | AnyString;
+
+type AnyString = string & {};
+
+```
+
+#### Possible errors
+
+The method throws an error if the uid does not exist or the hashing algorithm is not supported.

package/docs/sos/offline/index.md

@@ -0,0 +1,188 @@
+# offline
+
+The `sos.offline` API groups together methods for storing and using JS, CSS and font files.
+
+:::warning
+
+Emulator has certain limitations while handling offline files. [Read more here](https://docs.signageos.io/hc/en-us/articles/4405238997138)
+
+:::
+
+## Methods
+
+### addFile()
+
+The `addFile()` method downloads the specified file and stores it locally.
+
+```ts expandable
+addFile(file: ISaveFile): Promise<void>;
+// show-more
+interface ISaveFile {
+    uid: string;
+    uri: string;
+    type: IFileType;
+    headers?: {
+        [key: string]: string;
+    };
+    flags?: IFlag[];
+}
+
+type IFileType = 'javascript' | 'css' | 'video';
+
+interface IFlag {
+    type: 'append';
+    element: IElement;
+}
+
+interface IElement {
+    uid: string;
+}
+
+```
+
+#### Example
+
+```ts
+await sos.offline.addFile({
+	// Source URL
+	uri: 'https://code.jquery.com/jquery-3.7.1.slim.min.js',
+	// Unique identifier of the resource
+	uid: 'jquery-3.7.1.slim.min.js',
+	// Indicate that the downloaded file is a JavaScript file
+	type: sos.offline.types.javascript,
+	// After the file is downloaded, it will be appended to document.body
+	flags: [sos.offline.flags.append(document.body)],
+});
+```
+
+<Separator />
+
+### addFiles()
+
+The `addFiles()` method downloads the specified files and stores them locally. The order in which the files are downloaded and stored is **not** guaranteed.
+
+```ts expandable
+addFiles(files: ISaveFile[]): Promise<void[]>;
+// show-more
+interface ISaveFile {
+    uid: string;
+    uri: string;
+    type: IFileType;
+    headers?: {
+        [key: string]: string;
+    };
+    flags?: IFlag[];
+}
+
+type IFileType = 'javascript' | 'css' | 'video';
+
+interface IFlag {
+    type: 'append';
+    element: IElement;
+}
+
+interface IElement {
+    uid: string;
+}
+
+```
+
+#### Example
+
+```ts
+await sos.offline.addFile([{
+	uri: 'https://unpkg.com/normalize.css@8.0.1/normalize.css',
+	uid: 'normalize.css',
+	type: sos.offline.types.css,
+	flags: [sos.offline.flags.append(document.head)],
+}, {
+	uri: 'https://code.jquery.com/jquery-3.7.1.slim.min.js',
+	uid: 'jquery-3.7.1.slim.min.js',
+	type: sos.offline.types.javascript,
+	flags: [sos.offline.flags.append(document.body)],
+}]);
+```
+
+<Separator />
+
+### addFilesSync()
+
+The `addFilesSync()` method downloads the specified files and stores them locally. The order in which the files are downloaded and stored **is** guaranteed.
+
+```ts expandable
+addFilesSync(files: ISaveFile[]): Promise<void>;
+// show-more
+interface ISaveFile {
+    uid: string;
+    uri: string;
+    type: IFileType;
+    headers?: {
+        [key: string]: string;
+    };
+    flags?: IFlag[];
+}
+
+type IFileType = 'javascript' | 'css' | 'video';
+
+interface IFlag {
+    type: 'append';
+    element: IElement;
+}
+
+interface IElement {
+    uid: string;
+}
+
+```
+
+<Separator />
+
+### addFont()
+
+The `addFont()` method downloads the specified file and stores it locally. You should use this method for loading fonts instead of
+using `addFile()`, because it also generates appropriate font-face definition.
+
+```ts expandable
+addFont(font: IAddFont): Promise<void>;
+// show-more
+interface IAddFont extends IFontFaceProperties {
+    uid: string;
+    append: HTMLElement;
+    formats: IFontFormats;
+}
+
+interface IFontFormats {
+    woff2: string;
+    eot?: string;
+    woff?: string;
+    ttf?: string;
+    svg?: string;
+}
+
+interface IFontFaceProperties {
+    fontFamily: string;
+    fontStretch?: string;
+    fontStyle?: IFontStyle;
+    fontWeight?: string;
+    unicodeRange?: string;
+}
+
+type IFontStyle = `normal` | `italic` | `oblique` | `initial` | `inherit` | AnyString;
+
+type AnyString = string & {};
+
+```
+
+#### Params
+
+| Name                             | Type           | Description                                                                                         |
+|----------------------------------|----------------|-----------------------------------------------------------------------------------------------------|
+| `font.uid`                       | `string`       | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters. |
+| `font.append`                    | `HTMLElement`  | Reference to HTMLElement where the generated font-face will resist.                                 |
+| `font.fontFamily`                | `string`       | Font family that can be referenced from your CSS.                                                   |
+| `font.formats`                   | `IFontFormats` | URI where these formats will be downloaded from.                                                    |
+| `font.fontStretch` *(optional)*  | `string`       | Allows you to make text wider or narrower.                                                          |
+| `font.fontStyle` *(optional)*    | `IFontStyle`   | Specifies the font style for a text. (Either `normal`, `italic`, `oblique`, `initial` or `inherit`) |
+| `font.fontWeight` *(optional)*   | `string`       | Sets how thick or thin characters in text should be displayed                                       |
+| `font.unicodeRange` *(optional)* | `string`       | Defines the range of unicode characters the font supports, default value is "U+0-10FFFF"            |
+| `font.formats`                   | `IFontFormats` | Dictionary of supported formats with its files                                                      |

package/docs/sos/osd.md

@@ -0,0 +1,13 @@
+# osd
+
+The `sos.osd` API groups together methods for working with the OSD (On Screen Display).
+
+## Methods
+
+### showOSD()
+
+The `showOSD()` method opens the OSD without typing the pin.
+
+```ts expandable
+showOSD(): Promise<void>;
+```

package/docs/sos/proofOfPlay.md

@@ -0,0 +1,37 @@
+# proofOfPlay
+
+## Methods
+
+### recordItemPlayed()
+
+The `recordItemPlayed()` method dispatches a `sos.command.dispatch()` command. It sends provided information about played content along
+with additional metadata about current applet and device to signageOS.
+
+```ts expandable
+recordItemPlayed(options: IRecordItemOptions): Promise<void>;
+// show-more
+interface IRecordItemOptions {
+    name: string;
+    customId?: string;
+    type?: 'video' | 'image' | 'html' | 'custom';
+    tags?: string[];
+    fileName?: string;
+    playbackSuccess?: boolean;
+    errorMessage?: string;
+}
+
+```
+
+#### Example
+
+```ts
+await sos.proofOfPlay.recordItemPlayed({
+  name: 'generic-brand-christmas-coffee-ad',
+  customId: 'dBE43bFB3312VFfvd34bgGHJVV334cd2',
+  type: 'video',
+  tags: ['generic-brand', 'christmas'],
+  fileName: 'coffee.mp4',
+  playbackSuccess: false,
+  errorMessage: 'Unsupported framerate 60fps',
+});
+```