@jitto/analyze-embed

Guide: GUIDE.md, shipped in this package, takes you from nothing to an embedded dashboard.

Show a Jitto dashboard inside your own web app, for your own signed-in users, in React or plain JavaScript. Each user sees only the rows Jitto's row rules allow them; your page never holds a Jitto password or secret.

Status: 0.4. Expect small changes before 1.0. What changed in each version: CHANGELOG.md.

Not available yet: filterChanged fires for the filters your app sets (source: 'host') only; changes the user makes in the filter bar are not reported yet. Everything else in this README works as described.

Filters need your Jitto server to list them. Pass filters (or call setFilters) only once your Jitto server returns filter_bar in its token answer. Until then every filter is refused: a mount with filters ends with failed and the dashboard does not load. In 0.2.0 the filters option was ignored instead.

Install

npm install @jitto/analyze-embed

One package, two entry points: @jitto/analyze-embed (plain JavaScript) and @jitto/analyze-embed/react (React). Both run on the same core, so the same options give the same events. TypeScript declarations are included.

Quickstart

1. Get three things from your Jitto tenant administrator: your tenant's Jitto host (for example https://example-tenant.jittocloud.com; -uat and -dev hosts for the other environments), the id of the dashboard, and confirmation that your website's origin (for example https://portal.client.example) is on the tenant's allowed origins. Origins are exact: https://, host, optional port.
2. Install: npm install @jitto/analyze-embed.
3. Write fetchToken (see Tokens): it asks Jitto for a dashboard token with the signed-in user's own access token from your sign-in library.
4. Mount the dashboard:

import { JittoDashboard } from '@jitto/analyze-embed/react';

export function DeskOverview() {
  return (
    <JittoDashboard
      dashboardId="3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"
      embedOrigin="https://example-tenant.jittocloud.com"
      fetchToken={fetchToken} // see Tokens: it sends the user's own access token
      style={{ height: 600 }}
    />
  );
}

Open the page as a test user. You see that user's rows.

React: <JittoDashboard>

import { useRef } from 'react';
import { JittoDashboard } from '@jitto/analyze-embed/react';
import type { JittoDashboardHandle } from '@jitto/analyze-embed';

export function Report() {
  const dashboard = useRef<JittoDashboardHandle>(null);
  return (
    <JittoDashboard
      ref={dashboard}
      dashboardId="3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"
      embedOrigin="https://example-tenant.jittocloud.com"
      fetchToken={fetchToken}
      theme={{ mode: 'light', colorPrimary: '#0b7a75' }}
      onLoaded={({ durationMs }) => console.log(`loaded in ${durationMs} ms`)}
      onFailed={({ reason, message }) => console.warn(reason, message)}
      onSizeChanged={({ height }) => console.log('frame height', height)}
      className="report"
    />
  );
}

How prop changes apply:

• A change to dashboardId or embedOrigin remounts the dashboard.
• theme is compared by value. An equal value does nothing, so an inline object is safe. A different value is applied in place, as setTheme would. Removing theme changes nothing: a theme can be replaced, not removed, so the dashboard keeps its current look.
• filters is compared by value too, key order ignored, so filters={{ Ccy: userCcy }} is safe inline. A different value is applied as setFilters would; a refusal calls onFilterRejected and the filters in effect stay. Removing filters changes nothing; pass {} to clear every filter your app set. Use either the prop or the handle's setFilters for filters, not both.
• Callbacks, the token function and the deadlines are read when used. A new function takes effect from its next use, with no remount.

The component mounts in the browser only. In a server-rendered app, render it on the client.

Plain JavaScript: mountJittoDashboard

import { mountJittoDashboard } from '@jitto/analyze-embed';

const element = document.getElementById('dashboard');
if (!element) throw new Error('no #dashboard element on the page');

const dashboard = mountJittoDashboard(element, {
  dashboardId: '3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0',
  embedOrigin: 'https://example-tenant.jittocloud.com',
  fetchToken,
  onFailed: ({ reason, message }) => console.warn(reason, message),
});

const stop = dashboard.on('loaded', ({ durationMs }) => console.log(`loaded in ${durationMs} ms`));

// Later, when your app's own controls change:
export function useDarkTheme() {
  dashboard.setTheme({ mode: 'dark' });
}

// When your page or view goes away:
export function teardown() {
  stop();
  dashboard.unmount();
}

mountJittoDashboard(element, options) takes the same options and callbacks as the React props (except className, style and ref) and returns a handle:

The setFilters promise always settles. It rejects with a SetFiltersError whose outcome is:

• deadline: the filters were not applied within loadDeadlineMs. failed fires with reason network and the mount ends. A dashboard that is not displayed then (in a hidden tab) gets another loadDeadlineMs instead.
• ended: the mount ended first, or had already ended.
• replaced: a later setFilters call came before this one was applied.

If the dashboard refuses a name or a value, setFilters rejects with a FilterError instead and applies nothing. Its code is unknown_filter or invalid_filter_value, filterNames lists the refused names and knownFilterNames lists every filter the dashboard has. filterRejected fires with the same error. A call made before the first token arrives waits for it: the names are checked against the token's filter list then, in call order.

Tokens

Your page asks Jitto for a short-lived dashboard token with the signed-in user's own access token, the one your sign-in library already holds. That token is the user's identity: there is no token endpoint on your backend, no shared account and no secret, and your code never states who the user is or what they may see.

1. The SDK calls your fetchToken(dashboardId, signal) on mount and again at 80 % of the token's lifetime (at most about 24.8 days later, the longest delay a browser timer holds).

2. Your fetchToken sends the user's own access token to Jitto, from the browser:

   POST /api/v1/embed-tokens HTTP/1.1
   Host: example-tenant.jittocloud.com
   Origin: https://portal.client.example
   Authorization: Bearer <the user's own access token>
   Content-Type: application/json
   
   {"dashboard_id": "3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"}
   

3. Jitto checks the token against your tenant's identity provider (issuer, signature, audience, expiry), reads the user's groups from it, and applies the row rules your tenant administrator stored in Jitto. It checks the Origin against your tenant's allowed origins, and answers the browser's CORS preflight only for those origins.

4. Jitto answers with a dashboard token that lives 5 minutes. The answer has Cache-Control: no-store:

   {
     "token": "<opaque>",
     "dashboard_id": "3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0",
     "embed_url": "https://example-tenant.jittocloud.com/embed",
     "expires_in": 300
   }
   

5. Your fetchToken hands it to the SDK with the SDK's field names (dashboardId, embedUrl, expiresIn, and filterBar when the answer has filter_bar, the dashboard's filters), values unchanged. The SDK checks the answer itself and refuses a wrong one with reason token.

