Migration Guide

This guide details steps to migrate from the iframe-based Onboarding SDK 2 integration to the SDK 3 embedded runtime integration.

What’s Changed?

The core change is ownership of the iframe. With SDK 2, your host page creates and manages a Worth iframe directly. With SDK 3, you give the SDK a DOM element and it mounts, renders, and tears down the onboarding runtime for you with no iframe and no postMessage subscription required.

	SDK 2	SDK 3
Rendering	Host-managed `<iframe>`	SDK-managed DOM mount
Setup	`createOnboardingApp({ origin, inviteToken, mode })`	`createWorthOnboarding({ inviteToken, ... })`
Mounting	`container.appendChild(onboardingApp.iframe)`	`await onboarding.mount(target)`
Events	`subscribe()` + `postMessage` event stream	Typed callbacks (`onStepSubmit`, `onComplete`, `onError`, …)
Navigation	`next()`, `prev()`, `skip()`	Not exposed; the SDK owns step navigation
Styling	`setCustomCss()`	Styles injected automatically on `mount()`
Cleanup	`subscription.unsubscribe()` + `onboardingApp.cleanup()`	`onboarding.unmount()`

Side-by-Side Comparison

Before: SDK 2
After: SDK 3

When using SDK 2, the customer application owns the iframe lifecycle. It creates the iframe, appends it to the page, listens for postMessage events, and may drive navigation by calling helper methods such as next(), prev(), and skip().

import { createOnboardingApp } from '@worthai/onboarding-sdk';

const container = document.getElementById('worth-onboarding');
const inviteToken = 'INVITE_TOKEN';

const onboardingApp = createOnboardingApp({
  origin: 'https://onboarding.example.com',
  inviteToken,
  mode: 'embedded',
  loadingTimeout: 15000
});

const subscription = onboardingApp.subscribe((event) => {
  switch (event.data.type) {
    case 'ONBOARDING_COMPLETED':
      handleComplete();
      break;
    case 'ERROR':
      handleError(event.data.payload.error);
      break;
    case 'STAGE_NAVIGATION':
      updateNavigation(event.data.payload.stageNavigation);
      break;
    default:
      break;
  }
});

container?.appendChild(onboardingApp.iframe);

document.getElementById('worth-back')?.addEventListener('click', () => {
  onboardingApp.prev();
});

document.getElementById('worth-next')?.addEventListener('click', () => {
  onboardingApp.next();
});

function cleanupOnboarding() {
  subscription.unsubscribe();
  onboardingApp.cleanup();
  onboardingApp.iframe.remove();
}

When using SDK 3, the customer application no longer manages an iframe. It creates an onboarding instance with a valid invite token and optional callbacks, and mounts the SDK into a DOM element. SDK styles are injected automatically during mount.

import { createWorthOnboarding } from '@worthai/onboarding-sdk';

const onboarding = createWorthOnboarding({
  inviteToken: 'INVITE_TOKEN',
  onStepSubmit: ({ inviteToken, stepId, values }) => {
    // step submission hook for analytics, audit, or synchronization
  },
  onComplete: ({ inviteToken, values }) => {
    // form completion hook - maps to ONBOARDING_COMPLETED event from SDK2
  },
  onError: (error) => {
    // error handling hook - maps to ERROR event from SDK2
  }
});

await onboarding.mount('#worth-onboarding');

function cleanupOnboarding() {
  onboarding.unmount();
}

Additional SDK 3 Configuration

For non-production or non-default API environments, pass apiBaseUrl:

const onboarding = createWorthOnboarding({
  apiBaseUrl: 'https://api.staging.example.com',
  inviteToken: 'INVITE_TOKEN',
  onComplete: ({ values }) => {},
  onStepSubmit: ({ inviteToken, stepId, values }) => {},
  onError: (error) => {}
});

SDK 3 injects its scoped runtime styles automatically during mount(). Hosts with a strict style-src Content Security Policy should pass the page’s request-level nonce explicitly with styleNonce:

const onboarding = createWorthOnboarding({
  inviteToken: 'INVITE_TOKEN',
  styleNonce: window.__CSP_NONCE__,
  // . . .
});

Bundler and module-script integrations should not rely on automatic nonce discovery. If the host application uses CSP nonces, pass the nonce value from the host application configuration.

What changes do you need to make?

The core migration is from iframe orchestration to embedded runtime mounting. SDK 2 iframe-specific code should be replaced with SDK 3 lifecycle callbacks. Remove SDK 2 iframe ownership:

Remove origin, mode, and loadingTimeout configuration
Remove appendChild(onboardingApp.iframe) and direct iframe styling
Remove raw postMessage event subscription logic
Remove calls to next(), prev(), skip(), setMode(), setCustomCss(), and refreshSize()
Remove iframe-specific teardown, except for replacing it with onboarding.unmount()

Add SDK 3 embedded runtime usage:

Add a stable mount target, such as <div id="worth-onboarding"></div>
Remove any old SDK stylesheet import or stylesheet <link> tag. SDK 3 styles are injected automatically during mount()
Create an SDK instance with createWorthOnboarding({ inviteToken, ... })
Use onComplete for completion behavior
Use onError for SDK/runtime errors
Use onStepSubmit when the host application needs a step-submission analytics, audit, or synchronization hook
Call unmount() when the containing route or component unloads

Callback Mapping

SDK 2 exposed a broad event stream through subscribe(). SDK 3 exposes structured callbacks on the createWorthOnboarding options object.

Use onComplete instead of handling the ONBOARDING_COMPLETED message
Use onError instead of handling the ERROR message
Use onAuthenticated and onAuthUnsupported for authentication-specific outcomes when the host application needs to observe those states
Use onStepSubmit for submitted step payloads. The callback receives:

{
  inviteToken: string;
  stepId: string;
  values: Record<string, unknown>;
}

SDK 3 does not expose a public step-navigation callback. If the SDK 2 integration used STAGE_NAVIGATION only to observe internal step changes, remove that listener during migration; onStepSubmit is only fired for submitted step payloads and is not a general navigation-event replacement.

Migration Checklist

Use this checklist to track your migration from start to finish.

Update the SDK package

Update the @worthai/onboarding-sdk package version that contains SDK 3

Add a mount target

Add or reuse a mount target element, such as <div id="worth-onboarding"></div>

Remove old stylesheets

Remove any old Worth SDK stylesheet import or CDN stylesheet tag. SDK 3 injects its styles automatically during mount()

Swap the SDK entry point

Replace createOnboardingApp(...) with createWorthOnboarding(...)

Move event handling to callbacks

Move completion and error behavior from subscribe() handlers to onComplete and onError

Add onStepSubmit if needed

Add onStepSubmit if your application needs a step-submission hook for analytics, auditing, synchronization, etc.

Handle strict CSP, if applicable

If your host page enforces a strict style-src Content Security Policy, pass its request nonce as styleNonce and test in a page with CSP enabled

Remove iframe navigation controls

Remove external iframe navigation controls (next(), prev(), skip()) unless SDK 3 explicitly adds a replacement API

Replace cleanup logic

Replace iframe cleanup (subscription.unsubscribe(), onboardingApp.cleanup()) with onboarding.unmount()

Test the full flow

Test the full onboarding flow in your host page, including route changes, cleanup/remount, completion, and error handling

Support

For questions or issues, please contact your Worth Customer Success team or reach out to support@joinworth.com.

​What’s Changed?

​Side-by-Side Comparison

​Additional SDK 3 Configuration

​What changes do you need to make?

​Callback Mapping

​Migration Checklist

​Support