Embed Components Using JavaScript and Trusted Access

Describes the JavaScript EventListeners and methods you can use to embed a dashboard in your application.

You can embed a Self-Service Analytics component using JavaScript.

The following components can be embedded:

• dashboards, lite dashboards
• visual authoring experience
• source editor

When components are embedded, the way in which users can interact with them is determined by settings established in their user account. See Embedded Self-Service Analytics Component Controls.

Complete examples of JavaScript code that initializes and authorizes the EmbedManager class are provided in Embedded JavaScript Examples.

Follow these steps:

• Step 1. Verify the Prerequisites Have Been Met
• Step 2. Make the Embed Manager Available to Your Application
• Step 3. Initialize and Authorize the Embed Manager
• Step 4. Create and Render a Component in Your Application

Step 1. Verify the Prerequisites Have Been Met

Verify that the embedded dashboard prerequisites have been met. See Embedded Component Prerequisites.

Step 2. Make the Embed Manager Available to Your Application

To make the Self-Service Analytics’s embed manager available to your application, include this script in your HTML:

<script data-name="composer-embed-manager" src="https://<sampleurl>/embed/embed.js"></script>

where <samplecomposerurl> is the URL of your Self-Service Analytics instance.

After this script is run, the initComposerEmbedManager function is available globally in window.

Step 3. Initialize and Authorize the Embed Manager

Use the window.initComposerEmbedManager function to initialize and authorize the embed manager. This can be done using the following configuration properties. Note that the token you supply must be obtained beforehand using the Trusted Access API, usually in backend code that supports your HTML.

The getToken property is a method that returns a token from Trusted Access prior to token expiration. Here is an example:

const getEmbedManagerPromise =
window.initComposerEmbedManager({
       getToken: function () {
           // transform for the embed syntax
           return getToken().then((result) => { // getToken function uses the Trusted Access API
               return {
                   access_token: result.token,
                   expires_in: result.expiresIn,
               };
            });
        },
});

After the initComposerEmbedManager function is called, it returns a promise that resolves an instance of the EmbedManager class. The objects, methods, properties, and embedded events provided with the EmbedManager class can be used in your HTML.

Step 4. Create and Render a Component in Your Application

After the EmbedManager class has been initialized and authorized, you can use its methods to embed a Self-Service Analytics component in your application and set various properties for that component. In addition, you can use embedded events to control component behavior when specific events occur.

Other EmbedManager methods can be used to modify, refresh, and remove components in your application.

Complete descriptions of the supported EmbedManager methods and properties are provided in EmbedManager Methods, Embedded Dashboard Properties and Objects, and Embedded Visual Authoring Properties and Objects. Supported embedded events are described in Embedded Events.

The following simple example creates and renders an embedded dashboard:

getEmbedManagerPromise.then((embedManager) => {
     embedManager.createComponent('dashboard',
          {
               dashboardId: <id>, // dashboard id
               <property>,... // set of properties
          }
     ).then(dashboard => dashboard.render(
          htmlElement, // htmlElement
          {width: '100%', height: '100%'}
     ))
});

// Example with async await
async function createComponent() {
     const embedManager = await getEmbedManagerPromise;
     const newDashboard = await embedManager.createComponent('dashboard',
          {
               dashboardId: <id>, // dashboard id
               <property>,... // set of properties
          });
     newDashboard.render(
          htmlElement, // htmlElement or selector
          {width: '100%', height: '100%'}
     ));
}

The following simple example creates and renders an embedded lite dashboard:

embedManager.createComponent('lite-dashboard', const componentConfig = { "dashboardId": "<dashboard-ID>", "componentInstanceId":"<component-instance-ID>", "type":"lite-dashboard", "application":{ "banner":false, "logo":true }, "interactivityProfileName":"lite", "theme":"modern", "editor":{ "placement": "docRight" }, "header": { "title": "My Lite Dashboard" "showActions": false, "showTitle": false, "visible": false }, "availableVisTypes" : [`HISTOGRAM`,`BOX_PLOT`,`HEATMAP`] } );

Optionally, return dashboards to your users that match a filter string you have defined (partial example):

// Fetch filtered dashboard list
const response = await fetch(
  `${composerUrl}/api/dashboards?filter=tags NOT IN ["internal"]`,
  {headers}
);

Supported operators include IN, NOT, !=, <>, AND, and OR.

Embedded JavaScript Examples

This section provides JavaScript examples that use methods, properties, and embedded events of the EmbedManager class to embed, refresh, reauthenticate, or remove Self-Service Analytics components from your application.

Embedded Dashboard JavaScript Example

The following JavaScript example uses methods, properties, and embedded events of the EmbedManager class to embed, refresh, reauthenticate, and remove a dashboard.