On an error Jitto answers with an HTTP status and a problem body (code, correlation_id), and with Retry-After on a 429. A token that is expired, for another audience or from another issuer is refused with 401 unauthenticated (reason token); a user in no group the row rules read gets 403 no_group (reason permission). Your tenant administrator registers your identity provider with Jitto once.

Your fetchToken rejects on an HTTP error with the status and the API's code. This exact code is tested against 401, 403, 422, 429, 502 and malformed answers. getAccessToken() is your sign-in library's:

async function fetchToken(dashboardId, signal) {
  const r = await fetch('https://example-tenant.jittocloud.com/api/v1/embed-tokens', {
    method: 'POST',
    signal,
    cache: 'no-store',
    headers: {
      Authorization: `Bearer ${await getAccessToken()}`, // the signed-in user's own token, from your sign-in library
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ dashboard_id: dashboardId }), // nothing else: Jitto reads who the user is from the token
  });
  const body = await r.json().catch(() => null);
  if (!r.ok) {
    const retryAfter = Number(r.headers.get('Retry-After'));
    throw Object.assign(new Error(`token request failed with HTTP ${r.status}`), {
      status: r.status,
      code: body?.code,
      correlationId: body?.correlation_id,
      retryAfterSeconds: retryAfter > 0 ? retryAfter : undefined,
    });
  }
  if (!body || typeof body !== 'object') return body; // the SDK refuses it with reason `token`
  const answer = { token: body.token, dashboardId: body.dashboard_id, embedUrl: body.embed_url };
  if ('expires_in' in body) answer.expiresIn = body.expires_in;
  if ('filter_bar' in body) answer.filterBar = body.filter_bar; // the dashboard's filters; without it, filters are refused
  return answer; // the SDK checks it and refuses a wrong answer with reason `token`
}

Events

Subscribe with the on… props or callbacks, or with handle.on(name, handler).

