@adobe/griffon-plugin-bridge
v0.4.0
Published
Communication API between Project Griffon and plugins.
Downloads
14
Maintainers
Keywords
Readme
Griffon Plugin Bridge
Usage
The Project Griffon UI consumes the bridge via the @adobe/griffon-plugin-bridge
npm package while plugin views consume the bridge by loading a CDN-hosted script
The communication layer consists three different pieces:
Parent (lib/parent.js): This is the portion of the communication layer that Project Griffon UI uses by importing it directly:
import { loadIframe } from '@adobe/griffon-plugin-bridge';
The arguments, return value, and behavior of
loadIframe
can be found within the code documentation in parent.js.Child (dist/pluginBridge.min.js): This is the portion of the communication layer that plugin views use by including the script:
<script src="https://ui.griffon.adobe.com/pluginBridge/pluginBridge.min.js"></script>
API
Griffon UI Methods
The bridge provides a plugin (child) to call methods into the Griffon UI (parent).
annotateEvent
Allows a plugin to annotate an event. Annotations are additional data to events that need to be persisted - like third-party API results. The annotation is stored as an object with two properties: type
and payload
. The plugin UUID is used as the type and the data provided in the annotateEvent call is stored in the payload property. An event will have an array of annotations.
annotateSession
Allows a plugin to annotate a session.
flushConnection
Allows a plugin to rerun a connector. Flush connection takes a namespace
and context
parameter. The exact connection that fully matches both the namespace
and context
will be cleared, causing the downstream Connector to reload the data.
deletePlugin
Allows a plugin to delete a validation or view plugin that is owned by the user's organization. The payload needs to be the uuid of a plugin. This operation is currently restricted to Adobe first-party plugins only.
navigateTo
Allows a plugin to navigate to another view for deep linking.
selectEvents
Allows a plugin to toggle selected events to pass to other plugins via receiveSelectedEvents
. The payload needs to be an array of event uuids.
sendCommand
Sends a command to the SDK via the Griffon server. The format should be:
{
type: 'command to trigger',
payload: { ... }
}
where the payload is an object containing data for the SDK to process when running the command.
uploadPlugin
Allows a plugin to upload a validation or view plugin. The payload to upload a plugin needs to look like the following:
{
uuid: '1234567890', // optional
file: Blob
}
If a uuid is not provided, then a new plugin is created. Otherwise, the plugin is updated.
Plugin Methods
The bridge provides a plugin (child) the ability to implement the following APIs by calling window.pluginBridge.register
and passing in an object
window.pluginBridge.register({
init: (configuration) => {
// do something
},
navigateTo: (path) => {
// do something based on the current path
},
receiveEvents: (events) => {
// array of session events
},
receivePlugins: (events) => {
// array of view plugins
},
receiveSelectedEvents: (events) => {
// subset of session events
},
receiveSession: (session) => {
// session information including session annotations
},
receiveSettings: (settings) => {
// new settings
},
receiveValidation: (results) => {
// validation results from the validation plugins
}
});
init
The parent (Project Griffon UI) calls init once the plugin is registered. Here, Project Griffon UI will pass in any applicable configuration settings.
Example Payload
{
imsAccessToken: 'LongEncodedTokenGoesHere',
imsOrg: 'testOrg@AdobeOrg',
environment: 'prod',
settings: {
global: {
theme: 'light',
locale: 'en-US'
}
}
Configiration Values
- imsAccessToken: token string used to make calls to Adobe services
- imsOrg: string that identifies the user's active org id
- environment: environment that the plugin is running against. Possible values are
local
/dev
/qa
/stage
/prod
- settings: object contain the following settings. Settings can be updated using
receiveSettings
.
Settings
Settings determine how the plugin should look and feel. These settings are scoped to a namespace. The global
namespace contains the following:
- theme: (light/dark) specifies the theme the parent's UI is using
- locale: (en-US, etc) specifies which localization to use in the UI
You may also provide plugin specific settings using your plugins specific namespace.
receiveSettings
Passes a new set of settings data. The structure matches the settings
field from the init
command above.
Example Payload
{ global: { theme: 'light', locale: 'en-US' }, 'aep-places': { defaultZoom: 7 } }
Supported Values
- theme: (light/dark) specifies the theme the parent's UI is using
- locale: (en-US, etc) specifies which localization to use in the UI
- showTimeline: (true/false) many Griffon Plugins show a timeline at the bottom by default. Setting this to
false
will hide that timeline.
navigateTo
The parent (Project Griffon UI) calls navigateTo whenever the URL is updated. The intent here is to provide deep linking capabilities as well as an opportunity for plugins to be good citizens and limit resources when not visible.
receiveConnections
Project Griffon UI sends an array of connections. A connection will look like:
{
namespace, // the namespace of the connector
context, // object containing parameters needed to run the connector
loaded, // has the connection data finished loading
loading, // is the connection currently loading
error, // error object resulting from the query (if applicable)
data // the resulting data from the api call
}
receiveEvents
Currently, Project Griffon UI will send all events via this method on all registered plugins in the following scenarios:
- Upon initial load of the plugin
- Any time a new event is received while the session with the client (Mobile SDK) is active
- Any time an event is annotated by a plugin
receivePlugins
Project Griffon UI calls receivePlugins when the visibility of a view is changed or when a view is uploaded or deleted. The payload will contain an array of plugin object metadata.
receiveSelectedEvents
Project Griffon UI sends an array of event uuids selected from the result of a plugin calling selectEvents
on the bridge.
receiveValidation
The parent (Project Griffon UI) calls receiveValidation when the validation plugins have been executed. The payload will contain an object of results each keyed by the namespace of the plugin. Each result will have a payload similar to the following:
{
"category": "Adobe Analytics"
"description": "Validates each analytics event has post-processed data."
"displayName": "Adobe Analytics Post-Processed Data"
"level": "off"
"namespace": "adobe-analytics-post-processed"
"results": {
"message": "Valid! All Analytics events have post-processed data!",
"events": [],
"result": "matched"
}
}
Scripts
To run tests, run the following command:
npm run test:browsers
To run a ci test:
npm run test
To create a build, run the following command:
npm run build
Contributing
Contributions are welcomed! Read the Contributing Guide for more information.
Licensing
This project is licensed under the Apache V2 License. See LICENSE for more information.