# Embed options

URL: /docs/developers/collect/embed-options

The browser SDK creates and manages an iframe using a public project ID, not Business Auth or an API key. The iframe creates its visitor session through Orvelt's public storefront API, so your website calls no API and hosts no session endpoint. [Website embed](/docs/developers/collect/website-embed) walks through installation.

## `orveltEmbed.configure` [#orveltembedconfigure]

Import it from `@orvelt/business`, or use the `OrveltEmbed` global provided by `opinion-embed.js`.

### Example [#example]

```ts
import { orveltEmbed } from '@orvelt/business';

const embed = orveltEmbed.configure({
  projectId: 'PROJECT_UUID',
  visibility: 'public',
  externalUserId: 'reference-42',
  attributes: { orderId: 'order-42', context: { tags: ['checkout'] } },
  onSubmitted: ({ isPrivate }) => console.log({ isPrivate }),
});
document.querySelector('#open-feedback')?.addEventListener('click', () => {
  void embed.open();
});
// Cleanup before replacing the form:
embed.unmount();
```

### Options [#options]

| Option | Default | Meaning |
| --- | --- | --- |
| `projectId` | Required | Published project UUID. Public configuration, not a credential. |
| `visibility` | `public` | Only `public` reviews or `private` feedback. Set by the business, not a visitor-facing toggle. |
| `externalUserId` | Omitted | Optional unverified reference. Trimmed, 1–256 characters, no control characters. |
| `attributes` | Omitted | Optional JSON metadata saved with the opinion and returned by the Business API. Accepts nested objects, arrays, strings, numbers, booleans, or `null`. Not shown in public reviews. |
| `origin` | `https://orvelt.com` | Optional storefront origin; override for staging or local development. |
| `sessionUrl` | Omitted | Identifier-only resume URL for this project and origin. See [Resume a session](#resume-a-session). |
| `onSubmitted` | Omitted | Receives `{ isPrivate }` after persisted completion. |
| `onSessionCreated` | Omitted | Receives an identifier-only resume URL after opening or renewing a session. Never includes its bearer secret. |
| `onClose` | Omitted | Called when the visitor closes the form: its close button, or Escape/backdrop click in a modal. With `mount()`, setting it shows the close button. |
| `closeButton` | See meaning | Shows the close button in the form's top-right corner. Defaults to `true` with `onClose` and `false` without it for `mount()`; always shown for `open()`. Set `false` to hide it while still handling `onClose`. |
| `appearance.accentColor` | Orvelt's accent | Hex color such as `#4f46e5` (3 or 6 digits) for buttons, focus rings, and highlights. Text color is chosen for contrast. |
| `appearance.colorScheme` | `light` | `light`, `dark`, or `system` (follows the visitor's device). |
| `appearance.radius` | Orvelt's radius | Integer from 0 to 24: corner radius of fields and buttons, in pixels. |
| `onReady` | Omitted | Called when the iframe has loaded and is ready. |
| `onError` | Omitted | Called once if the iframe fails to load or is not ready within 15 seconds. |

Invalid options throw from `configure()`. `attributes` must be JSON: functions, `undefined` values, `BigInt`, and non-finite numbers are rejected. The SDK places metadata in the iframe URL fragment rather than a request query, so never include secrets. With `sessionUrl`, the existing session keeps its original metadata.

### Methods [#methods]

| Method | Meaning |
| --- | --- |
| `open()` | Shows the form in an Orvelt `<dialog>` and returns a promise for its iframe. Reopening after a close shows the same form; after a submission it starts a new opinion. Replaces a mounted iframe from the same embed. |
| `mount(elementOrSelector)` | Inserts the iframe into your connected element and returns a promise for it. Concurrent mounts into the same slot share the iframe. Replaces an open modal from the same embed. |
| `close()` | Closes the modal, keeping its progress. Calls `onClose`. |
| `unmount()` | Removes the iframe or modal and its listeners. The next `mount()` or `open()` without `sessionUrl` creates a new visitor session. |

Configuration is SSR-safe; call `open()` and `mount()` only in the browser. One configured embed shows at most one form at a time. There is no API-key option, session provider, identity setter, tracking, or automatic launcher.

### Styling [#styling]

Appearance options are applied inside the iframe, because your stylesheets cannot reach a form on another origin. The elements the SDK creates on your page carry classes you can style:

| Class | Element |
| --- | --- |
| `orvelt-modal` | `<dialog>` created by `open()`; its backdrop is `.orvelt-modal::backdrop`. |
| `orvelt-modal__iframe` | Iframe inside the modal. |
| `orvelt-iframe` | Iframe created by `mount()`. |

The SDK's default styles use zero-specificity selectors in an adopted stylesheet, so they work under a strict `style-src` CSP, any selector of yours overrides them, and CSS resets such as Tailwind's preflight do not move the modal. The SDK sets the iframe's `height` inline as the form resizes; cap it with `max-height` rather than a fixed height.

```css
.orvelt-modal {
  border-radius: 20px;
}

.orvelt-modal::backdrop {
  background: rgb(15 23 42 / 0.6);
}
```

### Attach to an existing iframe [#attach-to-an-existing-iframe]

Prefer `configure()` and `mount()` so the SDK owns resizing, callbacks, and cleanup. For an existing iframe or custom host, `opinionEmbedUrl(options)` creates the reusable iframe URL without fetching. A direct iframe can use `https://orvelt.com/embed/opinion/PROJECT_UUID?visibility=public`, optionally with an encoded `externalUserId` query parameter.

`attachOpinionEmbed(iframe, options)` adds resizing and the same callbacks, including `onClose`, to an existing iframe, validates message origin and source, and returns a disposer. To show the close button in such an iframe, build its URL with `opinionEmbedUrl({ ...options, closeButton: true })`. Completion carries only visibility, not author data.

## Visitor sessions [#visitor-sessions]

Each fresh mount gets its own visitor session for the project. A session lasts one hour and accepts one completed opinion; reopening can show a draft or its completion, never a second opinion.

### Identity and limits [#identity-and-limits]

The iframe keeps its session credential in its own origin's `sessionStorage`. Without a detected Orvelt account, name and email verification is required before the opinion form opens, with or without a reference; publication limits follow the authenticated account, and account-bound sessions still require that account. Visibility, the reference, and `attributes` are bound to the session: later workflow requests cannot replace them or claim another account. Sessions still enforce opinion and answer validation, project publication, cooldowns, and the shared allowance for public and private answers.

### Returning visitors and timeouts [#returning-visitors-and-timeouts]

A visitor who leaves and comes back does not lose their work:

- **Before the opinion is posted,** a timed-out iframe starts a new session with the same `visibility`, `externalUserId`, and `attributes`, keeps the visitor's text, and shows a short notice. It checks when the visitor returns or acts, and whenever a request reports the timeout. A visitor who confirmed their email confirms it again; a detected Orvelt account continues without a new check.
- **After the opinion is posted,** for example while answering follow-up questions, the form shows its thank-you screen and never posts twice.

Recovery needs no code on your side. The storefront API answers a timed-out session with `GONE` (HTTP 410), and unknown or foreign credentials with `NOT_FOUND`; only the holder of the session secret can tell the two apart.

### Resume a session [#resume-a-session]

A resume URL contains only `#session=SESSION_UUID`; `onSessionCreated` receives a new one whenever a session is renewed. Passing it as `sessionUrl` reopens that session in the same tab and storage context, where the iframe has its saved credential. In another context, with a copied or unknown identifier, or when the browser blocks third-party storage, the iframe starts a new session instead. The iframe never accepts a URL-supplied bearer secret or shares its secret with the host. Never treat a session URL as permanent installation code.

### Framing and errors [#framing-and-errors]

All host origins are allowed while **Delivery → Embedded form → Allowed origins** is empty. Added origins must match scheme, hostname, subdomain, and port exactly; paths, wildcards, and patterns are rejected. The Business dashboard preview stays allowed. The browser enforces Orvelt's `frame-ancestors` policy, and your site's `frame-src` must also allow the storefront.

Malformed configuration is rejected. Unknown or unpublished projects and invalid sessions cannot be used, and expired sessions are renewed only by the iframe that created them. Session creation is rate-limited and every successful request creates a different session, so do not retry blindly.