Skip to main content
waffle.svg
Domo Knowledge Base

Sharing Cards and Dashboards Outside of Domo Using Domo Embed

Version 14

 

Intro

The Domo Everywhere product suite includes Domo Embed which allows you to embed Domo within any website, application, or portal. Whether you want to embed a single Card, an interactive Dashboard, Domo Apps or even the entire explorer portion of Domo, we’ve got you covered. This article introduces the different options of embed and addresses frequently asked questions to get “Domo Goodness” embedded inside of your environment, quickly and easily.

  • Publicly on public websites, blogs, or social media platforms such as Facebook and Twitter.

  • Privately in websites, portals, or applications.

    • User Based - With Single Sign-On (SSO) enabled, leveraging personalized data permissions (PDP).

    • Server Based - With programmatic server-side filtering.

    • Platform Based (Beta) - Complete editable experience with Single Sign On (SSO) enabled, leveraging personalized data permissions (PDP). If you are interested in joining the Beta for this feature, please contact your Account Executive or Customer Success Manager.

Important: Due to security reasons, the option to embed content PUBLICLY is not available for HIPAA-compliant Domo instances. The PRIVATE embed options are available.

If you need assistance on choosing the right embed method, contact your Account Executive or Customer Success Manager and they will go over the embed method that is right for your use case and organization.

For Public and Private User Embed this is done by copying an automatically generated HTML string from Domo and pasting it into the necessary location on the website, blog, etc. as an iFrame or via a JavaScript API. This feature enables you to share business data in a consumable, interactive, and accessible way.

For individually-embedded Cards, you can choose whether or not to include Card features regularly available in the Details view, including all of the following:

You can also set the size of embedded Cards, either by choosing a preset size or entering a custom width and height.

For Domo Dashboards, you can choose whether or not to include the following options:

  • Dashboard title

  • Show Filter bar

  • Interactions and filtering

  • Export of the raw data of each Card to CSV

  • Persist filters, which automatically append pfilter parameters to the end of any custom interaction links

  • Opening of links in a new tab

Domo Embed is compatible with PDP, though this is feasible only for privately-embedded Cards.  

You can get an administrative view of embedded content using the Activity Log.

Confused about when to use Public and Private embed? Visit this PDF to find use cases for each: Public Embed and Authenticated Embed1.pdf

Video - Embed a Domo Card


Video - Domo Everywhere: Public Embed


PDF - Public Embed and Private Embed

To download this PDF to your computer, mouse over the top of the PDF and click pdf_download.png

 

Caveats

For all Private embedded Cards or Dashboards:

  • Currently, third-party cookies must be enabled in the website, portal, or application.

  • Social users cannot embed, create an iFrame, or view privately embedded content. Participant users cannot embed, but can view privately embedded content.

  • If the embed is taking place on a Safari browser, you must temporarily route your client window to a CORS endpoint in order to set a placeholder Domo cookie. This is discussed in greater detail in Overcoming Safari's Third-Party Cookie Policy, below.

For Private "User Based" and "Platform Based" embedded Cards or Dashboards (this does not pertain to "Server Based"):

  • SSO (Single Sign-On) must be enabled in Domo as well as in the website, portal, or application.

    • If the Only Invited People Can Access Domo option is enabled in Admin Settings > SSO, any non-Domo user attempting to access the Card will be denied. If this option is disabled, a non-Domo user will be auto-provisioned based on the access rights set for default users. The default setting is "Privileged."

    • For more information about access rights, see Controlling Access in Domo.

Also note the following:

  • If for security reasons you do not want your employees to be able to embed Cards publicly, you can turn off this functionality for your company by going into Admin Settings > Company Settings > Company Overview then unchecking the box for "Publicly embed Cards."

  • Private embedding is available for all types of Cards except Sumo pivot tables. Currently, Notebook Cards and Doc Cards cannot be embedded on their own but can be embedded as part of a Dashboard.

  • Titles, drill down, Summary Number, and the chart picker are all available when embedding Cards publicly; however, filters are only available for columns used in the Card. For security reasons, the end-of-Card table view is not available with this feature.

  • When embedding Cards individually, note that you can embed multiple Cards on a Page, but you will need to generate code for each Card independently.

