Skip to main content
Version: 6.4.2

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/PropertyDescriptionSupported 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 again5.8.0
appletVersionReturns current Applet versionJS API 4.5.0, Front-display 7.8.0
config objectReturns object with key-values set via Timing or as a bundled configJS API 1.5.0, Front-display 6.8.0
config objectReturns object with key-values set via Timing or as a bundled config1.0.0
capabilitiesEnum of device-specific capabilities and features1.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
});
});

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

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 cofiguration to your Applet

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.

CapabilityDescription
FILE_SYSTEM_EXTERNAL_STORAGEDevice file system supports external storage (i.e. flash drives)
FILE_SYSTEM_FILE_CHECKSUMDevice is can calculate a file checksum
VIDEO_4KDevice is capable of playing 4K video
SERIALDevice supports communication with peripherals over serial

Javascript example:

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

Management capabilities

Management capabilities refer to the capabilities of the display's internal state management.

CapabilityDescription
BATTERY_STATUSDevice can report its battery status.
WIFIDevice can connect to a Wi-Fi.
WIFI_SCANDevice can scan surrounding Wi-Fi devices.
WIFI_APDevice is capable of becoming a Wi-Fi endpoint that other devices can connect to.
SET_BRIGHTNESSDevice can change its screen brightness.
SET_TIMEDevice can change its time settings.
NTP_TIMEDevice can synchronize its time with an NTP server.
PACKAGE_INSTALLIt's possible to install additional packages on the device, managed by signageOS application.
SET_VOLUMEDevice can change its audio volume.
SET_REMOTE_CONTROL_ENABLEDDevice can disable control via IR remote to increase security.
if (await sos.management.supports('WIFI')) {
// connect to wifi
}