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

​
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.
  • 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();