Overcoming Safari's third-party cookie policy

Safari has a third-party cookie policy that blocks clients from setting cookies for third party domains without permission. This applies to all scripts and widgets embedded from third-party sources, not just Domo Cards. This means that unless the client has already set cookies for the Domo domain previous to navigating to your embed solution, any attempt to view privately embedded Domo content in Safari will fail. You will most likely experience an infinite redirect loop from the Domo Card to the authentication endpoint of your Identity Provider (IdP). No errors will be thrown, unless your IdP limits authentication request attempts, in which case you might see a 429 (Too Many Requests) error.

As a workaround for this issue, Domo engineers have added a CORS endpoint. Temporarily routing the client window location to this endpoint from your embedding site sets a placeholder Domo cookie while the Domo domain has full context of the Safari window. It then immediately redirects back to the embedding site without rendering any Domo content (this is virtually unnoticeable by the user). Once any cookie has been set on the Domo domain within Safari, the client will be able to set all of the required third-party Domo cookies in the embedded content.

For this to work, you must do two things:

  1. Navigate to Admin > Security > Embed settings in Domo and enter the names of all domains you will be accessing Safari from. (You must have an "Admin" default security profile or a custom role with "Embed Cards" enabled to access this Page in Admin Settings.) The bounce Page will work only when the user’s browser originates from one of the whitelisted URLs found in this list.

  2. Run the JavaScript below, being sure to replace the embeddingsite text with the name of your Domo domain. This JavaScript looks to see whether your browser accepts a cookie from Domo; if not, you are sent to the bounce Page in the Domo instance. You can run the JavaScript anytime before you embed a Domo Card in Safari. 
     

Important: DO NOT run this code more than once per client per history, or else you may potentially put yourself into an infinite loop. One way to avoid the infinite loop scenario is to set a cookie or "Localstorage" variable to track if the following code has already run.

Important: As of December 19, 2019, Safari's Intelligent Tracking Prevention (ITP) now blocks all third-party requests from seeing their cookies, regardless of the classification status of the third-party domain, unless the first-party website has already received user interaction. To get around this issue, industry standard has been to show a popup or growl message that requests acceptance before usage of cookies on the site continues, such as the following:

This means that as of Safari version 13.0.4, the bounce page solution described here may require user input to function properly.  
 

 

/**
 * checkThirdPartyCookies
 * 
 * Check for CORS support and verify that a cookie has been set on the window context (for Domo) at least once
 * for Safari support. Once this method has been called, it shouldn't need to be reused until the 
 * browser's cookies/history has been cleared.
 */
function checkThirdPartyCookies() {
  try {

    // Create a request for setting a 3rd party cookie
    var xhr = get("https://embeddingsite.domo.com/cookieSupport?action=setCookie").then(
      function success(xhr) {
        // CORS may have worked, so now we need to check the cookie value.
        checkCookie();
      }, function failure(xhr) {
        // The initial request to set a cookie failed, cors is not available on this browser. Hit the bounce Page.
        window.location = "https://embeddingsite.domo.com/safari-special";
      });
      
      /**
       * checkCookie
       * 
       * Call the `cookieSupport?action=setCookie&cookieValue={cookieValue}` endpoint to verify that
       * the original call to set the cookie was done correctly.
       */
      function checkCookie() {
        // Attempt to retrieve the cookie value
        var cookieValue = getCookie("safari");
        
        // If the cookie exists, check its value
        if (cookieValue) {
          // Create a request to check the cookie value
          var verifyXhr = get("https://embeddingsite.domo.com/cookieSupport?action=setCookie&cookieValue=" + cookieValue).then(function cookieSuccess(xhr) {
            // The request succeeded, so we have a response. The responseText should be a boolean value of either be true or false.
            var response = JSON.parse(responseText); 
            if (!response) { // if its not "true"
            // We had the wrong cookie value, so hit the bounce Page anyway.
            window.location = "https://embeddingsite.domo.com/safari-special";
          }
        }, function cookieFailure(xhr) {
          // There was an issue checking the cookie, so hit the bounce Page.
          window.location = "https://embeddingsite.domo.com/safari-special";
        });
      } else {
        // There was no cookie value, so hit the bounce Page.
        window.location = "https://embeddingsite.domo.com/safari-special";
      }
    }
  } catch (error) {
    // third party cookies are not allowed
    window.location = "https://embeddingsite.domo.com/safari-special";
  }
}

