Inquiry embed

The inquiry embed runs the Folio inquiry on any web page without npm, a bundler or React. Your page loads one module script from Folio and calls window.FolioInquiry.mount. The inquiry then runs in an iframe served from Folio's origin: the SDK, its WebAssembly module, the illustrations, the animations and the API requests all stay on that origin, and your page talks to the iframe only through postMessage to one pinned origin.

To run the inquiry inside your own React app instead, use the npm package: see Web setup.

How it worksCopy Anchor Link

1. Your backend creates an inquiry and receives a one-time launch code. The embed never creates an inquiry.
2. Your page loads the loader embed.v<major>.js. It registers window.FolioInquiry.
3. FolioInquiry.mount(options) loads the embed runtime next to the loader, adds an iframe that shows <baseUrl>/inquiry.html and sends it your app metadata.
4. The iframe starts the SDK and reports READY with its SDK version. The loader checks that version against the major version in its own file name.
5. Only then does the loader send the entry with your launch code to the iframe. The inquiry runs, and your onLifecycle callback receives every lifecycle change.

Load the loaderCopy Anchor Link

<script type="module" src="<embed-loader-url>"></script>

<embed-loader-url> is the URL of the loader that Folio gives you; Folio does not publish one URL for everyone. The iframe accepts messages only from host origins Folio has configured for it, so ask Folio for the loader URL and give it every origin your pages run on, including development and staging origins. A page on an origin Folio has not configured fails with READY_TIMEOUT; see Launch code handling and security.

• Load it as a module script: type="module" is required.
• The loader finds the rest of the embed from its own URL. It fetches runtime-manifest.json from the directory it was loaded from and imports the runtime chunk that the manifest names. Load it from the URL Folio gives you, so that these files are next to it.
• The v<major> in the file name is the major version the loader is pinned to. See Versions and caching.

Mount the inquiryCopy Anchor Link

Call mount from a module script that comes after the loader, so that window.FolioInquiry exists when it runs:

<div id="folio-inquiry"></div>
<script type="module">
    const handle = window.FolioInquiry.mount({
        container: '#folio-inquiry',
        app: { version: '2.3.4', build: '567' },
        mode: 'built-in',
        backdrop: { color: 'rgba(0, 0, 0, 0.5)' },
        panel: { background: '#ffffff', shadow: '0 12px 48px rgba(0, 0, 0, 0.24)' },
        entry: { type: 'START', value: { launchCode: backendMintedLaunchCode } },
        onLifecycle(lifecycle) {
            if (lifecycle.type === 'FAILED') console.error(lifecycle.value.error);
        },
    });
</script>

backendMintedLaunchCode stands for the launch code your backend passed to the page.

OptionsCopy Anchor Link

backdrop.color, panel.background and panel.shadow must be non-empty after trimming. The embed has no defaults for them, so your page decides how the modal looks.

Leave baseUrl and allowedOrigin out unless Folio tells you otherwise: the defaults point at the location you loaded the loader from.

EntryCopy Anchor Link

entry is the generated InquiryEntry in its JSON shape:

A source of { type: 'ANOTHER_DEVICE', value: { code } } continues an inquiry that was handed off from another device with its handoff code. Inquiry store describes the resume sources.

mount checks only that entry.type is START or RESUME. A blank launch code or handoff code, or a blank inquiryId in a SAME_DEVICE source, passes that check and then fails in the inquiry with INVALID_ENTRY.

ModesCopy Anchor Link

A modal removes itself when the lifecycle reaches CLOSED. The loader adds no close button of its own: the user leaves through the inquiry's own close control. A built-in iframe stays in the page after CLOSED; call destroy() to remove it.

The mount handleCopy Anchor Link

mount returns a handle right away, before the embed runtime has loaded:

• Messages to the iframe wait until the iframe reports READY. open() and close() called in that time are delivered after READY.
• open() and close() called before the embed runtime has loaded do nothing.
• destroy() called before the embed runtime has loaded prevents the mount.
• After destroy(), open() and close() do nothing. Call mount again for a new inquiry.

LifecycleCopy Anchor Link

onLifecycle receives the generated InquiryLifecycle, in the order the inquiry reports it:

