@omni-co/embed v0.3.13

Omni Embed SSO Typescript SDK

Install

npm:

npm install @omni-co/embed

yarn:

yarn add @omni-co/embed

Basic Example

import { embedSsoDashboard } from "@omni-co/embed";

// This creates a signed embed sso link for a dashboard
// in the omni account named Acme.
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "wile.e@coyote.co",
  name: "Wile E",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

Kitchen Sink Example

import { embedSsoDashboard } from "@omni-co/embed";

// This creates a signed embed sso link for a dashboard
// in the omni account named Acme.
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "wile.e@coyote.co",
  entity: "cartoon",
  name: "Wile E",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
  prefersDark: "system",
  theme: "vibes",
  userAttributes: { tool: "anvil" },
});

embedSsoDashboard

This is the type signature for the embedSsoDashboard function:

type EmbedSsoProps = {
  // Short GUID of the dashboard. Can be obtained via the dashboard's url.
  contentId: string;

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  externalId: string;

  // Required name of the external user.
  name: string;

  // Required Omni organization which contains the dashboard.
  organizationName: string;

  // Signing secret available to Omni admins.
  secret: string;

  // Optional identifier to associate the user with an external
  // organization or system.
  entity?: string;

  // Optional user attributes to be passed to user associated with the
  // externalId. User attributes must be created in Omni before being
  // defined and given a value here.
  userAttributes?: Record<string, string | string[] | number | number[]>;

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string;

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string;

  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
  filterSearchParam?: string;

  // Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
  linkAccess?: string;

  // Optional custom theme property that styles the embedded dashboard.
  customTheme?: CustomThemeProperties;
};