Getting started with web components

inmydata provides a suite of components, making it simple to embed visualisations & dashboards, and provide AI conversational ability to your application.

Our components are simple HTML elements, based on the universally supported Web Components standard.  They are vanilla JavaScript with no dependencies, and can be used in any web page, with or without a framework.  Regardless of whether you use React, Angular, jQuery, any other framework, or no framework at all, you can easily embed elements of inmydata to your application. 

Including the components in your application

To use our components in your web application, add one line to your html:

<script src="https://inmydata.com/sdk/inmydata-components-all.min.js"/>

Configuring Components

The components are configured by setting attributes on the HTML element.  e.g.:

<inmydata-copilot tenant="example" subject="Store Sales"/>

All of our components have the following common attributes (optional unless otherwise stated):

• tenant (required): Your tenancy name, as is used in the URL when you navigate to inmydata (e.g. the 'example' in example.inmydata.com)
• width: any valid CSS expression of width.  Defaults to "100%".
• height: any valid CSS expression of height.  Defaults to "100%".
• render: if set to 'false', delays rendering of the component until set to true.
• suppress-drilldown: if 'true', do not show a drilldown inside the component.  Used if you wish to handle the drilldown event in your own way.
• show-login: set to false to hide the login prompt inside this component (renders as blank until login is completed in another component). Defaults to true.
• domain - May be necessary if you are a customer of one of our partners (e.g. MultiAnalytics, where this would be set to "multianalytics.net")

Attributes can be set declaratively on the HTML element like so:

<inmydata-copilot tenant="example" subject="Store Sales" height="500px" width="400px"/>

Attributes can also be set programatically on the HTML Element.  Give the element an id, reference it in your code, and set the attributes via JS.  The component is refreshed whenever an attribute changes:

<inmydata-copilot id="aichat" tenant="example">

<script>
    document.getElementById('aichat').setAttribute('subject', 'Store Sales');
</script>

You may also add the components to your page programmatically, using document.createElement, for example:

let copilot = document.createElement('inmydata-copilot');

copilot.setAttribute('tenant','example');

document.body.appendChild(copilot);

Security & Authentication

In order to embed inmydata in your web application, you must specify the domain of the host application.  In the inmydata Settings, in the General section, add the domain (or domains, separated by spaces) in the box under "Allow embedding at these domains", e.g. myapp.mydomain.com).  You may enter more than one domain here, which will permit the embedded content to be visible when embedded at all specified domains, however, event messages can only be sent to one domain, being the first in the list.

inmydata offers three types of provider of authentication - our own provider hosted at auth.inmydata.com, major third-party providers such as Google and Microsoft, or another provider that it is visible to the public and OAuth2 compatible.  

Single Sign-On

inmydata supports Single Sign-On (SSO) via the industry-standard OAuth2 and OIDC protocols.  If your application is secured using Google or Microsoft logins, SSO is easy to achieve, just by selecting "Google" or "Microsoft" as your inmydata login provider.

If your app is also secured by any other OAuth2 or OIDC authority, and is visible outside of your company's network, then inmydata may be configured to use the same authority, allowing seamless integration between the imydata components and your application.  Select "Custom" as your login provider in the inmydata Settings and enter details as necessary (OIDC requires the fewest details and is recommended if available).  For this to succeed, you will need to create an ID (or key) in your authentication authority, for the inmydata application.

inmydata Login

If your application does not use any form of OAuth2 or OIDC provider, then you may log in to inmydata via our in-built authentication mechanism.  Without Single Sign-On, a login prompt will be shown inside the components (if the user is not already logged in to inmydata).  

If using more than one component on the same page, multiple login prompts will be shown.  It is recommended to show one component initially, and the others should wait until login is complete in the first component.  This can be achieved with the 'show-login' parameter - set this to "false" to show a placeholder message instead of the login screen, and when login completes in another component, these components will refresh.  Apart from being confusing to the user, multiple login prompts in the same screen could potentially cause errors as they share authentication cookies and other data.  All components emit the event "inmydata.loggedin" when login succeeds.

The inmydata login screen is protected so that it can only be embedded at permitted domains, preventing malicious sites from embedding inmydata and potentially stealing sensitive data.  In the inmydata Settings, under General, set the domain of your embedding app in the box labelled "Allow embedding at these domains".  At a bare minimum you can specifyonly the domain name itself, but it is recommended to include the scheme, e.g. https://mydomain.com.  Wildcards for subdomains are permitted, e.g. https://*.mydomain.com.  This setting is also used to specify where the component event messages may be sent to; see 'Events' below.

Events

All inmydata components emit events, named in the format "inmydata.<event name>".  You can listen to these events in JavaScript code using addEventListener, e.g.:

<inmydata-inisghts id="insights"/>

<script>
   let component = document.getElementById('insights');
    component.addEventListener('inmydata.loggedin', () => { console.log('logged in'); });
</script>

For messages to be received in your embedding application, you must add the application's domain in the inmydata Settings.  This is to ensure the messages are sent to this domain only, remaining secret and secure.  In the General tab, add the domain of your application as the first domain in the box under "Allow embedding at these domains".  Events can only be sent to one domain. Domains must be specified exactly with scheme, host name and optional port (that is, https://myapp.mydomain.com, not mydomain.com or https://*.mydomain.com).  Warning: a wildcard (*) is permissable here, but unsafe as this exposes the event data to mailicious sites.

If you are experiencing issues with events being received by your embedding app, you may disable the protection on the domain that it is sent to.  To do so, set the toggle "Do not restrict domains that embedded messages can be sent to (unsafe)". As the label suggests, this is insecure and not recommended, but useful whilst troubleshooting or if your host application is complex.

Events are sent with data in the format "<event name>:<arguments>", where arguments is a JSON object with at least two properties, EventName (e.g. inmydata.loggedIn) and User (the id of the currently signed-in user).  Specific events will have further properties relevant to that event - please see the pages for each component for more details.

inmydata.loggedin is emitted by all components.  The event data will look similar to:

inmydata.loggedin:{ "EventName": "inmydata.loggedin", "User": "mo@example.com" }