Events Sent

Plugins can send events to the Stream Dock application.

Both plugins and Property Inspectors can send the following events:

Event	Description
setSettings	Permanently save data for an action instance
getSettings	Request persistent data for an action instance
setGlobalSettings	Globally save plugin data
getGlobalSettings	Request global persistent data
openUrl	Open a URL in the default browser
logMessage	Write a debug message to the log file

Additional events that plugins can send:

Event	Description
setTitle	Dynamically change the title of an action instance
setImage	Dynamically change the image of an action instance
showAlert	Temporarily show an alert icon on the action instance's image
showOk	Temporarily show an "OK" checkmark icon on the action instance's image
setState	Change the state of an action instance that supports multiple states
sendToPropertyInspector	Send data to the Property Inspector

Additional events that Property Inspectors can send:

Event	Description
sendToPlugin	Send data to the plugin

setSettings

Plugins and Property Inspectors can use this event to permanently save data for an action instance

{
    "event": "setSettings",
    "context": uniqueValue,
    "payload": {<json data>}
}

Member	Description
event	setSettings
context	Identifier for the action instance
payload	Data sent by the plugin or Property Inspector

TIP

Note that when a plugin uses this API, the Property Inspector will automatically receive a didReceiveSettings callback with the new settings. Similarly, when the Property Inspector uses this API, the plugin will automatically receive a didReceiveSettings callback with the new settings.

getSettings

Plugins and Property Inspectors can use this event to request persistent data stored for an action instance

{
    "event": "getSettings",
    "context": uniqueValue
}

Member	Description
event	getSettings
context	Identifier for the action instance

The plugin or Property Inspector will asynchronously receive a didReceiveSettings event containing the settings for this action.

{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": uniqueValue, 
  "device": uniqueValue, 
  "payload": {
   "settings": {<json data>},
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "isInMultiAction": false
  }
}

setGlobalSettings

Plugins and Property Inspectors can globally save persistent data. The data will be securely stored in the Keychain on macOS or the Credential Store on Windows. This API can be used to save tokens or other data that should be available across all actions in the plugin.

{
    "event": "setGlobalSettings",
    "context": uniqueValue,
    "payload": {<json data>}
}

Member	Description
event	setGlobalSettings
context	Identifier for the instance action
payload	Data to be saved

TIP

Note that when the plugin uses this API, the Property Inspector will automatically receive a didReceiveGlobalSettings callback with the new settings. Similarly, when the Property Inspector uses this API, the plugin will automatically receive a didReceiveGlobalSettings callback with the new settings.

getGlobalSettings

Plugins and Property Inspectors can use this event to request globally stored persistent data.

{
    "event": "getGlobalSettings",
    "context": uniqueValue
}

Member	Description
event	getGlobalSettings
context	Identifier for the instance action

Plugins or Property Inspectors will asynchronously receive the event didReceiveGlobalSettings containing the global settings.

{
  "event": "didReceiveGlobalSettings", 
  "payload": {
     "settings": {<json data>}
   }
}

openUrl

Plugins or Property Inspectors can use this event to open a URL in the default browser.

{
    "event": "openUrl",
    "payload": {
        "url": "https://www.example.com"
    }
}

Member	Description
event	openUrl
payload	JSON object

The payload object contains the following member:

payload	Description
url	The URL to open

logMessage

Plugins or Property Inspectors can use this event to write debug logs to a log file.

{
 "event": "logMessage",
 "payload": {
  "message": "Hello World!"
 }
}

Member	Description
event	logMessage
payload	JSON object

The payload object contains the following member:

payload	Description
message	The message to write to the log file

setTitle

Plugins can use this event to dynamically change the title of an action instance.

{
    "event": "setTitle",
    "context": uniqueValue,
    "payload": {
        "title": "MyTitle",
        "target": software, hardware or both,
        "state": 0-based integer
    }
}

Member	Description
event	setTitle
context	Identifier for the action instance
payload	JSON object

The payload object contains the following members:

payload	Description
title	The title to set
target	Specifies whether the title should be displayed on hardware and software (0), only on hardware (1), only on software (2), default is 0
state	An integer value starting from 0, representing the state of an action with multiple states. If not specified, the title will be set for all states

setImage

Plugins can use this event to dynamically change the image of an action instance.

{
    "event": "setImage",
    "context": uniqueValue,
    "payload": {
        "image": <base64 encoded image>,
        "target": software, hardware or both,
        "state": 0-based integer
    }
}

Member	Description
event	setImage
context	Identifier for the action instance
payload	JSON object

The payload object contains the following members:

payload	Description
image	The base64-encoded image to set
target	Specifies whether the image should be displayed on hardware and software (0), only on hardware (1), only on software (2), default is 0
state	An integer value starting from 0, representing the state of an action with multiple states. If not specified, the image will be set for all states

Base64-encoded image examples:

"data:image/png;base64,avFOdwp0Ksgoe..."
"data:image/jpg;base64,avFOdwp0Ksgoe..."
"data:image/gif;base64,avFOdwp0Ksgoe..."

This API also accepts SVG images. Below is an example with an SVG image:

{
    "event": "setImage",
    "context": context,
    "payload": {
        "image": "data:image/svg+xml;charset=utf8,<svg></svg>",
        "target": 0
    }
}

showAlert

Plugins can use this event to display a temporary alert icon on the action.

{
    "event": "showAlert",
    "context": uniqueValue
}

Member	Description
event	showAlert
context	Identifier for the action instance

showOk

Plugins can use this event to display a temporary OK checkmark icon on the action.

{
    "event": "showOk",
    "context": uniqueValue
}

Member	Description
event	showOk
context	Identifier for the action instance

setState

Plugins can use this event to dynamically change the state of the action instance.

{
    "event": "setState",
    "context": uniqueValue,
    "payload": {
        state
    }
}

Member	Description
event	setState
context	Identifier for the action instance
payload	JSON object

The payload object contains the following member:

payload	Description
state	An integer value starting from 0, representing the state of the action with multiple states

sendToPropertyInspector

Plugins can use this event to send data to the Property Inspector.

{
    "action": "com.mirabox.demo.action1",
    "event": "sendToPropertyInspector",
    "context": uniqueValue,
    "payload": {<json data>}
}

Member	Description
action	Unique identifier for the action
event	sendToPropertyInspector
context	Identifier for the action instance
payload	JSON object

The Property Inspector will asynchronously receive the sendToPropertyInspector event.

{
  "action": "com.mirabox.demo.action1", 
  "event": "sendToPropertyInspector", 
  "context": uniqueValue, 
  "payload": {<json data>}
}

sendToPlugin

The Property Inspector can use this event to send data to the plugin.

{
    "action": "com.mirabox.demo.action1",
    "event": "sendToPlugin",
    "context": uniqueValue,
    "payload": {<json data>}
}

Member	Description
action	Unique identifier for the action
event	sendToPlugin
context	Identifier for the instance action
payload	JSON object

The plugin will asynchronously receive the sendToPlugin event.

{
  "action": "com.mirabox.demo.action1", 
  "event": "sendToPlugin", 
  "context": uniqueValue, 
  "payload": {<json data>}
}