Plug-in manifest

The plug-in manifest is a JSON file that contains all relevant information to install a plug-in in a Haiilo Home environment. Each plug-in must therefore necessarily have at least one plug-in manifest. Although Haiilo Home stores a local copy of the manifest in the database when a plug-in is installed, it makes sense to host and publish the manifest under the same domain as the plug-in.

The structure of the manifest is defined in an accompanying JSON schema. You can download the latest schema version 2.5.0 here. With this schema you can test your own plug-in manifest using a tool like the JSON Schema Tool. While the final definitions should always be looked up in the latest JSON schema file, here is a list of the most important fields of a plug-in manifest:

Attribute	Type	Description
manifestVersion	semantic version e.g. 2.3.0	The version that the plug-in manifest is validated against.
pluginVersion	semantic version e.g. 1.0.0	The plug-in version that follows the semantic versioning spec.
coyoVersion	semantic version e.g. 37.0.0	The minimum required Haiilo Home version this plug-in needs to operate properly.
name	translation map see Internationalization	The plug-in's name. Should be short.
description	translation map see Internationalization	The plug-in's description. Should describe in detail what the plug-in does.
thumbnail	URL e.g. /plugin/thumb.png	Absolute or relative (to this manifest) URL to a thumbnail for this plug-in.
context	string[] e.g. [“userName”]	Additional context properties that should be included in the plug-in initialization request.
config	configuration fields see Configuration	A list of global configuration fields.
lifecycle	lifecycle objects see Lifecycle events	Life cycle events the plug-in wants to receive.
apiAccess	Haiilo API access request data see Haiilo API access	If the plug-in requests access to the Haiilo API for backend-to-backend communication
entryPoints	entry point definitions see Entry points	The list of entry points the plug-in offers.

Schema changelog with download links

Version	Changelog
2.5.0	- added apiAccess for backend-to-backend communication
2.4.0	- added entryPoints/permissionsPolicy 'fullscreen'
2.3.0	- added custom configuration for entry points (entryPoints/configUrl) - added entryPoints/configHeight
2.2.0	- added entryPoints/permissionsPolicy
2.1.0	- added thumbnail
2.0.0	Initial version 2

Entry points

To cater for different views of a single plug-in, Haiilo Home offers the concept of entry points. Each entry point belongs to the overarching plug-in and shares the same data but defines its own URL endpoint. While the plug-in itself is configured in Haiilo Home’s administration area, the specific entry point to render can be configured on each individual plug-in instance in Haiilo Home. If your plug-in defines only one entry point Haiilo Home will automatically select and render it.

To get a better idea of entry points, let's take the following example. You develop a plug-in to display the current menu of your company canteen. While this is a single plug-in you might want to define three different entry points for it (each of them with an own URL and interface):

the daily menu,
a weekly overview
and the current special offers

The details of each entry point are defined in the plug-in manifest. Here is again a list of the most important fields of a plug-in manifest's entry point definition:

Attribute	Type	Description
entryPoints.id	UUID e.g. a6725e06-30f2-46c2-a1da-fa7a52a0e454	The entry point's unique identifier.
entryPoints.name	translation map see Internationalization	The entry point's name. Should be short.
entryPoints.description	translation map see Internationalization	The entry point's description. Should describe in detail what the entry point does.
entryPoints.url	URL e.g. /plugin/ep1	Absolute or relative (to this manifest) invocation URL.
entryPoints.origin	URL[] see Secure communication	Overrides the events' target origins that are accepted by Haiilo Home.
entryPoints.height	height or ratio see Dimensions and scrolling	The entry point's initial height or aspect ratio as a number in pixels or a string of the form {width}:{height}.
entryPoints.config	configuration fields see Configuration	A set of local configuration fields for this entry point.
entryPoints.configUrl	URL e.g. /plugin/ep1/edit	Absolute or relative (to this manifest) invocation URL for the configuration.
entryPoints.configHeight	height or ratio see Dimensions and scrolling	The configuration's initial height or aspect ratio as a number in pixels or a string of the form {width}:{height}.
entryPoints.permissionsPolicy	string[] e.g. [“camera", "geolocation", "fullscreen"]	Request allowance for permissions policies.

Internationalization

Since Haiilo Home can be used in different languages, plug-ins should also react to the language settings of the user. This concerns both the information in the plug-in manifest and the presentation of the plug-in itself.

The description texts of the plug-in manifest are used in the administration area and in the plug-in configuration dialog. Thus, every text in the manifest is not defined as a simple string but as a JSON object mapping language identifiers to their respective translations. Haiilo Home automatically takes care of selecting the correct language for every user based on the users' settings.

{
  "pluginVersion": "1.0.0",
  "name": {
    "en": "Hello world",
    "de": "Hallo Welt"
  },
  "description": {
    "en": "My first plug-in.",
    "de": "Mein erstes Plug-In."
  },
  …
}

Thumbnail

Plug-ins can set a thumbnail image in their manifest. The thumbnail will be shown in the widget chooser when instanciating a new plug-in. If no thumbnail is set, a generic plug-in icon will be shown instead.

The thumbnail should be in JPG of PNG format and should be at least 64px in width and height.