Guides

Plug-in Adapter Library

Suggest Edits

Haiilo Home provides a quick and easy way to get started with a front end communication. We have published an npm library that helps you setup your plug-in. It offers

Installation

Installing with the npm package manager:

npm install @coyoapp/plugin-adapter --save

Installing with the Yarn package manager:

yarn add @coyoapp/plugin-adapter

Usage

To use the Haiilo Home plug-in adapter you need to create a new instance of the PluginAdapter class. The adapter requires your plug-in's source ID, which can be found as src query parameter in the invocation URL. If it is not explicitly provided, the adapter will try to look for it automatically in the URL. Ideally, you create a new instance once for the entire lifetime of your plug-in.

import {PluginAdapter} from '@coyoapp/plugin-adapter';

const params = new URL(window.location.href).searchParams;
const adapter = new PluginAdapter(params.get('src'));

The adapter offers a variety of possibilities to interact with the Haiilo Home front end, such as plug-in initialization, plug-in configuration and automatic height adjustments. Most of these use cases are described in more detail in their respective guides of this documentation.

📘

The plug-in's source ID (src) is an identifier that is unique for every plug-in instance. It can be used to reference the plug-in over the entire lifespan of the instantiated plug-in. It is composed of the tenant ID and the ID of the plug-in.

🚧

There is a caveat when developing plug-ins using localhost or any other insecure URL without TLS. The browser will not provide the javascript crypto library to insecure content that is not protected by TLS aka HTTP, therefore the Plug-In Adapter library will not be able to validate a token but display an error message instead.

Functionality

Haiilo Home's plug-in library not only provides an easy interface to establish a working communication to the Haiilo Home front end, it also handles a lot of internal validations. Always keep in mind that you will have to implement this logic on your own if you decide to not use the library and still need a safe and secure connection. Furthermore, the library allows us to change details in the communication protocol without you having to change your implementation.

Here is a short overview of the features covered by the Haiilo Home plug-in adapter:

  • adhering to the message protocol
  • decoding the JWT claims
  • verifying that incoming tokens are not expired
  • validating all signed tokens using the correct certificates for the corresponding environment
  • adding a nonce to every message
  • match incoming responses to the request that initiated the conversation
  • wrapping every message in a time out
  • removing event listeners on the window object to avoid memory leaks
  • handling errors during the validation and verification steps

Updated over 2 years ago