Plugins
Create, add and update plugins
Smokeball offers a simple Plugin framework for developers to create custom web views within Smokeball desktop. A Plugin is defined by an integration partner, and can be assigned or subscribed to by multiple Smokeball firms.
Smokeball offers two implementations of a Plugin - Button or Tab. Partners can customize the appearance of the button/tab for what is shown to users.
Plugins are managed through two resources:
Plugins for creating or managing Plugins
PluginSubscriptions for assigning a Plugin to one or many Smokeball firms.
Placement Keys
One of the most important fields of a plugin is its placement
key, which defines where the plugin appears in Smokeball.
The syntax of a placement key for the Plugins API is page-zone
. Pages and Zones are described in further detail below:
Desktop Pages
Smokeball desktop supports two pages where plugins can be placed:
-
Main Window, denoted by
Window
key -
Matter Window, denoted by
MatterWindow
key
Desktop Zones
The zones are unique places on a page where content can appear. For instance, a page can have both button zones and tab zones and the placement key determines where the Plugin appears in the page.
Smokeball determines how a set of plugins appear in the zone, generally at the end of the existing list. For ribbon buttons, they will be placed into their own ribbon group at the end of the zone.
Below are the supported Matter window zones:
MatterWindow-MatterDetailsRibbon
- Places a Tab in Matter page
MatterWindow-MatterDetailsRibbonTab
- Places a Button in the ‘Matter’ Tab of Matter page
Below are the supported Main window zones:
Window-SmokeballRibbonTab
- Places a Button in the ‘Smokeball’ Tab of Main page
Window-MainTabs
- Places a navigation tab inside the Smokeball left-side tabs
Window-MainRibbon
- Places a tab in the main window ribbon
SDK Support
All browsers opened by Plugins support integration with the Smokeball SDK as long as the internal browser is used, when attributes.page.useDefaultBrowser
is true
.
See SDK Documentation for usage information.
Creating a Plugin
Currently, Plugins can only be created and maintained by select partners. Smokeball is currently controlling the process of which accounts can access plugins.
Subscribing Smokeball Firms to Plugins
Smokeball firms are subscribed to plugins through the PluginSubscriptions resource. Partners authorized through the Client Credentials Grant can then subscribe accounts to their plugins. Available plugins are scoped to API client ids, meaning that you can only subscribe to plugins that were created using the same API client id.
Smokeball firms that have subscribed to plugins will always receive the latest version of your plugins, and would be automatically updated to the latest changes.
Loading your Plugin
When a Plugin is accessed in Smokeball, a request is dynamically made to the endpoint defined in the Plugins requestEndpointUrl
field. The url returned by this request is then loaded into Smokeball.
For more detailed usage documentation, please refer to the information below.
Requesting your URL
Plugins support two fields which help load your view into Smokeball.
Field | Description |
---|---|
requestEndpointUrl | Used to request a URL from your backend. |
key | Used to calculate a signature which must be used by your backend to verify that the request is from Smokeball. |
When a Plugin view is loaded, a POST
request is made to the supplied requestEndpointUrl
url with a payload similar to below:
Your endpoint should use this information to generate a URL to be viewed by the user. This url should be returned in the JSON response like so:
It is critical that the above structure is used in the response payload. If an incorrect format is used or the URL is missing, the user will not be able to use your app.
Request Validation
It is important that you verify that the URL request is from Smokeball to prevent malicious usage of your endpoint.
If you supplied a Key
property when creating a Plugin, a header named Signature
will be included when Smokeball calls your requestEndpointUrl
. The signature is a HMAC SHA256 hash that was created with the key that you provided. You can perform the same hashing process on your processing side to verify that the request came from Smokeball.
Computing the HMAC
The Signature
hash is calculated using these three bits of information:
- The
Timestamp
header which is the ticks representation of the UTC datetime (.Net format) the request was sent - The
RequestId
header - Your
ClientId
that you use to authenticate with the API
These three parameters need to be concatenated into a single string, seperated by a |
and can then be used to create the hash.
This produces the hash string 58817681863148b0e624c00f3094f99e1af31cd7b99a3c2e0655d64a2764d650
Guarding against replay attacks
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks Smokeball provides a Timestamp
header which is the ticks representation (.NET format) of when the request was sent. It is also part of the verification signature so an attacker can not change the timestamp without invalidating the signature.
If the signature is valid but the timestamp is too old, you may choose to reject the request.
Limitations
API
Not all Plugin API fields are currently in use. For now, please assume these fields are not in use by Smokeball and may be supported in future:
endpoint
field has been deprecated. UseRequestEndpointUrl
for all new plugins. You can migrate an existing app to the new field by updating theendpoint
field to null, and setRequestEndpointUrl
to your new url.availability
- availability settings are currently not supported.
Web App
Plugins are currently not supported in the Smokeball web app.