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 connectElgatoStreamDeckSocket() 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 connectElgatoStreamDeckSocket(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 connectElgatoStreamDeckSocket(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)
inActionInfo	A json object containing information about the action. (see below inActionInfo 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.1.0"
  }, 
  "plugin": {
    "version": "1.1"
  },
  "devicePixelRatio": 2, 
  "devices": [
    {
      "id": "55F16B35884A859CCE4FFA1FC8D3DE5B", 
      "name": "Device Name", 
      "size": {
        "columns": 5, 
        "rows": 3
      }, 
      "type": 0
    },
    {
      "id": "B8F04425B95855CF417199BCB97CD2BB", 
      "name": "Another Device", 
      "size": {
        "columns": 3, 
        "rows": 2
      }, 
      "type": 1
    }
  ]
}

Members	Description
application	A json object containing information about the application.
plugin	A json object containing information about the plugin.
devices	A json array containing information about the devices.
devicePixelRatio	Pixel ratio value to indicate if the Stream Deck application is running on a HiDPI screen.

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 plugin object contains the following members:

plugin	Description
version	The plugin version as written in the manifest.json.

The devices array contains the following members:

devices	Description
id	An opaque value identifying the device.
type	Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0), kESDSDKDeviceType_StreamDeckMini (1), kESDSDKDeviceType_StreamDeckXL (2), kESDSDKDeviceType_StreamDeckMobile (3) and kESDSDKDeviceType_CorsairGKeys (4). This parameter parameter won't be present if you never plugged a device to the computer.
size	The number of columns and rows of keys that the device owns.
name	The name of the device set by the user.

---

inActionInfo parameter

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

{
  "action": "com.elgato.analogclock.action", 
  "context": opaqueValue, 
  "device": opaqueValue, 
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 2, 
      "row": 1
    }
  }
}

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.
device	An opaque value identifying the device.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.