Applet configuration

This section describes how to use [`sos.config`](/sdk/sos/#config) API.

You can add a number of key-value pairs into the Applet in a form of config.

Config values are unique per device and typically is used for passing:

• custom variables
• tokens and credentials
• any dynamic value that differs per-device

Accessing configuration

The configuration is available through sos.config object.

warning

The configuration may contain extra entries, besides the declared configuration of the applet.

import sos from '@signageos/front-applet';

sos.onReady(() => {
	// Parsed JSON object passed for current applet & current device together
	console.log(sos.config);

	console.log(sos.config.identification);

	console.log(sos.config.yourKey);
});

Defining configuration in code

Any configuration can be defined as code in package.json.

You can define multiple configuration in a config array. Each configuration item has the following definition:

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 building applet or assigning applet
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 numeric value user can fill in to the field
max	number	maximum numeric value user can fill in to the field

secret and encrypted type in configuration

Applet/Timing configurations are often used to pass sensitive data, such as tokens, credentials, and passwords. To protect these values, use the Applet 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, during an Applet/Timing configuration update.

• 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, even during an Applet/Timing configuration update.

Full example

package.json

"sos": {
    "config": [
      {
        "name": "wifiPassword",
        "valueType": "secret",
        "mandatory": true,
        "description": "A password 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/"
      }
    ],
    "appletUid": "967daxxxxxxx58e27376a5596028"
  },

Setting configuration values

Learn how to assign the configuration values using Box or REST API

Defining configuration for singlefile (Basic) applets

Singlefile applets — created directly in the Box HTML editor — do not have a package.json file. Instead, you can define the configuration schema directly in Box.

Using the Box UI editor

Navigate to your singlefile applet in Box and select the version you want to configure. Below the HTML editor, you will find the **Configuration Definition** section. Click **Add field** to start defining your configuration schema. For each configuration field, specify:

• Name — the key used to access this value in sos.config (e.g., apiToken, refreshInterval)
• Value Type — one of: string, number, url, enum, secret, encrypted
• Mandatory — whether the field must be filled when assigning the applet to a device
• Description — a hint shown in the UI to guide the user

Click **Save** to persist the configuration definition. The schema is stored in the database and will be used for validation and UI rendering when creating Timings for this applet version.

Using the REST API

You can also define the configuration schema by including configDefinition in the request body when creating or updating an applet version:

curl -X POST "https://api.signageos.io/v1/applet/{appletUid}/version" \
  -H "Content-Type: application/json" \
  -H "x-auth: {your-api-token}" \
  -d '{
    "binary": "<html>...</html>",
    "configDefinition": [
      {
        "name": "apiToken",
        "valueType": "secret",
        "mandatory": true,
        "description": "API authentication token"
      },
      {
        "name": "displayId",
        "valueType": "string",
        "description": "Custom identifier for this device"
      }
    ]
  }'

warning

When configDefinition is provided in the API request body, it takes precedence over any sos.config found in package.json. This applies to both singlefile and multifile applets.

All value types — including secret and encrypted — are fully supported for singlefile applets, with the same masking and encryption behavior as multifile applets.