Skip to content

Registration Procedure

Plugin Registration

The Stream Deck application loads each plugin at launch or when the plugin is installed. The plugin must follow the registration procedure as described in this page. The procedure is fairly simple and you can re-use the code already implemented in the various Samples. We provide an implementation of this procedure in Javascript, C++ and Objective-C.

When the Stream Deck application is launched, it spawns one instance of each plugin. The plugin process is started and

  • for Javascript plugins, its connectSocket() is called with several parameters.
  • for compiled plugins written for example in C++ or Objective-C, its main() function is called with several parameters.

These parameters contain among others the port to use for the communication and the plugin unique identifier. The plugin should open the websocket communication and registers itself with the Stream Deck application. After this procedure, the plugin and the Stream Deck application are communicating though the websocket.


Javascript plugin Registration

For a Javascript plugin, you need to declare the following Javascript function:

function connectSocket(inPort, inPluginUUID, inRegisterEvent, inInfo)

This function is called when the plugin is loaded and should:

  • create the WebSocket with the port passed in parameter:
websocket = new WebSocket("ws://localhost:" + inPort);
  • When the WebSocket is open, the plugin needs to be registered with a special json data:
websocket.onopen = function()
{
    // WebSocket is connected, register the plugin
    var json = {
        "event": inRegisterEvent,
        "uuid": inPluginUUID
    };

    websocket.send(JSON.stringify(json));
};
  • After performing these 2 steps, the plugin should receive the events though the function:
websocket.onmessage = function (evt)

The inInfo parameter is described in the section Info parameter.


Compiled plugin Registration

If your plugin is a compiled plugin (C++, Objective-C, ...), the command line tool will be executed with the following parameters:

Parameters Description
-port The string "-port"
port The port that should be used to create the WebSocket
-pluginUUID The string "-pluginUUID"
UUID A unique identifier string that should be used to register the plugin once the WebSocket is opened
-registerEvent The string "-registerEvent"
event The event type that should be used to register the plugin once the WebSocket is opened
-info The string "-info"
info A stringified json containing the Stream Deck application information and devices information.

The info json is described in the section Info parameter.


Property Inspector Registration

For the Property Inspector, you need to declare the following Javascript function:

function connectSocket(inPort, inPropertyInspectorUUID, inRegisterEvent, inInfo, inActionInfo)
Members Description
inPort The port that should be used to create the WebSocket
inPropertyInspectorUUID A unique identifier string to register Property Inspector with Stream Deck software
inRegisterEvent The event type that should be used to register the plugin once the WebSocket is opened. For Property Inspector this is
"registerPropertyInspector"
inInfo A json object containing information about the application. (see below Info parameter)
inApplicationInfo A json array containing information about the plugin's receiving action. (see below inApplicationInfo parameter.

This function is called when the Property Inspector is displayed and should:

  • create the WebSocket with the port passed in parameter:
websocket = new WebSocket("ws://localhost:" + inPort);
  • When the WebSocket is open, the Property Inspector needs to be registered with a special json data:
websocket.onopen = function()
{
    // WebSocket is connected, register the Property Inspector
    var json = {
        "event": inRegisterEvent,
        "uuid": inPropertyInspectorUUID
    };

    websocket.send(JSON.stringify(json));
};
  • After performing these 2 steps, the Property Inspector should receive the events though the function:
websocket.onmessage = function (evt)

The inInfo parameter is described in the section Info parameter.


Info parameter

The info parameter used in the registration process is a json object like:

{
  "application": {
    "language": "en", 
    "platform": "mac", 
    "version": "4.0.0"
  }, 
  "devices": [
    {
      "id": "55F16B35884A859CCE4FFA1FC8D3DE5B", 
      "size": {
        "columns": 5, 
        "rows": 3
      }, 
      "type": 0
    },
    {
      "id": "B8F04425B95855CF417199BCB97CD2BB", 
      "size": {
        "columns": 3, 
        "rows": 2
      }, 
      "type": 1
    }
  ]
}
Members Description
application A json object containing information about the application.
devices A json array containing information about the devices.

The application object contains the following members:

application Description
language In which language the Stream Deck application is running. Possible values are en, fr, de, es, ja, zh_CN.
platform On which platform the Stream Deck application is running. Possible values are kESDSDKApplicationInfoPlatformMac ("mac") and kESDSDKApplicationInfoPlatformWindows ("windows").
version The Stream Deck application version.

The devices array contains the following members:

devices Description
id An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
type Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0) and kESDSDKDeviceType_StreamDeckMini (1).
size The number of columns and rows of keys that the device owns.

inApplicationInfo parameter

The inApplicationInfo parameter is a stringified JSON-object (aka JSON-string). It contains the following information:

{
  "action":   "com.elgato.sample.action",
  "context":  "4F7D1F1473C169D7F411BFCBCE5DEB3B"
}
Members Description
action The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
context An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.