Embed a KPI Dashboard

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.


Embed a KPI Dashboard


  1. Create a URL for the embedded KPI dashboard:
    1. Log in to the GoodData Portal.
    2. Click the KPIs tab.
    3. From the list of KPI dashboards, select the KPI dashboard that you want to embed.

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

    5. Add the string /embedded/ into the URL after /dashboards. For example:


      By default, you would have the dashboard identifier and the project ID in your URL. However, there are other ways to construct the embedding URL.

      • If you store the dashboard ID, you can use it instead of the dashboard identifier:

      • 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:

      For more details about formats of the embedded URL, see Embedding Code Formats.
    6. 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:

    7. (Only when you have tags assigned to attributes, measures, or date datasets) If you want to configure hiding and displaying 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


      Do not specify both the parameters at the same time. If you do, only the includeObjectsWithTags parameter is applied, and the excludeObjectsWithTags parameter is ignored. You can specify more than one tag by separating them with a comma. The tags must include only lowercase characters, uppercase characters, and numbers.

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

      For more information about adding tags to attributes, measures, facts, or date datasets, see: 

      When you are done with creating the URL, you can use this URL as the basis for embedding the KPI dashboard.

  2. Include the embedded dashboard in 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>

    If you are using an Apple mobile device for viewing a large embedded KPI dashboard, the table headers may not stick to the top of the visible area and therefore scroll up with the rest of the content.

    To prevent this, do the following:

    1. Set a static height for the iframe.
    2. Use the setHeight parameter in your source URL and set it to the same number as the height of the iframe.

    Your reference for including the embedded dashboard should look like the following (a height of 500 px is used in this example):

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

  3. (Only when you are using scrolling=no in the URL) Make sure that the iframe is resized according to its content so it is handled by JavaScript:

    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'; 
  4. (Optional) If you want to hide the Drill into dashboard section from the embedded KPI dashboard so that users of this KPI dashboard cannot see it, contact GoodData Support.
  5. (Optional) Select which events become drillable.
    For details, see Setting up Events for Drilling in Embedded Analytical Designer and KPI Dashboards.

Embedding Limitations

  • Editing embedded KPI dashboards requires at least 1170 px of horizontal space for the embedded component. When less space is available, the Edit button and all controls for saving in edit mode are not displayed.

  • When a user adds an alert to a KPI, the email notification that is generated when the KPI value meets the alert parameters may or may not contain a link to the KPI dashboard. Whether the link is or is not in the notification depends on the user's access to the GoodData Portal:
    • If the user does not have access to the GoodData Portal, the email notification will not contain a link to the KPI dashboard.
    • If the user has access to the GoodData Portal, the email notification will contain a link to the KPI dashboard. If you want to hide this link for the users with access to the GoodData Portal, contact GoodData Support.
  • If you are using scrolling=no in the URL, table headers become not sticky: they will behave as any other part of the dashboard and will not stick to the top of the visible area to ease reading tables.
  • 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.

Communication with the Embedded KPI Dashboard

You can set up receiving messages from the embedded KPI dashboard to your application.

The messages are sent in the following format:

  "gdc": {
    "component": "dashboard",
    "event": {
      "name": "{event_name}",
      "data": {
        "{parameter_1_name}": "{parameter_1_value}",
        "{parameter_2_name}": "{parameter_2_value}"

The following events are supported:

EventEvent trigger
loadingStartedThe embedded content starts loading.
loadedThe content is fully loaded, and the user has permissions to access the dashboard.

The user does not have permissions to view or edit the content. The 'data' section contains information about whether view or edit permissions are missing:

"data": {
  "reason": "viewDenied|editDenied"

An operation increasing the height of the hosting iframe is performed. The 'data' section contains information what hight the iframe needs (in pixels):

"data": {
  "height": {height_in_px}

A dashboard has been created and saved. The 'data' section contains, among other information, the dashboard ID. You can store it on your side and use later for managing multiple dashboards for this particular user.

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"
dashboardCreationCanceledThe user cancels the creation of the dashboard.

The existing dashboard has been updated. The 'data' section contains, among other information, the dashboard ID. You can store it on your side and use later for managing multiple dashboards for this particular user.

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"

The dashboard has been deleted. The 'data' section contains information about the deleted dashboard:

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"

The GoodData platform is temporary unavailable:

"data": {
  "status": "maintenance|upgrade|error"

For the status of 'error', the 'data' section contains additional error details:

"data": {
  "status": "error",
  "errorCode": "{error_code}",
  "description": "{error_description}"