/**
 * getCookie
 * @param {String} name : the name of a cookie to retrieve a value for
 */
function getCookie(name) {
  var value = "; " + document.cookie;
  var parts = value.split("; " + name + "=");
  if (parts.length == 2) return parts.pop().split(";").shift();
}

/**
 * get
 * @param {String} url : a URL to request from using a GET method 
 */
function get(url) {
  return new Promise(function(resolve, reject) {
  var xhr = new XMLHttpRequest();
  xhr.open("GET", url);
  xhr.withCredentials = true;
  xhr.send('null');
  xhr.onreadystatechange = function onReadyStateChange() {
    if(xhr.readyState === 4 && xhr.status !== 200) {
      reject(xhr);
    } else if (xhr.readyState === 4 && xhr.status === 200) {
      resolve(xhr);
    }
  }
 });
}

Using Domo Embed for Cards

Domo Embed is available for any Card. You can access the option for the Card either on the Page level or in the Details view for the Card, by going into the Wrench menu and selecting Domo Everywhere.
 

domo_embed_option.png
 

The following image points out the components of the Domo Embed dialog for a Card:

domo_embed_ui2.png

You can use the following table to learn more about the parts of this dialog:

Component Description

Display options

Let you toggle certain Card features on or off in the embedded Card. The following toggles are available:

  • Show title. Toggles the Card title.

  • Allow drill. Toggles drill capability.

  • Allow table view. Toggles the ability to open the data table for the Card. When this option is enabled, a grid icon appears at the top of the Card. Viewers of the embedded Card can open the data table by clicking this icon. Available for privately embedded Cards only. 

  • Show summary number. Toggles the Summary Number for the Card.

  • Allow filter changes. Toggles the ability to set or change filters for the Card. When this option is enabled, a funnel icon appears at the top of the Card. Viewers of the embedded Card can toggle the filter options by clicking this icon. Currently available for privately embedded Cards only.

  • Allow chart picker. Toggles the ability to change the chart type. When this option is enabled, a pie graph icon appears at the top of the Card. Viewers of the embedded Card can open the chart picker by clicking this icon.

Sizing options

Allow you to set the size of the embedded Domo Card. Three default sizes are available: Square (600 x 600 pixels), Portrait (600 x 900) pixels, and Landscape (900 x 600 pixels). There is also a Custom option, which allows you to set your own custom width and height.

Preview

Displays a preview of the Card with the size and option settings you have applied. You can interact with this preview just as you can the embedded version of the Card. For example, you can change the chart type, drill into the Card (if drill is enabled), toggle series items by clicking them in the legend, and so on.

Embed menu

Lets you choose whether this Card is to be embedded in an iFrame or using a JavaScript API. For more information about the JavaScript API, see the next section.

Privacy options

Let you specify whether this Card is to be embedded privately (default) or publicly. If you choose to make a Card public, anyone on the web will be able to view it and the displayed data. This also gives Domo permission to publish the Card as part of a public Card newsfeed. 

When you choose the Public option, a URL is generated (under Share link), which you can then copy and paste into the desired website, blog, social media platform, etc. You may also directly open any of 5 social media platforms (Facebook, Twitter, Google+, LinkedIn, or Pinterest) so you can embed the Card immediately. 

HTML string

Displays the automatically generated HTML string that you copy and paste into the website, portal, or application. You can copy the HTML by clicking the domo_embed_copy.png button to the right of the HTML string.