outcome is one of COMPLETED, FAILED, ERROR, CANCELED, EXPIRED and NEEDS_REVIEW. The iframe reports a lifecycle only when it differs from the last one it reported.

The inquiry UI runs inside the iframe, so its links act from there. When the inquiry reaches its terminal screen and has finished loading, it closes the inquiry; when that screen has a redirect, the inquiry first navigates the iframe to the redirect URL with window.location.assign. Your page is not navigated. An EXTERNAL link of the inquiry opens in a new browser tab.

function onLifecycle(lifecycle) {
    switch (lifecycle.type) {
        case 'READY':
            console.log('Folio SDK', lifecycle.value.sdkVersion);
            break;
        case 'STARTED':
            console.log('inquiry', lifecycle.value.correlationId);
            break;
        case 'CLOSED':
            console.log('closed', lifecycle.value.outcome);
            break;
        case 'FAILED':
            console.error(lifecycle.value.error.type, lifecycle.value.error.value);
            break;
    }
}

FailuresCopy Anchor Link

The embed reports its own failures as a FAILED lifecycle with an InquiryError, like the failures of the inquiry itself:

const lifecycle: InquiryLifecycle = {
    type: 'FAILED',
    value: {
        error: {
            type: 'EMBED',
            value: {
                reason: { type: 'READY_TIMEOUT' },
                message: 'Inquiry runtime did not report READY in time',
            },
        },
    },
};

EMBED reasons:

After VERSION_MISMATCH the loader still waits for READY, so a READY_TIMEOUT follows it.

The other InquiryError values come from the inquiry itself; see Errors.

Launch code handling and securityCopy Anchor Link

• Your backend creates the inquiry. It passes the one-time launch code to the page. Mint a fresh launch code for each inquiry. Keep the credentials your backend uses with Folio out of the page.
• The launch code travels in one message only. The loader sends it in the body of the OPEN message to the pinned origin, after the iframe has reported READY and passed the version check. It never puts the launch code in a URL, a query string, srcdoc or a message addressed to '*'. The first message to the iframe carries only baseUrl, the origins and your app metadata.
• One pinned origin in each direction. The loader posts only to allowedOrigin and accepts messages only from that origin and from its own iframe's window. The iframe accepts its first message only from the host origin Folio configured for it and from its parent window, and later messages only from that same origin and window.
• Your page's origin must be configured. The iframe ignores the first message from any other origin, so a page on an origin Folio has not configured gets no READY and fails with READY_TIMEOUT.
• The runtime chunk name is checked. The loader imports only a file whose name matches runtime.<hex>.js from the manifest next to it.
• The inquiry's data stays on Folio's origin. The SDK runs inside the iframe, so its storage and its API requests belong to Folio's origin, not to your page.
• Camera and microphone. The iframe is created with allow="camera; microphone" so that document capture and selfie steps can use the camera. If your page sends a Permissions-Policy header, it must allow camera and microphone for the Folio origin, for example Permissions-Policy: camera=*, microphone=*.

Content Security PolicyCopy Anchor Link

If your page sends a Content Security Policy, allow what the embed loads from the Folio origin:

Replace <embed-origin> with the origin of the loader URL Folio gives you, and with the origin of baseUrl if you set it. The iframe document, its WebAssembly module, the illustrations, the animations and the API requests are loaded by the iframe on Folio's origin and are not governed by your page's policy.

Versions and cachingCopy Anchor Link

The embed carries the version of the Folio web SDK. The loader file name holds only its major version: SDK 0.x.y is served as embed.v0.js, 1.x.y as embed.v1.js.

• Patch and minor releases replace the files under the same loader URL. Your page gets them without a change.
• A major release gets a new loader file name. The loader of the previous major stays published for pages that reference it. To upgrade, change the src of your script tag after reading the release notes. Do not add a query string to the loader URL to upgrade.
• The version check. The loader reads its pinned major from the first v<digits> in its URL and rejects an iframe SDK of another major, or one that reports no version, with VERSION_MISMATCH. A loader URL without such a part skips the check.

Caching of the published files:

The loader and the manifest are cached for 5 minutes, so a fix reaches your page within minutes. The content-hashed runtime files are cached for one year. Keep the loader URL stable; the loader resolves the content-hashed runtime chunk itself.