Initialization

The first thing you have to do to get your plug-in up and running is to initialize. This will let COYO know that your plug-in has been loaded and that it is ready to do whatever it is supposed to do. This will also provide your plug-in with all the contextual data and configuration values it needs to run properly.

Initialization via library

Fortunately, the initialization of your plug-in is extremely easy using the COYO plug-in library. After you have instantiated the PluginAdapter just call its init() method. You can optionally provide a timeout for the request. The default timeout is set to be 60 seconds. The method returns a Promise object that eventually resolves to COYO's initialization response. Besides some required fields of the JWT, it contains the contextual data and configuration values for your plug-in.

The library already validates and decodes the JWT for you. You can find an example response of an initialization message below:

{
  // the COYO environment that issued the JWT
  iss: "https://example.coyocloud.com",
  // the time at which the JWT was issued
  iat: 1607082866,
  // the expiration time after which the JWT MUST NOT be accepted
  exp: 1607082926,
  // the subject of the message
  sub: "init",
  // the random nonce sent via the request
  jti: "hSPryn8doMoi6Fjn",
  // the ID of the current tenant
  ctx.tenantId: "5aaa4d6d-cf92-4385-a49e-bc620c2de7e1",
  // the ID of the current user
  ctx.userId: "e47c39ff-8384-45d5-b998-a801930e936d",
  // additional context data requested via the manifest
  ctx.userName: "Robert Lang",
  // custom configuration text field
  cfg.text: "Hello World",
  // custom configuration number field
  cfg.number: 5,
  // the current edit state in COYO
  stt.edit: false
}

Manual initialization

To initialize your plug-in without the plug-in adapter is risky. After all, the adapter not only takes care of the correct message format but also validates the response and checks the message for the correct signature using browser native crypto technology. Furthermore, it establishes measures to prevent replay attacks. If you still feel the need to manually initialize your plug-in you need to send a well formatted message to COYO via the window.postMessage() API. Make sure to also setup the event listener for the response before you send out the actual request. Here is an example implementation that gives you a basic idea but should not be used in production:

const iss = new URL(window.location.href).searchParams.get('src');
const sub = 'init';
const jti = generateRandomStr();

window.addEventListener('message', (event) => {
   // identify, validate and process initialization resposne
});

parent.postMessage({ iss, sub, jti}, '*');

Did this page help you?