Registration Procedure

How the plugin connects to Stream Deck.

Plugin Registration

The plugin must follow the registration procedure as follows. You can re-use the code implemented in the various Samples. We provide an implementation of this procedure in Javascript, but you can implement this in any programming language that supports WebSockets. When the Stream Deck application launches, it spawns one instance of each plugin.

• for Javascript plugins, connectElgatoStreamDeckSocket() is called with several parameters.

• for native plugins, the executable file is started with several parameters.

These parameters contain the port and unique identifier to use for communication with the Stream Deck application.

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 register with 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 two steps, the plugin should receive the events through the function:

websocket.onmessage = function (evt)

The inInfo parameter is described in the section Info parameter.

Compiled plugin Registration

For native plugins, the executable file will be started with the following parameters:

Parameters	Description
-port	The string "-port"
port	The port used to create the WebSocket
-pluginUUID	The string "-pluginUUID"
UUID	A unique identifier string 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 Stream Deck and device 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 to be used to create the WebSocket
inPropertyInspectorUUID	A unique identifier string to register Property Inspector with Stream Deck software
inRegisterEvent	The event type to register the plugin after opening the WebSocket. For the 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:

websocket.onopen = function()
{
 // WebSocket is connected, register the Property Inspector
 var json = {
  "event": inRegisterEvent,
  "uuid": inPropertyInspectorUUID
 };

 websocket.send(JSON.stringify(json));
};

• After performing these two steps, the Property Inspector should receive the events through 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": {
   "font": ".AppleSystemUIFont",
    "language": "en", 
    "platform": "mac", 
    "platformVersion": "11.4.0", 
    "version": "5.0.0.14247"
  }, 
  "plugin": {
   "uuid": "com.elgato.counter",
    "version": "1.4"
  },
  "devicePixelRatio": 2, 
  "colors": {
    "buttonPressedBackgroundColor": "#303030FF", 
    "buttonPressedBorderColor": "#646464FF", 
    "buttonPressedTextColor": "#969696FF", 
    "disabledColor": "#F7821B59", 
    "highlightColor": "#F7821BFF", 
    "mouseDownColor": "#CF6304FF"
  }, 
  "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.
colors	A JSON object containing information about the preferred user colors.

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.
platformVersion	The operating system version.

The plugin object contains the following members:

plugin	Description
version	The plugin version as written in the manifest.json.
uuid	The unique identifier of the plugin.

The devices array contains the following members:

devices	Description
id	A value to identify the device.
type	Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0), kESDSDKDeviceType_StreamDeckMini (1), kESDSDKDeviceType_StreamDeckXL (2), kESDSDKDeviceType_StreamDeckMobile (3), kESDSDKDeviceType_CorsairGKeys (4), kESDSDKDeviceType_StreamDeckPedal (5), kESDSDKDeviceType_CorsairVoyager (6), and kESDSDKDeviceType_StreamDeckPlus (7).
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": uniqueValue, 
  "device": uniqueValue, 
  "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 value to identify the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	An value to identify 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.