To embed a Card outside of Domo privately,

  1. Navigate to either the Page in which the Card is found or the Details Page for the Card.

  2. In the Wrench menu for the Card, select Domo Everywhere.

  3. Select a preset size for the embedded Card in the Default Size menu or select Custom and enter the desired dimensions in the Width and Height fields.

  4. Check the boxes for all the display options you want to include in the embedded Card.

  5. In the Embed Using menu, select whether you want to embed the Card in an iFrame or use a JavaScript API.
    For more information about the JavaScript API, see the next section.

  6. Click the domo_embed_copy.png icon to copy the HTML to embed.

  7. Paste the HTML into the website, portal, or application where you want the Card to appear. The specific instructions for doing this will vary depending on the website, portal, or application. Consult your documentation for more information.

To embed a Card outside of Domo publicly,

  1. Navigate to either the Page in which the Card is found or the Details Page for the Card.

  2. In the Wrench menu for the Card, select Domo Everywhere.

  3. Select a preset size for the embedded Card in the Default Size menu or select Custom and enter the desired dimensions in the Width and Height fields.

  4. Check the boxes for all the display options you want to include in the embedded Card.
    Allow table view and Allow filter changes are not currently available for publicly embedded Cards. 

  5. Select Publicly Available in the Privacy Options menu.

  6. Click Make Public.

  7. Click the clipboard icon to copy the automatically generated URL. 

  8. (Conditional) To embed the Card in any of the 5 listed social media platforms, click the icon for the desired platform, log in if necessary, and paste the URL as required by the platform. Otherwise, open your website, blog, etc., and paste the URL as necessary.

Using the JavaScript API or Rendering API data as a Card

Please visit https://developer.domo.com/docs/overview/embedded-analytics for code examples in using the JavaScript API or Rendering API data as a Card options.

Tracking publicly embedded Cards

You can keep track of all publicly embedded Cards in your Domo instance in Admin Settings > Domo Everywhere. You can see information such as embed creator, current embed link status (public or disabled), number of public views, and so on. You must have an "Admin" security role or a custom role with "Embed Cards" enabled to see this tab. For more information, see Admin Settings Layout - Domo Everywhere Tab.  

Using Domo Embed for Dashboards

Domo Embed is available for any Domo Dashboard. You can access the option by going into the Share menu for the Dashboard and selecting Embed Dashboard. With Dashboard Embed, you can only embed using an iFrame, not a JavaScript API as you can with Card Embed. 
 

domo_embed_option_stories.png
 

The following image points out the components of the Domo Embed dialog for a Dashboard:
 

domo_embed_ui_stories.png
 

You can use the following table to learn more about the parts of this dialog:

Component Description

Display options

Let you toggle certain features on or off in the Cards in the embedded Dashboard. The following toggles are available:

  • Show title. Toggles the Dashboard title. The title can be hidden if you have already labeled the content in the host page that contains the iFrame.

  • Page filters. Allows you to use page filters on the Dashboard.

  • Allow interactions and filtering. Allows you to enable interactions and filtering on embedded Dashboard Cards. You should turn off this option if you want to lock down your embedded content (usually only for public embed).

    Interactions include such actions as opening the Card details view in a new browser tab, opening a specified web page, and enabling drilldown into the Card. For more information about configuring interactions in Dashboards, see Setting Card interactions.

    Filtering in this case refers to the use of Page filters, which are discussed in Applying Page-Level Filters. Note that when you embed a Dashboard publicly, all columns on all DataSets used in the Page are available for filtering whether the columns are used in Cards or not. However, you can block access to sensitive columns by disabling interactions on the Cards (as explained in Setting Card interactions) or transforming the data to exclude the columns.  

  • Allow export. Allows users to export the raw data for each Card in CSV format. (The Export button appears when users mouse over Cards in the embedded Dashboard). 

  • Persist filters. Enables persist filters, which automatically append pfilter parameters to the ends of any custom interaction links so that the following content maintains context around filters on this Page. Persist filters are discussed in detail here: Using Pfilters to Apply Filters from URL Query Parameters to Embedded Dashboards.

  • Open links in new tab. When users click on links in Cards, they are opened in a new browser window; otherwise the new content opens within the iFrame. (The Allow interactions and filtering option must be checked for links to be clickable.)  

Sizing options

Allow you to set the width and height of the embedded Domo Dashboard. 

Embed options

Let you specify whether this Dashboard is to be embedded, and, if so, privately or publicly (the default option is Off). If you choose to make a Dashboard public, anyone on the web will be able to view its content. 

