This is an expert-level functionality

Misuse of Scripts can cause issues, including device misconfiguration, device disconnection, or other unforeseeable situations.

Use this feature wisely and always test your scripts in lab before running them on production devices.

Feature entitlement: scripts · Plan: 👑 Pro Device Plan or higher

Introduction to Custom Scripts

Scripts allow users to send custom scripts in operating-system-specific programming languages. The script can use device-specific native APIs.

Prerequisites

signageOS CLI - version 1.8.0 and newer
Minimal Core App version per platform that supports Custom Scripts:

Core App	Minimal Version
Tizen	2.9.0
webOS	2.10.0
BrightSign	2.3.0
Linux	2.6.0
Windows	3.2.0
Android	4.12.0
ChromeOS	1.2.0
Emulator	14.15.1

Minimal front display version: 14.34.1 on every platform. Older versions do not pass sos.config to a script, so the script starts but receives none of its parameters and cannot tell what to do. A script running on such a device typically reports that the operation is undefined.

Note that such an execution is still recorded as succeeded with exit code 0, because the script itself ran and exited cleanly. The evidence is in the returned payload, not in the execution status, so always read the reply before concluding that a run worked.
No minimal platform (OS) version. Old panels run Custom Scripts too, Tizen 2.4 and webOS 3.x included, as long as the script itself can run there. BrightSign was verified from firmware 8.5.64 to 9.1.140.

A script that never replies is recorded as succeeded

When a browser-runtime script does not call postResult(), the device application waits, gives up after 90 seconds and records a placeholder of its own: the run is succeeded, exit code 0, with the single output line OK - executed. Whatever the script meant to return is lost, and a caller waiting for a real reply, such as a feature that matches replies by correlation id, sees the operation stay pending and then fail.

On older devices the usual cause is syntax the engine cannot parse. Custom Scripts have no build step: the source runs exactly as written, so one ES2015+ token, a trailing comma in a function call for instance, turns the whole file into a parse error and not a single line runs. The failure is indistinguishable from a script that ran and returned nothing.

So, for a browser-runtime script that has to work on old Tizen or webOS panels:

write it in ES5, and check it parses as ES5 before uploading;
make every path answer, including a timeout of the script's own, so silence is never the outcome;
read the returned payload rather than the execution status. The status only reports that the runtime finished, not that the work happened.

Create a new project

Generate boilerplate project with signageOS CLI:

sos custom-script generate

Alternatively, copy the boilerplate code from signageOS/custom-script-boilerplate.

You will have a project with the following structure:

.
├── README.md
├── .sosconfig.json
├── .gitignore
├── default
│   └── setBrightness.js
├── linux
│   └── setBrightness.sh
├── tizen
│   └── setBrightness.js

How it works

Config file

When calling sos custom-script upload, it reads the .sosconfig.json file. This file contains several fields:

name - Custom Script will be created and displayed using this name
description - Short description of the Custom Script that will be displayed in Custom Script detail. It should help the user to understand what the Custom Script does.
version - Used for version control. Must follow the semantic versioning format. Each time the Custom Version changes, it should be incremented, however it's possible to overwrite the same version as long as its not published.
dangerLevel - Can be one of the following:
- low, medium, high, critical
- It represents the danger level of the Custom Script. It should be set according to the potential impact of the Custom Script on the device.
sos - Auto-generated object containing signageOS metadata. Currently includes:
- @signageos/front-applet - The version of the @signageos/front-applet JS API that was current when the project was generated. This version is sent to the platform during upload to track JS API compatibility.
platforms - List of platforms and their files that will be uploaded to the signageOS platform.
configDefinition - list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": [])

Platforms

The general structure of the platforms field is as follows:

{
	"{platform}": {
		"rootDir": "{rootDir}",
		"mainFile": "{mainFile}",
		"runtime": "{runtime}"
	}
}

{platform} - name of the platform. It should be one of:
- default, tizen, webos, android, linux, windows, brightsign
{rootDir} - relative path to the platform implementation. This is where the platform-specific files are located in this repository.
{mainFile} - entry point of the platform implementation. This file will be executed
{runtime} - runtime of the platform. It should be one of:
- ps1, bash, sh, nodejs, browser, brs

Platforms and supported runtimes matrix:

Platform	Available Runtimes
Samsung Tizen	browser
LG webOS	browser
Windows	ps1
Linux	bash
Android	sh
BrightSign	browser (CoreApp / CloudControl) nodejs, sh (Supervisor)
ChromeOS	browser
Emulator (default)	browser

Config Definition

configDefinition is a list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": []).

Config Definition item has the following options (same as Applet configuration):

