# Perfetto UI embedding API reference

This page is a reference for the `postMessage` and URL parameter surface used to
embed the Perfetto UI (`ui.perfetto.dev`) inside an `<iframe>` on a host page.

For a task-oriented walkthrough of the embedding flow, see
[Embedding the Perfetto UI](/docs/visualization/embedding-the-ui.md). For the
`window.open()` (new browser tab) variant and for sharing / `appStateHash`
details, see [Deep linking to the Perfetto UI](/docs/visualization/deep-linking-to-perfetto-ui.md).

NOTE: This is a reference, not a tutorial. Fields and message types not listed
here are not part of the supported surface.

## Message channel

The host page communicates with the embedded UI via `window.postMessage`. The
UI's message handler only acts on messages whose `event.source` is one of:

| `event.source`            | When                                                              |
| ------------------------- | ---------------------------------------------------------------- |
| `window.parent`           | The UI runs inside the host's `<iframe>` (the embedding case).   |
| `window.opener`           | The host launched the UI with `window.open()` (new-tab case).    |
| A window this UI opened   | `event.source.opener === window`.                                |

For iframe embedding, the UI's `window.parent` is the host page, so the host
posts messages to `iframe.contentWindow` and the UI accepts them.

Because the channel is not buffered, a handshake is required before posting a
trace:

1. The host repeatedly posts the string `'PING'` to the UI window.
2. The UI replies with the string `'PONG'`. The reply is sent to `'*'` and is
   sent only once the UI's message listener is registered **and**
   `document.readyState === 'complete'`.
3. The host listens for `'message'` events; on the first `data === 'PONG'` from
   the UI window it stops pinging and posts the trace.

A robust host pings on an interval (for example every 50-250ms) and clears the
interval on the first `PONG`.

A message with `{perfettoIgnore: true}` is ignored on purpose. This lets a host
multiplex other traffic over the same channel.

## Opening a trace

To open a trace, post an object with a single `perfetto` key:

```js
iframe.contentWindow.postMessage({perfetto: {buffer, title}}, '*');
```

Fields of the `perfetto` object:

| Field          | Type                                                      | Required | Default | Meaning                                                                                                                              |
| -------------- | -------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `buffer`       | `ArrayBuffer`                                             | Yes      | -       | Raw trace bytes, e.g. from `fetch(...).then(r => r.arrayBuffer())`.                                                                  |
| `title`        | `string`                                                 | Yes      | -       | Trace title shown in the UI.                                                                                                          |
| `fileName`     | `string`                                                 | No       | -       | Suggested file name if the user downloads the trace.                                                                                 |
| `url`          | `string`                                                 | No       | -       | Sharing URL. See sharing details in [Deep linking to the Perfetto UI](/docs/visualization/deep-linking-to-perfetto-ui.md).          |
| `appStateHash` | `string`                                                 | No       | -       | 40-char hex hash; restores saved UI state from GCS. See [Deep linking to the Perfetto UI](/docs/visualization/deep-linking-to-perfetto-ui.md). |
| `localOnly`    | `boolean`                                                | No       | `true`  | Defaults to `true` for posted traces, which disables download and share. Set `false` to enable them.                                |
| `keepApiOpen`  | `boolean`                                                | No       | `false` | If `true`, the listener stays active so the host can post more traces later. If `false`/omitted, the handler removes its own message listener after the first trace (avoids duplicate posts, b/182502595). |
| `pluginArgs`   | `{[pluginId: string]: {[key: string]: unknown}}`         | No       | -       | Passed to plugins' `onTraceLoad()`.                                                                                                  |

### Bare ArrayBuffer shorthand

A bare `ArrayBuffer` (`event.data instanceof ArrayBuffer`) is also accepted. It
is treated as `{title: 'External trace', buffer}`.

## Scroll to time range

Post the following message after the trace is loaded to scroll/zoom the viewport
to a time range:

```js
iframe.contentWindow.postMessage(
    {perfetto: {timeStart, timeEnd, viewPercentage}}, '*');
```

| Field            | Type     | Required | Meaning                                          |
| ---------------- | -------- | -------- | ------------------------------------------------ |
| `timeStart`      | `number` | Yes      | Range start, **absolute trace time in seconds** (not relative to trace start; clamped to trace bounds). |
| `timeEnd`        | `number` | Yes      | Range end, **absolute trace time in seconds**.   |
| `viewPercentage` | `number` | No       | Fraction of the viewport the range should fill, in `(0.0, 1.0]`. Out-of-range values are ignored and replaced by `0.5`. |

