iFrame

Learn how to use the iframe to embed the self-service analytics experience in your app.

Overview

Zero-Dependency Embeds with iFrame

When you embed Semaphor using an iFrame, you don’t need to bundle any analytics libraries, UI components, or dependencies into your application. Everything: visualization libraries, state management, styling, and interactive features lives fully within the Semaphor frame.

This gives you two major advantages:

No extra dependencies in your codebase Your app stays lightweight. You’re not shipping chart libraries, SDKs, or custom components just to display analytics. Semaphor handles all of that inside the frame.
Analytics stays isolated from your product code There’s no risk of CSS collisions, version conflicts, or package bloat. Semaphor runs in its own sandbox, so your product and your analytics never step on each other.

1. Obtain the Auth Token

Before rendering an iframe, you need to retrieve an Auth Token. This token ensures secure access to your embed session.

const PROJECT_ID = 'your-project-id';
const PROJECT_SECRET = 'your-project-secret';
const END_USER_ID = 'tenant-user-id';
const SEMANTIC_DOMAIN_ACCESS = {
  mode: 'include',
  domains: ['your-semantic-domain-id'],
} as const;
const INITIAL_DASHBOARD = 'your-dashboard-id';

const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(tokenRequest),
});

const authToken = await response.json();

Do not expose projectSecret in client-side code in production. Use a backend service to fetch the token securely.

See the Token API reference for all available options including security policies, user provisioning, and multi-tenancy.

2. Build the Embed URL

Use the token to generate the iframe URL. You can control the experience with query parameters.

const url = `https://semaphor.cloud/embed/${authToken?.accessToken}?showAssistant=true&showControls=true&currentTheme=light`;

3. Render the Iframe

Render the iframe inside a responsive container.

<iframe src={url} width="100%" height="100%" />

src/App.tsx

import { useEffect, useState } from 'react';

const PROJECT_ID = 'your-project-id';
const PROJECT_SECRET = 'your-project-secret';
const END_USER_ID = 'tenant-user-id';
const ALLOWED_SEMANTIC_DOMAINS = ['your-semantic-domain-id'];
const INITIAL_DASHBOARD = 'your-dashboard-id';

const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';

type AuthToken = {
  accessToken: string;
};

function App() {
  const [authToken, setAuthToken] = useState<AuthToken>();

  const tokenRequest = {
    projectId: PROJECT_ID,
    projectSecret: PROJECT_SECRET,
    endUserId: END_USER_ID,
    semanticDomainAccess: SEMANTIC_DOMAIN_ACCESS,
    initialDashboardId: INITIAL_DASHBOARD,
    allowEdit: true, // This will allow the user to edit the dashboard
    tokenExpiry: 60 * 30, // 30 minutes
    // sls: 'corp_a', // This will route the user to the corp_a schema
  };

  useEffect(() => {
    async function fetchToken() {
      try {
        const response = await fetch(TOKEN_URL, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify(tokenRequest),
        });
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }

        const token = await response.json();
        if (token?.accessToken) {
          setAuthToken(token);
        }
      } catch (error) {
        console.error('There was an error!', error);
      }
    }
    fetchToken();
  }, []);

  const url = `https://semaphor.cloud/embed/${authToken?.accessToken}?showAssistant=true&showControls=true&currentTheme=light`; 

  if (!authToken) {
    return <div>Loading...</div>;
  }

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <iframe src={url} width="100%" height="100%" />
    </div>
  );
}

export default App;

URL Parameters

showAssistant: Enable the AI assistant panel in the embed (true/false)
showControls: Show header controls for the embed (true/false)
currentTheme: Set theme for the embed (light, dark, or system)

Append these as query parameters to the embed URL as needed.

Key Considerations

Security: Always generate tokens server-side; never expose secrets in client code.
Sizing: Wrap the iframe in a container with explicit width/height for proper layout.
Token expiry: Use tokenExpiry in your token request to control session duration.

Single Visual Embedding

Instead of embedding a full dashboard, you can embed a single visual -- a specific chart, KPI, or table -- from any dashboard. This is useful when you want to display an individual metric or visualization inline within your application.

Build the Visual URL

The URL includes both the dashboard ID and the visual (card) ID:

const DASHBOARD_ID = 'your-dashboard-id';
const VISUAL_ID = 'your-visual-id';

const url = `https://semaphor.cloud/view/dashboard/${DASHBOARD_ID}/visual/${VISUAL_ID}?token=${authToken?.accessToken}&theme=light`;

You can find the visual ID by opening the dashboard in Semaphor, clicking on the card, and copying the ID from the card settings.

Render the Visual

Use the same iframe pattern as dashboard embedding:

<div style={{ width: '400px', height: '300px' }}>
  <iframe src={url} width="100%" height="100%" style={{ border: 'none' }} /> // [!code highlight]
</div>

Visual URL Parameters

Parameter	Type	Description
`token`	string	Auth token (same token used for dashboard embedding)
`theme`	`light` \| `dark`	Visual theme
`filterValues`	JSON array	Dashboard-level filter values to apply
`controlValues`	JSON object	Control values to apply
`selectedSheetId`	string	Sheet containing the visual (required if the visual is not on the first sheet)
`cardTitle`	string	Override the page title

iFrame

On this page