Key	Value type	Description
name	string	name of the configuration
valueType	string \| url \| enum \| number \| secret \| encrypted	expected value type
list	array of strings \| numbers	only for valueType enum, list of predefined options
mandatory	boolean	required to be filled before executing script
description	string	description shown in the UI to guide user
placeholder	string	field placeholder in the UI to guide user; `placeholder` is never used as default value
min	number	minimum number value user can fill in to the field
max	number	maximum number value user can fill in to the field

`secret` and `encrypted` type in configuration

Script configuration is often used to pass sensitive data, such as tokens, credentials, and passwords. To protect these values, use the Script configuration with one of these value types.

secret value type

Use this type if you want to mask the value in the Box UI. It is suitable for less sensitive data. The value is stored in the database in its raw form and may be visible, for example, in device history.
encrypted value type:

This type provides stronger protection. The value is encrypted using asymmetric encryption with a provided public key, which is generated for your company on demand. It is stored in encrypted form in the database and cannot be read anywhere.

Full example

.sosconfig.json with defined configDefinition
{
	// ... .sosconfig.json
	"sos": {
		"@signageos/front-applet": "8.5.2"
	},
	"configDefinition": [
		{
			"name": "wifiSSID",
			"valueType": "secret",
			"mandatory": true,
			"description": "An SSID for the WiFi network."
		},
		{
			"name": "authToken",
			"valueType": "encrypted",
			"mandatory": true,
			"description": "A token generated by My Control used for authentication against My cloud."
		},
		{
			"name": "myBaseUrl",
			"valueType": "url",
			"description": "A base URL to My cloud. No slash at the end required.",
			"placeholder": "https://api.signageos.io"
		},
		{
			"name": "playerDuration",
			"valueType": "string",
			"description": "A length of generated playlist in '##s' format (seconds).",
			"placeholder": "172800s"
		},
		{
			"name": "refreshIntervalMs",
			"valueType": "number",
			"description": "Frequency of trying to generate new playlist from My cloud in milliseconds.",
			"placeholder": "65000",
			"min": 60000,
			"max": 70000
		},
		{
			"name": "playerId",
			"valueType": "string",
			"description": "An identifier for the device used to identifying against cloud. E.g. platform: SSSP, WEBOS, BRIGHTSIGN, ANDROID, WINDOWS, LINUX",
			"placeholder": "{PLATFORM}_{SERIAL_NUMBER}"
		},
		{
			"name": "proxyUrl",
			"valueType": "url",
			"description": "A prefix for all HTTP(s) requests done by My player to My cloud. Default is no proxy.",
			"placeholder": "https://cors-anywhere.herokuapp.com/"
		}
	]
}

.sosconfig.json when not using configDefinition
{
	// ... .sosconfig.json
	"configDefinition": []
}

Script output

Script can return back response(s) during it's execution. Each script runtime has a platform-specific syntax described below.

Runtime	Platform	Response
browser	Tizen BrightSign webOS	javascript function - `postResult('your response')`
nodejs	BrightSign (Supervisor)	javascript function - `postResult('your response')`
bash / sh	Linux	Terminal - `stdout` or `echo 'your response'`
ps1	Windows	PowerShell - `Write-Output`

tip

Calling postResult('your response') immediately terminates the browser-based script.

Sample code for browser runtime:

Script output in browser runtime
var brightness = sos.config.brightness;

sos.management.screen
	.setBrightness('03:00:00', brightness, '23:00:00', brightness)
	.then(function () {
		// pass custom response of the script
		postResult('SUCCESS! Brightness set to ' + brightness);
	})
	.catch(function (e) {
		// pass custom response of the script
		console.log(e);
		postResult('FAILURE! Brightness not set to ' + brightness);
	});

FAQ for scripts running in browser runtime

The JavaScript code executed in a browser-based runtime is limited to the capabilities of a browser version on a given device. Check browser version of your target device to avoid running scripts that uses unsupported syntax.

The general recommendation is to use ES5-compatible JavaScript code.

Upload custom script

Run the following command to upload your custom script to signageOS

sos custom-script upload

When calling sos custom-script upload, it reads the .sosconfig.json file. After the upload is completed, you will get customScriptUid in the uid field in .sosconfig.json file. Which you can use to run custom scripts using REST APIs.

Execute custom script

Your custom script can be executed on device using Box or REST API.

Custom scripts can be executed on one-by-one basis as well as using Bulk actions.

Debugging

Browser runtime scripts

The best way to debug script runtime is to enable Native debug on your target device and inspect the browser console for logs and errors.

Prerequisites​

Create a new project​

How it works​

Config file​

Platforms​

Config Definition​

secret and encrypted type in configuration​

Full example​

Script output​

FAQ for scripts running in browser runtime​

Upload custom script​

Execute custom script​

Debugging​

Browser runtime scripts​