The handler retries internally (roughly 20 times at 200ms intervals) until the
trace is ready, so this message can be posted shortly after the trace without
waiting for an explicit "loaded" signal.

## String commands

The handler understands these string messages:

| Message                 | Effect                                  |
| ----------------------- | --------------------------------------- |
| `'PING'`                | Replies with `'PONG'` (sent to `'*'`).  |
| `'SHOW-HELP'`           | Opens the help dialog.                  |
| `'RELOAD-CSS-CONSTANTS'`| Reloads CSS constants.                  |

## URL parameters

Set these on the iframe `src`. The route is hash-based:
`https://ui.perfetto.dev/#!/?key=val&...`.

| Parameter         | Value                          | Effect                                                                                                                              |
| ----------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `mode`            | `embedded`                     | Enables embedded mode: the sidebar is **disabled entirely** (not just hidden) and the file-drop handler is not installed. Use this when embedding. |
| `hideSidebar`     | `true`                         | Hides the sidebar visually without fully disabling it.                                                                             |
| `url`             | `<https url>`                  | UI fetches a public trace itself (requires CORS allowing the UI origin). Alternative to `postMessage` for public traces.           |
| `s`               | `<hash>`                       | Loads a permalink (saved state).                                                                                                   |
| `visStart`        | `<ns>`                         | Initial viewport start, raw **nanosecond** timestamp (as in SQL tables). Pair with `visEnd`.                                       |
| `visEnd`          | `<ns>`                         | Initial viewport end, raw **nanosecond** timestamp.                                                                               |
| `ts`              | `<ns>`                         | Timestamp of the slice to select on load, in **nanoseconds**. Linking is by `ts`+`dur`, **not** by `id` (ids are unstable).        |
| `dur`             | `<ns>`                         | Duration of the slice to select on load, in **nanoseconds**.                                                                       |
| `pid`             | `<n>`                          | Process id used to disambiguate the slice selection.                                                                              |
| `tid`             | `<n>`                          | Thread id used to disambiguate the slice selection.                                                                               |
| `query`           | `<sql>`                        | Runs a SQL query on load (URL-encode the value).                                                                                  |
| `startupCommands` | `<url-encoded JSON array>`     | Runs UI commands after load, e.g. `[{id:'dev.perfetto.PinTracksByRegex', args:['.*CPU [0-3].*']}]`.                                |
| `enablePlugins`   | `<comma,list>`                 | Enables specific plugins by id.                                                                                                    |

NOTE: `visStart`/`visEnd` and `ts`/`dur` are raw **nanoseconds**, whereas the
`timeStart`/`timeEnd` `postMessage` fields are **seconds**.

NOTE: Slice selection is by `ts`+`dur` (plus optional `pid`/`tid`), never by
`id`, because ids are unstable across runs.

## Origin trust

If the posting origin is trusted, the trace opens immediately. The trusted set
is:

- Same-origin requests.
- `localhost`, `127.0.0.1`, and `[::1]` (so local dev embedding works with no
  prompt).
- A few hardcoded Google origins.
- Origins the user previously saved via "Always trust".

If the origin is **not** trusted, the UI shows a modal:

> `<origin>` is trying to open a trace file. Do you trust the origin?

with the options **No**, **Yes**, and **Always trust**. "Always trust" persists
the origin in `localStorage`.

Embedding from a production domain therefore shows users a one-time consent
prompt, unless you self-host the UI (same-origin => trusted).

Strings in `title` and `url` are sanitized to the character set
`[A-Za-z0-9.\-_#:/?=&;%+$ ]`.

## Constraints

- Does not work from `file://` URLs (browser security). Serve over `http(s)`.
- The host page must **not** be served with
  `Cross-Origin-Opener-Policy: same-origin`, which breaks the opener
  relationship.
- The UI is client-only. Posted traces stay in browser memory and are never
  uploaded.
- `ui.perfetto.dev` follows the latest release. If you need a fixed version,
  self-host the UI build to pin it. Self-hosting also makes your origin
  same-origin, so the consent modal is skipped.

## Source

The behavior above is defined in:

- [/ui/src/frontend/post_message_handler.ts](/ui/src/frontend/post_message_handler.ts)
- [/ui/src/public/route_schema.ts](/ui/src/public/route_schema.ts)