Customization & Interactivity

Embedded content can be customized with dashboard themes, vanity domains and you can also increase the interactivity of embed content with linking, javascript events, and post messages.

Vanity Domains

🪞 You may want to implement the use of a vanity domain for your embedded dashboards if you need to utilize first-party cookies or would like to have cohesive branding of the content you share with your clients.

🔥 Tips

• This feature is only available for private embed use cases.
• Only one vanity domain is allowed per Omni organization.
• Have a multi-part domain like products.ecommerce.com or dev.products.ecommerce.com.

SDK Example

Vanity Domain: products.ecommerce.com

const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "wile.e@coyote.co",
  name: "Wile E",
  organizationName: "products",
  domain: "ecommerce.com",
  secret: "abcdefghijklmnopqrstuvwxyz123456"
});

Note: Your SDK must have the domain: parameter in addition to the organizationName: parameter in order to properly generate the embed URL.

How to...

1. 📧 Start this process by reaching out to support@omni.co with the following information:

   • Provide the vanity domain you are interested in, e.g. products.ecommerce.com

   • Key considerations:

     • Note that a vanity domain must have three, or more, parts like the example above - ecommerce.com without “products” prepended will not be considered a valid vanity domain.
     • The top level domain of the vanity domain must match the embedding page to support first party cookies.
       • If your embedding page is ecommerce.com, then your embedded vanity domain should be omni.ecommerce.com
       • If your embedding page is ecommerce.com and you provide an embedded vanity domain of ecommerce.omni.com then you may still run into third-party cookie limitations on some browsers like Safari or other iOS applications.

2. Your dedicated Omni team will reach back out with DNS configuration details and ask that you update your DNS configuration.

3. Once confirmed it is updated with Omni, the team can complete the next configuration steps.

4. Your Omni team will let you know once all of the settings are enabled and ready for you to start rocking that vanity domain 🤘

Linking to Other Content

The Markdown component can be used to build links to other Omni content, like other dashboards. These links work seamlessly within the app, and don't require any complex iframe manipulation.

Embed SSO requires enabling link access:

• You'll need to specify __omni_link_access_open (described in the docs) to permit linking in an embed session.

Linking is as easy as setting an <a> tag's href in markdown to the relative path of a piece of content, like a dashboard.

Example:

## Dashboards

1. <a href="/dashboards/123abc">Product Dashboard</a>
2. <a href="/dashboards/789xyz">Sales Dashboard</a>

You can also link filters between dashboards using mustache references to the filter values. For example, if you have a filter on Traffic Source you can reference it like so:

<a href="/dashboards/123abc?f--users.traffic_source={{filters.users.traffic_source.json}}">Product Dashboard</a>

This allows linking of dashboard and dashboard state across multiple dashboards.

Event Messaging

Javascript events

View certain interactions from the iframe out to the parent frame via javascript events. Events will have the following shape:

type EmbedEvent<Payload> = {
  payload: Payload
  description: string
  name: EmbedEventName
}

Omni currently supports the following events:

Filter event: This will trigger when a user applies a filter to a document within an iframe Payload:

{
  'users.id': {
    filter: {
      is_negative: false,
      kind: 'EQUALS'
      ...
    },
    asJsonUrlSearchParam: 'f--users.id=%7B"is_inclusive"%3Afalse%2C"is_negative"%3Afalse%2C"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B"3"%5D%7D'
  }
}

Dashboard download: This will trigger when a user downloads the dashboard Payload:

userId: string - id of the user who downloaded the dashboard
  dashboard: {
    filters: {
      [filterName: string]: {
        filter: Filter object - complex object representing the filter
        asJsonUrlSearchParam: string - filter as a JSON URL search param that can be used in dashboard urls
      }
    }
    href: string  - full url of the dashboard
    urlId: string - id of the dashboard used in the url
    path: string  - path to the dashboard
    title: string - title of the dashboard
  }
  format: string  - one of 'pdf', 'csv', 'xlsx'

Tile download event: This will trigger when a user downloads a given tile on a dashboard Payload:

userId: string - id of the user who downloaded the dashboard
  dashboard: {
    filters: {
      [filterName: string]: {
        filter: Filter object - complex object representing the filter
        asJsonUrlSearchParam: string - filter as a JSON URL search param that can be used in dashboard urls
      }
    }
    href: string  - full url of the dashboard
    urlId: string - id of the dashboard used in the url
    path: string  - path to the dashboard
    title: string - title of the dashboard
  }
  format: string  - one of 'csv', 'xlsx', 'png'
  tile: {
    id: string - id of the tile
    title: string - title of the tile
    appliedFilters: { - filters applied to the tile
      [filterName: string]: {
        filter: Filter object - complex object representing the filter
        asJsonUrlSearchParam: string - filter as a JSON URL search param that can be used in dashboard urls
      }
    }
  }

Dashboard size event: This will trigger on dashboard load to give the size of the frame, allowing users to dynamically size the iframe. Payload:

type EmbedSizeEvent = {
  payload: {width?: number, height?: number}
  description: `returns a {width?: number, height?: number} object representing the total height of the document`
  name: 'size'
}

