Skip to main content

​
createOnboardingApp

API reference for all Onboarding SDK methods, types, and options.

​
Import

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

​
Parameters

The function accepts a single argument object with the following properties:
PropertyTypeDescription
originstringThe origin URL of the onboarding app
inviteTokenstringThe invite token used to authenticate and initialize the onboarding session
mode?'embedded' | 'non-embedded' | undefinedThe iframe mode. When set to 'embedded', the iframe is embedded in the parent site. When 'non-embedded' or undefined, the iframe operates in standalone mode
loadingTimeout?numberLoading timeout in milliseconds. The minimum allowed value is 15000 ms

​
Example

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

const onboardingApp = createOnboardingApp({
  origin: '{{WORTH_ONBOARDING_APP_DOMAIN}}',
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  mode: 'embedded',
});

​
Returned Methods

The createOnboardingApp function returns an object with the following methods and properties:

​
subscribe(callback)

Subscribes to messages from the Worth Onboarding App. Returns a subscription object with an unsubscribe method. Parameters:
  • callback: (event: MessageEvent<OnboardingAppMessage>) => void - A callback function that receives message events from the Worth Onboarding App
Returns:
  • { unsubscribe: () => void } - A subscription object with an unsubscribe method to stop listening to messages
Example: 
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'ROUTE_URL') {
    console.log('Current route:', event.data.payload.url);
  }
});

// Clean up when done
subscription.unsubscribe();
Message Types Received:
  • ROUTE_URL - Notifies when the route changes in the onboarding app
  • IFRAME_RESIZE - Notifies when the iframe needs to resize (includes height)
  • IFRAME_INITIALIZED - Notifies when the iframe has finished initializing
  • ONBOARDING_STARTED - Signals that the onboarding flow is ready; the parent clears the loading state and the SDK initializes the detached iframe.
  • STAGE_NAVIGATION - Updates as the user moves through stage. With this event that the parent receives it, updates navigation, and re-renders the buttons and labels accordingly. See more details about how this message type is handled.
  • LOADING_TIMED_OUT - Fired when the onboarding app does not load within the configured time limit. This event requires the loadingTimeout option to be set when creating the createOnboardingApp instance. Fallback event to hide loading state.
  • RESTARTING - Fired when the onboarding app is restarted after LOADING_TIMED_OUT.
  • AUTHENTICATION_STATUS - Notifies when the onboarding app’s isAuthenticated state changes.
  • ONBOARDING_COMPLETED - Fired when the full onboarding is submitted.
  • ERROR - Handles ERROR events from the onboarding SDK subscription. See more details about how this message type is handled.

​
Handling STAGE_NAVIGATION message type

Drives navigation actions, and the SDK app responds with the new navigation state and stage metadata. 
// Object definition
export type StageNavigation = {
  isInitialStage: boolean;
  isLastStage: boolean;
  stage: string | undefined;
  nextStatus: {
    visible: boolean;
    disabled: boolean;
    loading: boolean;
    isSubmit: boolean;
  };
  prevStatus: { visible: boolean; disabled: boolean; loading: boolean };
  skipStatus: { visible: boolean; disabled: boolean; loading: boolean };
};
Field‑by‑field semantics
  • isInitialStage: true when the current stage is the very first step of the flow. The parent uses this to decide that “Back” should leave the flow entirely instead of going to a previous stage.
  • isLastStage: true when the current stage is the final step. The parent uses this to change both behavior (navigate to a “completed” route instead of NEXT_STAGE) and label (“Complete” vs “Next”).
  • stage: A logical identifier for the current stage (e.g. “personal-info”, “documents”, etc.). In your parent UI it’s currently just displayed for observability / debugging.
  • nextStatus: controls the Next/Complete button
  • visible: whether the Next/Complete button should be rendered at all.
  • disabled: whether the button is clickable (e.g. when validation not satisfied).
  • loading: whether the action is in progress (you could map this to a spinner on the button if desired).
  • isSubmit: the child is telling you “this click actually submits data / form”, even if it’s not the very last stage. You could use this to show different copy or confirmation.
  • prevStatus: controls the Back button Same idea: visible, disabled, loading communicate whether Back should be shown and usable.
  • skipStatus: controls the Skip button Same structure:*** visible, disabled, loading, telling you whether skipping is allowed on this particular stage.
Example: How the parent consumes STAGE_NAVIGATION. The parent subscribes to SDK events and stores stageNavigation into local state: 
// Get Button Inner Elements
const prevButton = document.getElementById('prev-btn');

const skipButton = document.getElementById('skip-btn');

const nextButton = document.getElementById('next-btn');

// Listen for onboarding messages
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'STAGE_NAVIGATION') {
    console.log('Current stage:', event.data.payload.stageNavigation);
    const stageNavigation = event.data.payload.stageNavigation;

    // Set prev button disabled state based on stageNavigation event
    if (prevButton) {
      prevButton.disabled = stageNavigation.prevStatus.disabled;
    }

    // Set skip button disabled state based on stageNavigation event
    if (skipButton) {
      skipButton.disabled = stageNavigation.skipStatus.disabled;
    }

    // Set next button disabled state based on stageNavigation event
    if (nextButton) {
      nextButton.disabled = stageNavigation.nextStatus.disabled;
    }
  }
});

