Embed a KPI Dashboard

Overview

Embedding a KPI dashboard creates a version of the KPI dashboard minus platform functions for use in your own product.

  • If you are a Growth or Enterprise customer, embedding Analytical Designer (insights) and KPI Dashboards will remove all the GoodData branding.
  • If you are a Free customer, the following Powered by GoodData logo will be displayed on embedded tools.


    Note: Clicking the logo redirects you to either the GoodData product documentation (Administrators) or the GoodData website (other roles). See User Roles.

Contents:

Create a URL for embedding a KPI Dashboard

To acquire a simple embedding URL directly through the KPI Dashboards, see Embed KPI Dashboards.

This article assumes that you access your projects at https://secure.gooddata.com/.

Steps:

  1. Log in to the GoodData Portal.
  2. Click the KPIs tab.
  3. To embed an empty dashboard in the edit mode, use the following URL:

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/new-dashboard
  4. To embed an existing KPI dashboard:
    1. From the list of KPI dashboards, select the KPI dashboard that you want to embed.

    2. Check the URL in the browser address bar. For example:

      https://secure.gooddata.com/dashboards/#/project/{project_id}/dashboard/{dashboard_identifier}/
    3. Add the string /embedded/ into the URL after /dashboards. For example:

       https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}/
      • You can use the dashboard ID instead of the dashboard identifier.
        https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboardId/{dashboard_id}/
      • If you use LCM (see Managing Projects via Life Cycle Management), use the combination of the data product ID and client ID instead of the project ID:
        https://secure.gooddata.com/dashboards/embedded/#/product/{data_product_id}/client/{client_id}/dashboard/{dashboard_identifier}

      For more details about formats of the embedded URL, see Embedding Code Formats.

Advanced configuration options

This section assumes that you embed a specific dashboard. To add these option to an empty dashboard, use https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/new-dashboard as the URL.

  1. If you want the navigation panel listing KPI dashboards to be visible (by default, it is hidden), add the showNavigation parameter to the URL and set to true.

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?showNavigation=true
  2. To configure hiding and displaying of attributes, measures, or dates based on tags, add either of the following parameters to the URL:
    ?includeObjectsWithTags=[tag_name] - to show only the attributes, measures, and dates with the specified tag
    ?excludeObjectsWithTags=[tag_name] - to hide the attributes, measures, and dates with the specified tag

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?includeObjectsWithTags=[sales]
     
    https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?excludeObjectsWithTags=[marketing,hr]
     
    https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?excludeObjectsWithTags=[finance]&showNavigation=true
    • The tags must include only lowercase characters, uppercase characters, and numbers.
    • To specify multiple tags, separate them with a comma.
    • If you specify both parameter at the same time, only the includeObjectsWithTags parameter is applied and the excludeObjectsWithTags parameter is ignored.

    Hiding and displaying attributes, measures, and dates is not a security feature. Items are hidden and shown depending on the parameter in the URL, and anyone who can access and edit the URL can change the parameters.

    For more information about the tags, see Add a Tag to an Attribute, Add a Tag to a Metric, Add a Tag to a Fact, and Add a Tag to a Dataset.

  3. To hide the filter bar, add the ?hideControl=[filterBar] parameter to the URL.

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?hideControl=[filterBar]

    To hide multiple parameters, separate them with a comma: ?hideControl=[filterBar,widgetsCatalogue]

  4. To hide the list of insights and other items that you can add to dashboards, add the ?hideControl=[widgetsCatalogue] parameter to the URL.

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_id/dashboard/{dashboard_identifier}?hideControl=[widgetsCatalogue]
  5. To hide the top bar, add the ?hideControl=[topBar] parameter to the URL.

    https://secure.gooddata.com/dashboards/embedded/#/project/{project_id/dashboard/{dashboard_identifier}?hideControl=[topBar]

Use the completed URL as the basis for embedding your KPI Dashboard. For example:

https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}/?hideControl=[filterBar,topBar]

Add the embedded dashboard to your page

The following is an example reference using the project ID in your URL:

<iframe src="https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}/" frameborder="0" id="frame"></iframe>

On Apple mobile devices, the headers may not stick to the top of the visible area and therefore scroll up with the rest of the content.

To prevent this:

  1. Set the static height for the iframe.
  2. Use the setHeight parameter in your URL and set to the same number as the height of the iframe. For example:

    <iframe src="https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?setHeight=500"
    height="500px" frameborder="0" id="frame"></iframe>

If you use the scrolling=no parameter in the URL, verify that the iframe is resized according to its content so it is handled by JavaScript:

<script> 
window.addEventListener('message',function(event) {
		switch(event.data.gdc.event.name) {
			case 'resized':			
				var height = event.data.gdc.event.data.height;
			
				if (height) { 
					document.getElementById('frame').style.height = height + 'px'; 
				}	
				break;
		}
	},false);
</script>

Embedding limitations

  • If you use less than 1170 px of horizontal space for the embedded component, the Edit button and all controls for saving in edit mode are not displayed.
  • When yo add an alert to a KPI, the email notification that is generated when the KPI value meets the alert parameter, may or may not include a link to the KPI Dashboard. This depends on the user access to the GoodData Portal:
    • If the user does not have access to the GoodData Portal, the email does not contain a link to the KPI Dashboard.
    • If the user has access, the email contains the link.
      To hide this link for user with access to the GoodData Portal, contact https://support.gooddata.com/.
  • If you use the scrolling=no parameter in the URL, table headers will not stick to the top of the visible area to ease reading table.
  • The layout of the KPIs and insights on an embedded KPI dashboard (that is, how many KPIs and insights are placed in one row and spacing between them) depends on the size of horizontal space where the dashboard is embedded. Resizing the frame of the embedded dashboard changes the layout automatically in a predefined way, which cannot be adjusted manually.
  • If the KPI dashboard cannot be found within the project, GoodData displays the last opened KPI dashboard from the same project. Any parameters specified in the URL are disregarded.
  • If the project cannot be found, GoodData displays your last opened project. Any parameters specified in the URL are disregarded.

Example of HTML page with an embedded KPI Dashboard

You can copy the following code and use your own URL in the iframe section to try embedding.

<html>
<head>
	
</head>
<body>
	
	<button type="button" id="postMessageApiButton">Send message</button>
	<input type="text" id="input" value="" size="50"> 

	
	<iframe id="iframe0" src="{embed_dashboard_URL}?showNavigation=true&disabladEditMode=true" width="80%" height="80%" style="border:1px solid black;">
	</iframe>
	
	<div id="received">
	</div>
	
	<script>
		var targetFrame = document.getElementById("iframe0").contentWindow;
		var targetOrigin = '*';
		var received = document.getElementById("received");
		
		
		document.getElementById("postMessageApiButton").addEventListener('click', () => {
			var input = document.getElementById("input").value;
			var input = JSON.parse(input);
			console.log(input);
			targetFrame.postMessage(input, targetOrigin);
			
		});
		
		window.addEventListener('message', (event) => {
		    console.log(event.data.gdc);
			received.innerHTML += "<p>"+JSON.stringify(event.data)+"</p>";
			
		});
		</script>
	
</body>
</html>

Communication with the Embedded KPI Dashboard

For detailed information, see Communication with Embedded KPI Dashboards.


Powered by Atlassian Confluence and Scroll Viewport.