Dashboard status event: This will send the dashboard status to the parent frame, with a status of loading, running, done, or error.

{
  description: `Sends the dashboard status to the parent window.
  The status can be one of the following:
  - loading: the dashboard is still loading
  - running: the dashboard is running queries
  - done: the dashboard has finished loading
  - error: the dashboard has encountered an error
  `,
  name: EmbedEventName.Status,
  payload: { ...payload },
}

Post Messages

In addition to javascript events, users can send post messages from markdown or table visualizations. These can be observed by listeners in the parent frame to trigger certain actions, such as popping open custom drill modals or passing through certain data from Omni to the parent frame.

Table Visualizations

Within the table visualization, if a user clicks on the field level settings, then the display tab, and updates display as to link, then update URL to Embed Event. This will allow a user to give an embed event name, which will be triggered on a click to send a message out to the parent frame.

Markdown Visualizations

Using a tag for a custom element in markdown, we can send post messages from the iframe to the parent frame. This can be done upon a click to the corresponding aspect of the markdown visualization. To include it, you can include the following tag:

<omni-message event-name="product-image-click" event-data="{{products.name.raw}},{{products.retail_price.raw}},{{products.sku.raw}}">

Within this tag, you can set the event name, as well as the data that will be sent out to the parent frame.

Custom Theme Properties

Custom themes are currently only available for dashboards. There are two ways to create and use custom themes: directly on a dashboard or through the url.

Advanced If you intend to make the theme dynamic with some external logic then adjusting the url theme properties using the customTheme parameter is also available to use.

Property Name	Description
dashboard-background	The background color of the embedded dashboard. Any valid CSS "background" property value is acceptable.
dashboard-tile-background	The background color of the embedded dashboard's tiles. Any valid CSS "background" property value is acceptable.
dashboard-tile-text-body-color	The text color of primary text in the embedded dashboard's tiles. Primary text refers to the tile title of most tiles or the single value of single value tiles.
dashboard-tile-text-secondary-color	The text color of secondary text in the embedded dashboard's tiles. Any valid CSS "color" property value is acceptable.
dashboard-tile-border-color	The border color of the embedded dashboard's tiles. Any valid CSS "color" property value is acceptable.
dashboard-tile-border-radius	The border radius of the embedded dashboard's tiles. Any valid CSS "border-radius" property value is acceptable.
dashboard-tile-border-style	The border style of the embedded dashboard's tiles. Any valid CSS "border-style" property value is acceptable.
dashboard-tile-border-width	The border width of the embedded dashboard's tiles. Any valid CSS "border-width" property value is acceptable.
dashboard-tile-title-font-size	The font size of the embedded dashboard tiles' titles. Any valid CSS "font-size" property value is acceptable.
dashboard-tile-title-font-weight	The font weight of embedded dashboard tiles' titles. Any valid CSS "font-weight" property value is acceptable.
dashboard-tile-title-text-color	The text color of title text in the embedded dashboard's tiles. Any valid CSS "color" property value is acceptable.
dashboard-tile-title-font-family	The font family of title text in the embedded dashboard's tiles. To use a custom font, pass a link to a remote woff2 file.
dashboard-tile-text-body-font-family	The font family of body text in the embedded dashboard's tiles. To use a custom font, pass a link to a remote woff2 file.
dashboard-tile-text-code-font-family	The font family of a markdown <code> element in the embedded dashboard's markdown tiles. To use a custom font, pass a link to a remote woff2 file.
dashboard-key-color	The key color of the embedded dashboard. Used on filter "Update" buttons and other key elements.
dashboard-key-text-color	The key text color of the embedded dashboard. Used on the text of filter "Update" buttons and other key elements.
dashboard-control-background	The background color of the filter controls on the dashboard. Any valid CSS "background" property value is acceptable.
dashboard-control-popover-background	The background color of the popover that is shown when you interact with a filter control. Any valid CSS "background" property value is acceptable.

Getting woff2 file links from Google Fonts

Font family properties like dashboard-tile-title-font-family support links to a remote woff2 file. A typical use case is to link to a woff2 file from a Google Font. To grab the link to a Google Font woff2 file, perform the following steps:

1. Go to fonts.google.com and click on your font of choice. For this example, we’ll be using the “Yarndings 12” font.

2. That click should take you to a font specimen page. On that font specimen page, click the “Get font” button.

3. After pressing “Get font” you’ll be taken to a selection page. On that selection page, click the “Get embed code” button.

4. Go to the fonts.googleapis.com link that appears in the third <link> element of the example embed code. Note that some Google Fonts allow you to customize font weight and font style in the left panel so feel free to filter down to the exact font styling you’d like.

5. Find the @font-face at-rule under labeled “latin” and copy the src property url(...).

6. Pass that url(...) value into the appropriate customTheme property when generating your Omni SSO embed link.

  {
    "dashboard-tile-title-font-family": "url(https://fonts.gstatic.com/s/yarndings12/v2/55xreyp2N8T5P2LJbZAlkY9s9pjNAWZEnA.woff2)",
  }

7. And voilà!