Orvelt

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

OptionDefaultMeaning
projectIdRequiredPublished project UUID. Public configuration, not a credential.
visibilitypublicOnly public reviews or private feedback. Set by the business, not a visitor-facing toggle.
externalUserIdOmittedOptional unverified reference. Trimmed, 1–256 characters, no control characters.
attributesOmittedOptional 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.
originhttps://orvelt.comOptional storefront origin; override for staging or local development.
sessionUrlOmittedIdentifier-only resume URL for this project and origin. See Resume a session.
onSubmittedOmittedReceives { isPrivate } after persisted completion.
onSessionCreatedOmittedReceives an identifier-only resume URL after opening or renewing a session. Never includes its bearer secret.
onCloseOmittedCalled when the visitor closes the form: its close button, or Escape/backdrop click in a modal. With mount(), setting it shows the close button.
closeButtonSee meaningShows 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.accentColorOrvelt's accentHex color such as #4f46e5 (3 or 6 digits) for buttons, focus rings, and highlights. Text color is chosen for contrast.
appearance.colorSchemelightlight, dark, or system (follows the visitor's device).
appearance.radiusOrvelt's radiusInteger from 0 to 24: corner radius of fields and buttons, in pixels.
onReadyOmittedCalled when the iframe has loaded and is ready.
onErrorOmittedCalled 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

MethodMeaning
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:

ClassElement
orvelt-modal<dialog> created by open(); its backdrop is .orvelt-modal::backdrop.
orvelt-modal__iframeIframe inside the modal.
orvelt-iframeIframe 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, 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

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.