Embed options
Every orveltEmbed option and method, styling hooks, and how visitor sessions expire and recover.
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 walks through installation.
orveltEmbed.configure
Import it from @orvelt/business, or use the OrveltEmbed global provided by opinion-embed.js.
Example
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
| 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. |
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
| 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
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.
.orvelt-modal {
border-radius: 20px;
}
.orvelt-modal::backdrop {
background: rgb(15 23 42 / 0.6);
}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
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
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
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, andattributes, 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
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
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.