Guides

Personalise your plug-in with contextual data

Suggest Edits

Requesting contextual data from Haiilo Home

Displaying just “Hello Haiilo Home” isn’t that fancy! Wouldn’t it be cooler to greet the user by his/her name instead? In order to do this we need to request this data first, because Haiilo Home will not just transmit this data automatically. Any user information is GDPR relevant data and has to be treated with care and under secure conditions. All contextual information a plug-in wants to access thus has to be known by the Haiilo Home system beforehand.

Consult the current manifest schema for a comprehensive list of available context information.

Let us enhance our manifest so that the user’s name can be obtained. We then personalise our first entry point. We will also update our plug-in’s version.

📥
Request contextual data
Open Recipe

Our manifest for might look like this:

{
  "manifestVersion": "2.0.0",
  "pluginVersion": "0.2.0",
  "name": {
    "en": "Demo Plugin - Step 2",
    "de": "Demo Plugin - Step 2"
  },
  "description": {
    "en": "A simple demo plug-in",
    "de": "Ein einfaches Beispiel-Plug-in"
  },
  "context": ["userName"],
  "entryPoints": [
    {
      "id": "510e9e0c-e3b8-44a8-8db1-5185d3d844ce",
      "name": {
        "en": "Personal View 1",
        "de": "Persönliche Ansicht 1"
      },
      "description": {
        "en": "Greeting the user",
        "de": "Persönlicher Gruß"
      },
      "url": "/ep1.html"
    },
    {
      "id": "4f434887-9289-48ac-986d-4ff1f37ab618",
      "name": {
        "en": "View 2",
        "de": "Ansicht 2"
      },
      "description": {
        "en": "Displaying view 2",
        "de": "Ansicht 2 wird angezeigt"
      },
      "url": "/ep2.html"
    }
  ]
}

Accessing contextual data from Haiilo Home

With a frontend-only plug-in as ours we can use the window.postMessage() communication between the plug-in's iFrame and the Haiilo Home parent frame. For the concepts behind it and how Haiilo Home ensures a secure passing of data please refer to our guides on front end communication.

Luckily we do not have to implement the message exchange between frames nor the validation of the sent data ourselves, but can use Haiilo Home's plug-in adapter to initialise the plug-in communication and retrieve the contextual information defined in the manifest above.

The plug-in adapter does everything to enable secure communication with Haiilo Home environments at *.coyocloud.com

📘

Setting up javascript development in the demo project

Our demo project uses a very basic typescript and webpack setup to bundle all frontend code together and get it deployed to Heroku. If you are following along the demo project you will have to set up the build task for our javascript code.

Follow this guide.

If you are using your own setup you can directly proceed below.

Initialising frontend communication with the Plug-in Adapter

Install the Plug-in Adapter.

npm install @coyoapp/plugin-adapter --save

All our typescript code will reside in /src.
Let's keep all the plug-in functionality in an extra DemoPlugin class at /src/app/plugin.ts and fill it with life.

👋
Read initialisation information with the plug-in adapter
Open Recipe

Our final DemoPlugin code looks like this:

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

export class DemoPlugin {
    constructor() {
        new PluginAdapter().init().then(data => {
            const name = data['ctx.userName'];
            this.changeName(name);
        });
    }

    private changeName(userName: string) {
        const nameElem = document.getElementById('userName')!;
        nameElem.innerText = userName;
    }
}

Now we only have to use it in our index.ts

import {DemoPlugin} from './app/plugin';

(function () {
    new DemoPlugin();
})();

And, of course, we have to use our bundled script in the html page that will greet the user.
Don't forget to provide the html element that should display the user's name here, too.

<!DOCTYPE html>
<head>
    <meta charset="utf-8">
    <title>Haiilo Home Demo Plug-in</title>
    <meta content="A simple demo plug-in" name="description">
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source Sans Pro">
    <link rel="stylesheet" type="text/css" href="styles.css">
</head>
<html>
<body class="bright">
<h1>Hello Haiilo Home - Entry Point 1</h1>
<p>Welcome <span id="userName"></span> :)</p>
<p>This is View 1.</p>
<script src="main.js"></script>
</body>
</html>

Now commit, deploy and install the new manifest into your Haiilo Home.
Does your plug-in say hello to you now? It should :)

👍

Demo project

The result of this step can be seen at branch 2-frontend-data of our demo project

📘

Taking it from here

In the demo project we are showing the simplest possible way of accessing and displaying information.
In real life you would additionally have to deal e.g. with error handling, and with the display of a loading state while the PluginAdapter's promise has not yet returned.

Updated over 2 years ago

What’s Next