// Get the current stage navigation
const navigation = onboardingApp.navigation();

/** Prev button handler **/

// That navigation object (of type StageNavigation)
// then directly drives your buttons:
prevButton?.addEventListener('click', () => {
  if (navigation?.isInitialStage) {
    // HERE: implement code to back to home or previous page
    window.location.href = '/';
  } else {
    onboardingApp.prev();
  }
});

/** Skip button handler **/
skipButton?.addEventListener('click', () => {
  onboardingApp.skip();
});

/** Next button handler **/
nextButton?.addEventListener('click', () => {
  if (navigation?.isLastStage) {
    // HERE: implement code to navigate into onboarding-completed page
    // or custom redirection
    window.location.href = '../onboarding-completed';
  } else {
    onboardingApp.next();
  }
});

​
Handling ERROR message type

Extracts the error message and displays it via notification UI component. 
// Listen for onboarding messages
const subscription = onboardingApp.subscribe((event) => {
  if (event.data.type === 'ERROR') {
    const message = event.data.payload.error.message;

    // Show error message into your Notification UI Component
    alert(`Error Title: ${message}`);
  }
});

​
setMode(mode)

Sets the iframe mode to control how the onboarding app is displayed. Sends a SET_IFRAME_MODE message to the Worth Onboarding App. Parameters:
  • mode: 'embedded' | 'non-embedded' | undefined - The mode to set
    • 'embedded' - The iframe is embedded within the parent site’s layout
    • 'non-embedded' - The iframe is displayed in standalone mode
    • undefined - Uses as default non-embedded mode
Returns: void Example: 
// Switch to embedded mode
onboardingApp.setMode('embedded');

// Switch to non-embedded mode
onboardingApp.setMode('non-embedded');

// Toggle mode based on checkbox
const modeToggle = document.getElementById('mode-toggle');
modeToggle?.addEventListener('change', (event) => {
  const isEmbedded = (event.target as HTMLInputElement).checked;
  onboardingApp.setMode(isEmbedded ? 'embedded' : 'non-embedded');
});

​
next()

Navigates the onboarding app to the next stage. Sends a NEXT_STAGE message to the Worth Onboarding App. Parameters: None Returns: void Example: 
const nextButton = document.getElementById('next-btn');
nextButton?.addEventListener('click', () => {
  onboardingApp.next();
});

​
prev()

Navigates the onboarding app to the previous stage. Sends a PREV_STAGE message to the Worth Onboarding App. Parameters: None Returns: void Example: 
const prevButton = document.getElementById('prev-btn');
prevButton?.addEventListener('click', () => {
  onboardingApp.prev();
});

​
skip()

Skips the current onboarding app stage. Sends a SKIP_STAGE message to the Worth Onboarding App. Parameters: None Returns: void Example: 
const prevButton = document.getElementById('prev-btn');
prevButton?.addEventListener('click', () => {
  onboardingApp.prev();
});

​
setCustomCss(css)

Injects custom CSS styles into the Worth Onboarding App iframe. Sends a SET_CUSTOM_CSS message to the Worth Onboarding App. Parameters:
  • css: string - A string containing CSS rules to apply to the Worth Onboarding App
Returns: void Example: 
// Apply custom background color
onboardingApp.setCustomCss('body { background: #f0f0f0; }');

// Apply multiple styles
onboardingApp.setCustomCss(`
  body {
    background: #ffffff;
    font-family: 'Custom Font', sans-serif;
  }
  .onboarding-container {
    padding: 20px;
    border-radius: 8px;
  }
`);

// Dynamic CSS based on user preference
const themeToggle = document.getElementById('theme-toggle');
themeToggle?.addEventListener('change', (event) => {
  const isDark = (event.target as HTMLInputElement).checked;
  onboardingApp.setCustomCss(
    isDark
      ? 'body { background: #1a1a1a; color: #ffffff; }'
      : 'body { background: #ffffff; color: #000000; }',
  );
});

​
refreshSize()

Requests the Worth Onboarding App to recalculate and report its size. This is useful when the iframe content changes dynamically. Sends a REFRESH_SIZE message to the Worth Onboarding App. Parameters: None Returns: void Example: 
// Refresh size after content changes
onboardingApp.refreshSize();

// Refresh size on window resize
window.addEventListener('resize', () => {
  onboardingApp.refreshSize();
});

// Refresh size on button click
const refreshButton = document.getElementById('refresh-size-btn');
refreshButton?.addEventListener('click', () => {
  onboardingApp.refreshSize();
});

​
iframe

A read-only property that contains the Worth Onboarding App. This is the actual iframe DOM element that should be appended to your page. Type: HTMLIFrameElement Example: 
// Append iframe to container
const container = document.getElementById('onboarding-container');
if (container) {
  container.appendChild(onboardingApp.iframe);
}

// Example of creating and appending in vanilla TypeScript
function setupOnboarding() {
  const onboardingApp = createOnboardingApp({
    origin: '{{WORTH_ONBOARDING_APP_DOMAIN}}',
    inviteToken: 'YOUR_TOKEN',
  });

  const container = document.getElementById('onboarding-container');
  if (container) {
    container.appendChild(onboardingApp.iframe);
  }
}

// Call setup function during your app's initialization
setupOnboarding();