Quick Start

Introduction

Semaphor is an embedded analytics platform for customer-facing dashboards. You build dashboards in the Semaphor Console and embed them in your app with a few lines of code.

This decouples analytics from your product code. Update dashboards, add visuals, and change data logic — all without redeploying your app. Semaphor supports natural language, SQL, and Python for data logic.

Prerequisites

A Semaphor account — sign up here
A data source: PostgreSQL, MySQL, MS SQL, ClickHouse, BigQuery, Snowflake, or S3

Step 1: Create a Project and Connect Your Data

Log in to the Semaphor Console
Create a new project
Go to the Connections tab, click Add Connection, and connect your database
Note your projectId and projectSecret from the project settings

See the Connectors section for database-specific setup guides.

Step 2: Create a Dashboard

From the console, create a new dashboard
Add visuals using natural language, SQL, or Python
Note your dashboardId from the dashboard URL or settings

Step 3: Embed the Dashboard

The fastest way to embed is with an iframe. It's zero dependency — you don't need to bundle any Semaphor libraries or SDKs in your app. Everything runs inside the iframe. This means you can embed Semaphor dashboards in any app that supports iframes: Notion, Confluence, WordPress, Retool, internal tools, or your own product.

Fetch a token server-side, then render the iframe.

src/App.tsx

import { useEffect, useState } from 'react';
 
const PROJECT_ID = 'your-project-id';
const PROJECT_SECRET = 'your-project-secret';
const END_USER_ID = 'end-user-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>();
 
  useEffect(() => {
    async function fetchToken() {
      const response = await fetch(TOKEN_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          projectId: PROJECT_ID,
          projectSecret: PROJECT_SECRET,
          endUserId: END_USER_ID,
          initialDashboardId: INITIAL_DASHBOARD,
        }),
      });
      const token = await response.json();
      if (token?.accessToken) setAuthToken(token);
    }
    fetchToken();
  }, []);
 
  if (!authToken) return <div>Loading...</div>;
 
  const url = `https://semaphor.cloud/embed/${authToken.accessToken}?showAssistant=true&showControls=true&currentTheme=light`;
 
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <iframe src={url} width="100%" height="100%" />
    </div>
  );
}
 
export default App;

Do not expose projectSecret in client-side code in production. Generate tokens from your backend server.

Embedding Options

The iframe above is the simplest way to embed. For deeper integration, use the Semaphor SDK.

Method	Best For	Guide
iFrame	Fastest setup, zero dependencies	iFrame Guide
React SDK	Component-level control, event handlers	React Guide
Vue SDK	Vue applications	Vue Guide
Web Component	Framework-agnostic	Web Component Guide

Quick Start

Introduction

Step 1: Create a Project and Connect Your Data

Step 2: Create a Dashboard

Step 3: Embed the Dashboard

Embedding Options

What's Next

Self-Service Analytics

Custom Visuals

Connectors

Token Options

Themes & Styles

On this page