This is an expert-level functionality

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

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

Introduction

Plugins are used to extend the native features of signageOS and integrate them directly into system policies. Once installed, a Plugin behaves like a standard part of the system. It is executed periodically and automatically, ensuring its configuration is consistently enforced on the device.

Prerequisites

• signageOS CLI - version 2.6.0-rc.0 and newer
• Minimal Core App version per platform that supports Plugins:

Core App	Minimal Version
Tizen	2.10.2-runners-plugins.5520
webOS	2.10.0-runners-plugins.4373
BrightSign	coming soon
Linux	coming soon
Windows	coming soon
Android	coming soon
ChromeOS	coming soon
Emulator	14.21.3-plugins-runners.9762

Plugins allow users to send its implementation in operating-system-specific programming languages. The plugin can use device-specific native APIs.

Operating system	Plugin type
Tizen	HTML + JS + Tizen APIs
webOS	HTML + JS + webOS APIs

Create a new project

Generate boilerplate project with signageOS CLI:

sos plugin generate

Alternatively, copy the boilerplate code from signageOS/plugins-boilerplate.

You will have a project with the following structure:

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

In the setBrightness.js file, you can see a sample plugin structure. Every plugin must implement both the set and get methods:

• The set method is required for applying configuration, policy, or bulk operations.
• The get method is required for telemetry and retrieving the current state.

This ensures your plugin is compatible with signageOS policies and device management workflows.

var sosPlugin = {
	/**
	 * Required for settings, policy and bulk.
	 */
	set: function (data) {
		return new Promise(function (resolve, reject) {
			/// yor code
		});
	},
	/**
	 * Required for telemetry.
	 */
	get: function () {
		return new Promise(function (resolve, reject) {
			/// your code
		});
	}
};

How it works

Config file

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

• name - Plugin will be created and displayed using this name
• description - Short description of the Plugin that will be displayed in Plugin detail. It should help the user to understand what the Plugin does.
• version - Used for version control. Must follow the semantic versioning format. Each time the Plugin Version changes, it should be incremented, however it's possible to overwrite the same version as long as its not published.
• 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": [])

Schema file

Contains the schema definition for the plugin. Definition is the same for set and get methods in the plugin.

{
    "schema": [{
        "name": "backgroundColor",
        "description": "Background color input",
        "valueType": "string"
    }]
}

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
• {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:
  • browser,

Platforms and supported runtimes matrix:

Platform	Available Runtimes
Samsung Tizen	browser
LG webOS	browser
Windows	coming soon
Linux	coming soon
Android	coming soon
BrightSign	coming soon
ChromeOS	coming soon
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 plugin
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

Plugin configuration is often used to pass sensitive data, such as tokens, credentials, and passwords. To protect these values, use the Plugin 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
	"configDefinition": [
		{
			"name": "wifiSSID",
			"valueType": "secret",
			"mandatory": true,
			"description": "An SSID for the WiFi network."
		},
		{
			"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/"
		}
	]
}

Or leave empty when not using configDefinition.

.sosconfig.json when not using configDefinition

{
	// ... .sosconfig.json
	"configDefinition": []
}

Upload plugin

Run the following command to upload your plugin to signageOS

sos plugin upload

When calling sos plugin upload, it reads the .sosconfig.json file. After the upload is completed, you will get pluginUid in the uid field in .sosconfig.json file.