Quick Start - Worth

This guide details steps to install Onboarding SDK 3, mount the embedded onboarding runtime into your page, and handle its lifecycle callbacks.

Prerequisites

Before you start, ensure that you have:

A valid invite token for the customer or applicant who is to be onboarded
Node.js and npm installed in your project

Install the SDK

Install the SDK package via npm:

npm install @worthai/onboarding-sdk

Add a mount target

Add an empty element to your page wherein the onboarding flow should render. SDK 3 mounts directly into this element

<div id="worth-onboarding"></div>

Create the onboarding instance

Call createWorthOnboarding with your invite token and lifecycle callbacks:

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

const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  onStepSubmit: ({ inviteToken, stepId, values }) => {
    // Called each time an onboarding step is submitted
    console.log('Step submitted:', stepId, values);
  },
  onComplete: ({ inviteToken, values }) => {
    // Called when the applicant finishes the onboarding flow
    console.log('Onboarding completed:', values);
  },
  onError: (error) => {
    // Called on SDK or runtime errors
    console.error('Onboarding error:', error);
  },
});

Use apiBaseUrl only if you’re targeting a non-production or non-default Worth API environment:

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

Mount the SDK

mount() is asynchronous and accepts either a CSS selector string or an HTMLElement. It resolves once the onboarding flow has rendered into the target

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

Because mount() returns a promise, wrap it in a try/catch if you want to handle mount-time failures separately from runtime errors reported through onError

try {
  await onboarding.mount('#worth-onboarding');
} catch (error) {
  console.error('Failed to mount onboarding:', error);
}

Clean up on unmount

Call unmount() when the containing route or component unloads. SDK 3 supports only one mounted instance at a time, so unmounting is required before mounting a new instance on the same page

onboarding.unmount();

Putting It Together

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

const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  onStepSubmit: ({ stepId, values }) => {
    console.log('Step submitted:', stepId, values);
  },
  onComplete: ({ values }) => {
    console.log('Onboarding completed:', values);
  },
  onError: (error) => {
    console.error('Onboarding error:', error);
  },
});

try {
  await onboarding.mount('#worth-onboarding');
} catch (error) {
  console.error('Failed to mount onboarding:', error);
}

// Later, on route change or component teardown:
// onboarding.unmount();

<!-- In your HTML: -->
<div id="worth-onboarding"></div>

Using SDK 3 in a Framework

The example above is illustrative vanilla TypeScript. In component-based frameworks like React, create the instance once, mount it when the component mounts, and unmount it in your cleanup function:

import { useEffect, useRef } from 'react';
import { createWorthOnboarding, type WorthOnboarding } from '@worthai/onboarding-sdk';

function OnboardingFlow({ inviteToken }: { inviteToken: string }) {
  const mountRef = useRef<HTMLDivElement>(null);
  const onboardingRef = useRef<WorthOnboarding | null>(null);

  useEffect(() => {
    if (!mountRef.current) return;

    const onboarding = createWorthOnboarding({
      inviteToken,
      onComplete: ({ values }) => console.log('Onboarding completed:', values),
      onError: (error) => console.error('Onboarding error:', error),
    });

    onboardingRef.current = onboarding;
    onboarding.mount(mountRef.current).catch((error) => {
      console.error('Failed to mount onboarding:', error);
    });

    return () => {
      onboarding.unmount();
      onboardingRef.current = null;
    };
  }, [inviteToken]);

  return <div ref={mountRef} />;
}

Content Security Policy

SDK 3 injects its scoped runtime styles automatically during mount(). If your host page enforces a strict style-src Content Security Policy, pass your page’s request-level nonce with styleNonce:

const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  styleNonce: window.__CSP_NONCE__,
  onComplete: ({ values }) => {},
});

Handling Errors

onError receives a WorthOnboardingError, which includes a code that you can branch on. See Error Handling for a complete list of error codes.

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

onError: (error) => {
  if (isWorthOnboardingError(error)) {
    console.error(`[${error.code}] ${error.message}`);
  } else {
    console.error(error);
  }
};

Next Steps

See API Reference for complete API documentation
Migrating from SDK 2? Read the Migration Guide

Support

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

​Prerequisites

​Putting It Together

​Using SDK 3 in a Framework

​Content Security Policy

​Handling Errors

​Next Steps

​Support