reason is one of token, permission, network and not_found.

Size

Give the container a height, such as the window's height less your page's header. The dashboard frame takes the dashboard's own height within it:

• never taller than the container: a taller dashboard scrolls inside the frame, so its filter bar, messages and dialogs stay on screen;
• never shorter than the container or 600 px, whichever is less, so a short dashboard keeps room for its filter bar and dialogs. Below that, the frame ends where the dashboard does.

sizeChanged reports the frame's size on the page. You may size your container to it, so no space is left below a short dashboard; that never makes the frame taller than the container was.

Filters

Filters set what the dashboard shows first, by the names its filter bar uses (for example Ccy, Trade Date & Time), exactly, case included.

• Set them on mount with filters, and later with setFilters (or a new filters prop).
• The names come with the token: Jitto's answer lists the dashboard's filters in filter_bar, each a name and a kind, and your fetchToken passes it on as filterBar. Without it every filter is refused.
• Send a filter only to dashboards that have it. A name the dashboard lacks is refused with a FilterError, and on mount the dashboard does not load; it is never ignored, so the dashboard never shows unfiltered data.
• A value is a string, number or boolean, a list (several values), a date range { from, to } (two days written YYYY-MM-DD, such as 2026-06-30, from on or before to, both included), or null to clear the filter. Which values a filter takes depends on its kind: a list of values on a multiple-choice filter, exactly two numbers [min, max] on a numeric range, a date range only on a date-range filter.
• A list takes at most 1 000 values and a string at most 256 characters, the limits of the dashboard and of Jitto's export API, so download() is never refused for them. A value over them is refused with invalid_filter_value, and so is a call that sets more than 50 filters. A filter whose name has more than 255 characters cannot be set.
• setFilters replaces every filter your app set: a name you leave out goes back to the dashboard's own default.
• The filters travel in the dashboard's address, by name, which holds at most 4 096 bytes of them once encoded. A call that needs more (a long list on a multiple-choice filter) is refused at once with invalid_filter_value, naming the filters too long on their own (name and value), else its list-valued filters, else every filter.
• Like any address, the dashboard's can appear in your Jitto host's access logs, filter names and values included. Pass the values a user picks (a currency, a date), never a secret or personal data.
• download() gives the file with the filters in effect in the dashboard: those your app set, and the user's own filter-bar changes made since.
• Filters narrow the view. They are not security. A user can change them in the filter bar. What a user may see is decided only by the row rules in Jitto.
• Today setFilters reloads the dashboard inside the frame. Your page stays mounted and no new token is requested, but the user's own filter-bar changes and scroll position are reset. Set filters on mount when you can.

Theme

Theme tokens change colours, font and light or dark. Jitto keeps the layout; there is no CSS hook.

Colours are CSS colour strings (#1a73e8, rgb(…)). Anything else is ignored with a console warning. setTheme never reloads the frame.

Errors and troubleshooting

Every failure arrives as one failed event with one of four reasons. status, code and correlationId come from the API when it answered; quote the correlationId when you ask Jitto for help.

Other symptoms:

Supported browsers and frameworks

Proposed for 1.0.0; the end-to-end tests confirm the list before release.

• Browsers: the current and previous major versions of Chrome, Edge, Firefox and Safari. Pages must be served over https://, including local development (for example https://localhost:5173).
• React: 18 and 19, through @jitto/analyze-embed/react.
• Everything else (Angular, Vue, server-rendered pages, no framework): use mountJittoDashboard from @jitto/analyze-embed. Dedicated wrappers may follow on the same core.
• TypeScript: declarations are included. Every option, event and payload is typed.

Versioning

• The package follows semantic versioning. A breaking change to an option, event, payload or failure reason is a new major version.
• The package's major version matches the embed API's path version: @jitto/analyze-embed 1.x talks to /api/v1/ only. Additive API changes stay in v1.
• A deprecated API version answers with Deprecation, Sunset and Link headers for at least 90 days before it is removed.

Full guide and API reference

• The embedding guide, GUIDE.md in this package: the whole flow, the tenant administrator's settings, and a security checklist.
• The API reference, generated from the embed API's OpenAPI 3.1 contract. Your Jitto contact provides it with your tenant.

Both move to the Jitto docs site before 1.0.0, and this section then links there.