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:

/* 
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:

// 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:

/* 
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
  });
});

GitHub Example

Example of Applet for basic start

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:

/* 
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();
  });
});

GitHub Example

Example of Applet with restore() method

refresh()

AFter calling this method applet is freshly launched.

Javascript example:

await sos.refresh()

appletVersion

This property returns current active Applet version.

Javascript example:

/* 
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). Then you can access your values via sos.config object.

// Parsed JSON object passed to Timing for current applet & current device together
console.log(sos.config.mySecretID);
console.log(sos.config.imgUrl);

Guide

Custom variables in Applet

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.
2. The authHash is unique and can be revoked upon request.
3. 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.

async function startApplet() {
			await sos.onReady();
      console.log(sos.authHash);
}
window.addEventListener('sos.loaded', startApplet);

Guide

Using authHash for device identification

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 (i.e. flash drives)
FILE_SYSTEM_FILE_CHECKSUM	Device is can calculate a file checksum
VIDEO_4K	Device is capable of playing 4K video
SERIAL	Device supports communication with peripherals over serial

Javascript example:

if (await sos.display.supports('VIDEO_4K')) {
	// play 4K video
}

GitHub Example

Example of Content Capabilities

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.
WIFI	Device can connect to a Wi-Fi.
WIFI_SCAN	Device can scan surrounding Wi-Fi devices.
WIFI_AP	Device is capable of becoming a Wi-Fi endpoint that other devices can connect to.
SET_BRIGHTNESS	Device can change its screen brightness.
SET_TIME	Device can change its time settings.
NTP_TIME	Device can synchronize its time with an NTP server.
PACKAGE_INSTALL	It's possible to install additional packages on the device, managed by signageOS application.
SET_VOLUME	Device can change its audio volume.
SET_REMOTE_CONTROL_ENABLED	Device can disable control via IR remote to increase security.

if (await sos.management.supports('WIFI')) {
	// connect to wifi
}

GitHub Example

Example of Management Capabilities