Plug-in manifest

The plug-in manifest is a JSON file that contains all relevant information to install a plug-in in a COYO environment. Each plug-in must therefore necessarily have at least one plug-in manifest. Although COYO 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 find all schemas at https://download.coyoapp.com/release/plugins and might want to 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 COYO 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.

entryPoints

entry point definitions
see Entry points

The list of entry points the plug-in offers.

Entry points

To cater for different views of a single plug-in, COYO 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 COYO’s administration area, the specific entry point to render can be configured on each individual plug-in instance in COYO. If your plug-in defines only one entry point COYO 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 COYO.

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"]

Request allowance for permissions policies.

Internationalization

Since COYO 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. COYO 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.


Did this page help you?