• The createOrGetEmbedManager asynchronous function provides an initial access token using Trusted Access.
• The addDashboard asynchronous function embeds a dashboard in the application. It uses the dashboard ID as input so it knows which dashboard to embed. It also specifies some properties for the dashboard.
• The clearDashboard asynchronous function removes a dashboard from the application. It uses the dashboard ID as input so it knows which dashboard to remove.
• The refreshDashboard asynchronous function refreshes the authorization token for the embedded dashboard using Trusted Access.
• The application asynchronous function at the end combines the use of all the previous functions and uses embedded events to trigger some of them.

The Self-Service Analytics EmbedManager class must be made available to your HTML application prior to using this sample in your application. See Embed Components Using JavaScript and Trusted Access.

Self-Service Analytics provides a componentInstanceId provides a as part of event details for dashboard, source, and visual events.

async function createOrGetEmbedManager(<token>) {
   return window.initComposerEmbedManager({ //embed manager is a singleton and will be created only on the first call
      getToken: function () {
          // transform for the embed syntax
          return getToken().then((result) => {
              return {
                  "access_token": "result.token",
                  "expires_in": "result.expiresIn",
              };
          });
      }
   });
}

async function addDashboard(<id>) { // id of the composer dashboard
   const embedManager = await createOrGetEmbedManager();

   const dashboard = await embedManager.createComponent('dashboard', {
      "dashboardId": "<id>", // required
      "theme": "composer",
      "interactivityProfileName": "interactive",
      interactivityOverrides {
        "settings":{
           "CHANGE_LAYOUT": true,
        },
        "visualSettings":{
           "FILTER": false,
        },
     },
     "editor": {
         "placement": "dockRight" // use eve sidepanel
      },
      "header": {
         "visible": true,
         "showTitle": true,
         "showActions": false, // will hide actions bar
         "title": "Static custom title"
      }
   });

   dashboard.render(document.querySelector('#dashboard'), { width: '800px', height: '400px' });
   return dashboard;
}

async function clearDashboard(<id>) {
   const embedManager = await createOrGetEmbedManager();
   embedManager.removeComponent(<id>);
}

async function refreshDashboard(<newToken>) {
   const embedManager = await createOrGetEmbedManager();
   embedManager.updateToken(<newToken>).then(() => {
      embedManager.refresh();
   });
}

(async function application() {
   const token = await getComposerToken(); // some function of the 3rd party app that calls application API and return composer token retrieved via TA
   const dashboards = await getUserDashboard(); // some function of the 3rd party app that retrieved dashboards for the user
   createOrGetEmbedManager(token);

   // if token is expired composer will raise next event
   document.addEventListener('composer-unauthorized', async () => {
      const token = await getComposerToken();
      const embedManager = createOrGetEmbedManager();
      refreshDashboard(token);
   })
   // render first dashboard in the list
   const embeddedDashboard = addDashboard(dashboards[0].id);

   // embedded component supports an ability to subscribe on the component specific events
   embeddedDashboard.addEventListener('composer-dashboard-ready', () => {
      // triggered when all charts are rendered. put custom logic here.
   })
   document.querySelector('#clear-button').addEventListener('click', () => {
      clearDashboard(embeddedDashboard.componentInstanceId); // clears embedded dashboard when clicked on some button in the application
   })

})()

Embedded Visual Authoring JavaScript Example

The following JavaScript example uses methods, properties, and embedded events of the EmbedManager class to embed a visual authoring instance.

The Self-Service Analytics EmbedManager class must be made available to your HTML application prior to using this sample in your application. See Embed Components Using JavaScript and Trusted Access.

Self-Service Analytics provides a componentInstanceId provides a as part of event details for dashboard, source, and visual events.

// NOTE: This example assumes that the EmbedManager has already been initialized
const visualBuilder = await embedManager.createComponent('visual-builder', {
    visualId: <id>, // ID of existing visual
    source: {
        "visualId": "<id>", // ID of visual template, used for creating a new visual, do not pass it with visualId
    },
// If neither visualId is passed (visualId or source.visualId) an empty visual builder will be opened)
    "theme": "composer",
    "header": {
        "visible": true,
        "showTitle": true,
        "showActions": false, // hides the visual actions bar
        "title": "Static custom title"
    },
    "breadcrumbs": { // optional configuration of the breadcrumbs
        "title": "Visuals",
        "onClick": () => {console.log('clicked')},
        "href": "http://www.google.com",
        "target": "_blank"
    },
    interactivityOverrides: { // optional overrides for visual interactivity
        "visualSettings": {
            "FILTER": false,
            "GROUPING": true,
            "METRICS": false, // accept both boolean and string values
            "SETTINGS": false,
            "SORT": true,
            "ZOOM_ACTION": false
        }
    }
});

visualBuilder.render(document.querySelector('#builder'), { width: '800px', height: '100px' });