Script Tag (No Build Step)

For pages that have no build step — WordPress, Shopify, a Rails or Django template, a CMS block, a plain HTML landing page — load the widget with one <script> tag and drive it through the window.KYCWidget global. No bundler, no ES modules, no npm install.

<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."></script>

The file is the same browser SDK the npm package ships, built as a single self-contained IIFE. Behaviour, wire protocol and diagnostics are identical to @flonkid/kyc/core; only the way you configure and call it differs.

Which path do I want? React → @flonkid/kyc. Vue / Angular / Svelte / vanilla-TS with a bundler → FlonkKYC from @flonkid/kyc/core. No build step at all → this page. Native app or fully custom UI → Direct API.

1. Load and configure the tag

Configuration comes from data-* attributes on the script tag itself. They map onto the same options the npm SDK takes — there is no separate loader-only configuration.

Attributes not in this table are ignored.

Every attribute is a default: an argument you pass to init(), preview(), embed() or redirect() wins over the tag. Only data-api is fixed at load — it is read once, when the script constructs its client.

Pass data-pk even when your backend creates the session. With the key on the tag the script resolves your brand color in parallel with session setup and paints it on the first frame; without it the loading screen is neutral grey until a round-trip completes. The key is publishable — it is meant to sit in page source.

2. Start a verification

The secret key never touches the browser on this path either. Your backend creates the session; the page receives only sessionId + embedToken.

<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-api="https://api.flonk.id/v1"></script>

<button id="verify">Verify identity</button>

<script>
  document.getElementById('verify').onclick = async () => {
    // Your authenticated backend creates the session with the SECRET key and
    // returns { sessionId, embedToken, qrCodeUrl }.
    const res = await fetch('/api/kyc/create-session', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + token }, // your app's session/JWT
    });
    const { sessionId, embedToken, qrCodeUrl } = await res.json();

    window.KYCWidget.init({
      sessionId,
      embedToken,
      qrCodeUrl, // without it the desktop -> mobile QR step cannot render
      // Required by init(): the email of the person being verified. Put it on
      // the tag as data-email instead when it is known at page render.
      clientMetadata: { email: user.email },
      onSuccess: (result) => console.log('Verified:', result),
      onError:   (error)  => console.error('Failed:', error),
      onCancel:  ()       => console.log('Cancelled'),
    });
  };
</script>

You can also let the script call your endpoint for you — pass serverUrl instead of a session, exactly like the SDK's Option A:

<script>
  window.KYCWidget.init({
    serverUrl: '/api/kyc/create-session',
    requestHeaders: { Authorization: 'Bearer ' + token },
    // Required by init(), here or as data-email on the tag.
    clientMetadata: { email: user.email },
    onSuccess: (result) => console.log('Verified:', result),
    onError:   (error)  => console.error('Failed:', error),
    onCancel:  ()       => console.log('Cancelled'),
  });
</script>

Your endpoint must respond with { sessionId, embedToken, qrCodeUrl } — see Frontend & Backend → Backend.

onSuccess firing does not mean the user is verified. Branch on result.status (completed, manual_review, action_required, failed) and confirm server-side from the webhook or GET /v1/verifications/{sessionId}.

3. The window.KYCWidget surface

embed() renders a preview, not a verification

embed() mounts a themed preview — mock data, no camera, no session, no result. It exists for dashboard-style "this is how the widget will look in your brand colors" panels. It cannot verify anyone, and no callback will ever report a verification from it.

There is no script-tag equivalent of the npm SDK's mountInline() — the mode that runs a live verification inside your own layout. If you need a real verification embedded in the page rather than in a modal, use the npm path with a bundler. On this path, a real verification is init() (modal) or redirect() (full page).

Prewarming

The script warms the connection to the widget origin as soon as it runs. Raise the level on a page where the click is likely:

<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-prewarm="eager"></script>

intent is accepted too, but it warms on hover/focus of a trigger element that only the npm path can pass; from a script tag there is none, so it degrades to idle warming — the same thing connect does.

Content Security Policy

This path adds a script to your page, so script-src is a hard requirement here — unlike the npm path, where a blocked loader script only costs you dashboard-driven branding:

Content-Security-Policy:
  script-src  https://api.flonk.id;
  frame-src   https://verify.flonk.id;
  connect-src https://api.flonk.id;

If script-src blocks api.flonk.id, nothing runs at all: window.KYCWidget is never defined and your init() call throws a TypeError.

The widget origin belongs in frame-src only — it hands your page no script. redirect() needs neither, since it navigates your page instead of framing anything.

Permissions-Policy is what breaks the camera, not CSP. If your site sends a restrictive one, the iframe's allow="camera;microphone" delegation is refused and verification dies at the first capture step. See Troubleshooting.

Debugging

Add data-debug to the tag (or set window.__FLONK_DEBUG__ = true before the widget opens) to mirror every SDK diagnostic to the console — blocked loader script, prewarm skipped, no READY from the iframe, protocol mismatch. Silent by default.

<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-debug></script>

Migrating from the legacy widget.js

Existing pages load https://widget.flonk.id/v1/widget.js. That loader keeps working; the migration is a URL swap, because the global keeps its name and the methods keep their signatures.

Both scripts register window.KYCWidget. If a page ends up with both during a migration, the second one to load wins; call noConflict() from the one you don't want.