When you choose the Public option, a URL is generated (under Share link), which you can then copy and paste into the desired website, blog, social media platform, etc. The public embed option is not authenticated so filters cannot be personalized. 

When you choose the Private option, users will need to authenticate to see the embedded content. Because the private embed option uses authentication, filters can be personalized via PDP or programmatic filters.

Export DataSet mapping Lets you download a CSV file that lists all of the original DataSet IDs used in the Cards in the Domo Dashboard and maps them to obfuscated datasource IDs that can be used outside the Domo platform.  
Embed ID Used in the HTML embed code in programmatic filtering, which is discussed here: Using Programmatic Filters with Domo Embed (BETA).

HTML string

Displays the automatically generated HTML string that you copy and paste into the website, portal, or application. You can copy the HTML by clicking the domo_embed_copy.png button to the right of the HTML string.

To embed a Dashboard outside of Domo privately,

  1. Navigate to the Dashboard in Domo.

  2. In the details_export_icon.png menu for the Card, select Embed Dashboard.

  3. Check the boxes for all the display options you want to include in the Dashboard Cards.

  4. Enter the desired dimensions in the Width and Height fields.

  5. Select Private in the Embed options menu.

  6. Click the domo_embed_copy.png icon to copy the HTML to embed.

  7. Paste the HTML into the website, portal, or application where you want the Domo Dashboard to appear. The specific instructions for doing this will vary depending on the website, portal, or application. Consult your documentation for more information.

To embed a Dashboard outside of Domo publicly,

  1. Navigate to the Dashboard in Domo.

  2. In the details_export_icon.png menu for the Card, select Embed Dashboard.

  3. Check the boxes for all the display options you want to include in the Dashboard Cards.

  4. Enter the desired dimensions in the Width and Height fields.

  5. Select Public in the Embed Options menu.

  6. Click the clipboard icon to copy the automatically generated URL. 

  7. Open your website, blog, etc., and paste the URL as necessary.

Private Embed with PDP Playbook

Configuring Private Embed with PDP - Playbook

Private Embed leverages Domo’s SSO to authenticate users on the Domo platform. Embedded content is then served to the end user via either the Javascript API or iFrames. Private Embed can be paired with PDP to serve appropriate content to end users, including external end users. If Embed is to be used to serve content to external end users, one of two methods is preferred:

  • Embed cards from a white-labeled subscriber instance (see Domo Publish). This way, if a savvy end user was to access the Domo application, they would see only a white-labeled instance (e.g. no Buzz functionality).
  • Use Programmatic Embed. When using Programmatic Embed, end users are NOT actually authenticated users of Domo. Thus, end users are not able to access the Domo application. This means the portal or application code handles authentication and ensures end users see the appropriate data. See Using Programmatic Filters with Domo Embed for more information.

To implement Private Embed:

  1. Set up SSO. 

  2. Enable Private Embed, as explained above.

  3. Set up PDP. 

  4. Configure cards/pages for embedding. 

  5. Embed cards/pages using iFrame or Javascript code in the portal or application.

All of these steps are described in continuation. 

Enable Private Embed

Embed is a premium feature subject to additional fees. Once you have purchased Domo: Everywhere, you will need to reach out to your CSM to have the feature enabled in your instance.

Configure Cards/Pages

Configuring Cards and Pages for embedding is a simple process. For more information, see Using Domo Embed for Cards and Using Domo Embed for Dashboards.

Manage Embedded Cards/Pages

In Admin Settings > Domo Everywhere, you’ll find a list of all Cards and Dashboards that have been configured for embedding.

Embed Cards/Pages

Cards can be embedded using Iframes or JavaScript. The code to be included in the customer website is obtained when configuring the embedded Card. 

Enabling Domo Embed

To enable this feature, a user with an "Admin" default security role or a custom role with "Embed Cards" enabled must go into Admin Settings > Company Settings > Company Overview, then check the box for Publicly embed Cards. Note that Public Embed is NOT available on HIPAA-compliant instances.

 
Note: This is a 30-day free trial. At the end of the first 30 days of use, your Domo account representative will reach out to you to discuss pricing.