Skip to main content
waffle.svg
Domo Knowledge Base

Sharing Cards Outside of Domo Using Domo Embed

Version 44

 

Intro

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

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

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.

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.

  • Though you can embed multiple Cards on a page, you will need to generate code for each Card independently.

  • You cannot currently embed a page of Cards as one iFrame.

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

 

/**
 * 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

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:

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>

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.  

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.