Skip to main content
waffle.svg
Domo Knowledge Base

Sharing Cards and Stories Outside of Domo Using Domo Embed

Version 7

 

Intro

Using the "Domo Everywhere: Domo Embed" feature, you can embed Domo Cards and Domo Stories...

  • privately in SSO-enabled websites, portals, or applications, or

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

Important: Due to security reasons, Domo Everywhere: Domo Embed is not available for HIPAA-compliant Domo instances.

You do this by copying an automatically generated HTML string from Domo and pasting it into the necessary location in 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 Stories, you can choose whether or not to include the following options:

  • Story title

  • 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 Everywhere: 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 - Embedding a Domo Card


Video - Domo Everywhere: Public Embed


PDF - Public Embed and Authenticated Embed

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

 

Caveats

To embed Cards privately, all of the following conditions must be met:

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

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

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, while public embedding is currently available only for KPI Cards and Custom Apps. It is not currently possible to embed other Card types such as Notebook Cards, Doc Cards, etc.

  • Titles, drilldown, Summary Number, and the chart picker are all available when embedding Cards publicly; however, filters are not yet available. 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.

  • It is recommended that you embed no more than 10 Cards on one Page, as this hurts performance. 

  • Sumo pivot tables are not supported.

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 Everywhere: Domo Embed for Cards

Domo Everywhere: 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 Everywhere: 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

To embed a Card using the JavaScript API, do the following:

  1. In the <head> section of your HTML document, add the following HTML, replacing “yourinstance” with your URL and “yourkey" with your API key.

    <script src="http://yourinstance.domo.com/embed/yourkey/domo.js"></script>

2. In the <body> section of the HTML, insert a <div> where you want to embed the Domo Card.

3. Use Domo.embed to embed a Card in the DIV.
Currently this is the only function you can use. You can use Domo.embed to embed a Card in a <div> by ID, class or DOM element.

Examples:

  Domo.embed(…).intoElementWithId(‘divid’);

 Domo.embed(…).intoElementWithClass(‘class’);

 Domo.embed(…).intoElement(document.body);

Full HTML Example:

<html>

<head>

  <script

    src="http://domo.domo.com/embed/eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lciI6IioiLCJhbGxvd2VkRG9tYWlucyI6IioiLCJleHBpcmVzIjoibmV2ZXIifQ.30NufBEghPEJMCFf2TwKMAHT6arvgPZ-badTqI49Q8I/domo.js"></script>

</head>

<body>

<div id=“my-chart” style="width: 600px; height: 600px;"></div>

<script>

  Domo.embed({

    type: "Card",

    id: 1491996447,

    viewId: 1123,

    options: {

      showTitle: false,

      showSummaryNumber: true,

      allowDrill: true,

      allowTableView: true,

      allowFilters: true,

      allowChartPicker: true

    }

  }).intoElementWithId(“my - chart”);

</script>

</body>

</html>

Rendering API data as a Card

Here is a code sample for pulling data from an API and rendering it as a Card. (Replace all values in [] with your own parameters.)

$.ajax({
  url: 'https://api.domo.com/v1/datasets/que...ecute/[DataSet ID],
  type: 'POST',
  data: JSON.stringify({ "sql": "[Query]" }),
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Accept', 'application/json');
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.setRequestHeader('Authorization', 'bearer [Auth Token generate using client id and secret]);
 
  },
  success: function (results) {
    console.log(results);
    const data = {
      // This is the data you get back from the Domo Data API
      rows: results.rows,
      // You provide the names, types, and mappings of your ordered columns
      columns: [
        {
          type: DomoPhoenix.DATA_TYPE.STRING,
          name: ‘[Column 1]’,
          mapping: DomoPhoenix.MAPPING.SERIES
        },
        {
          type: DomoPhoenix.DATA_TYPE.STRING,
          name: ‘[Column 2]’,
          mapping: DomoPhoenix.MAPPING.ITEM
        },
        {
          type: DomoPhoenix.DATA_TYPE.DOUBLE,
          name: ‘[Column 3]’,
          mapping: DomoPhoenix.MAPPING.VALUE
        }
      ]
    };
 
    // Chart Options
    const options = {
      width: 600,
      height: 500
    };
 
    // Create the chart in Domo
    const chart = new DomoPhoenix.Chart(DomoPhoenix.CHART_TYPE.BAR, data, options);
 
    // Append the canvas element to your app
    document.getElementById('myDiv').appendChild(chart.canvas);
 
    // Render the chart when you're ready for the user to see it
    chart.render();
  }

 

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 Everywhere: Domo Embed for Domo Stories

Domo Everywhere: Domo Embed is available for any Domo Story. You can access the option by going into the Share menu for the Story Page and selecting Embed Dashboard. With Story 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 Everywhere: Domo Embed dialog for a Story:
 

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 Story. The following toggles are available:

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

  • Allow interactions and filtering. Allows you to enable interactions and filtering on embedded Story 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 Stories, 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 Story 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 Story). 

  • 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 Stories.

  • 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 Story. 

Embed options

Let you specify whether this Story is to be embedded, and, if so, privately or publicly (the default option is Off). If you choose to make a Story 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 Story 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 Story outside of Domo privately,

  1. Navigate to the Story 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 Story 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 Story 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 Story outside of Domo publicly,

  1. Navigate to the Story 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 Story 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. Note that Embed is NOT available on HIPAA-compliant instances.

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 Stories.

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