@speakavatar/onboarding

A powerful user onboarding library similar to intro.js, with optional SpeakAvatar avatar integration for spoken instructions.

Features

• 🎯 Step-by-step tours - Guide users through your application
• 🎨 Customizable styling - Match your brand with CSS variables
• 🔊 Optional SpeakAvatar integration - Add spoken instructions with animated avatars
• ⚛️ React support - React hooks and components included
• 📱 Responsive - Works on mobile and desktop
• ⌨️ Keyboard navigation - Arrow keys and escape support
• 🎨 Auto-positioning - Tooltips automatically position to stay in viewport

Installation

npm install @speakavatar/onboarding

Getting Started Guide

For a comprehensive step-by-step guide, see GUIDE.md. This includes:

• Detailed installation instructions
• Complete setup examples for React and Vanilla JavaScript
• SpeakAvatar integration walkthrough
• Configuration options explained
• Troubleshooting tips

Quick Start

Vanilla JavaScript

import speakAvatarTour from '@speakavatar/onboarding';
import '@speakavatar/onboarding/dist/style.css';

speakAvatarTour.setOptions({
  steps: [{
    element: '#login-button',
    intro: 'Click here to login to your account!',
  }, {
    element: '#dashboard',
    title: 'Welcome to Dashboard',
    intro: 'This is your main dashboard where you can see all your data.',
  }]
}).start();

React

import { TourProvider, useTour } from '@speakavatar/onboarding/react';
import '@speakavatar/onboarding/dist/style.css';

function App() {
  const { startTour } = useTour();
  
  const steps = [
    {
      element: '#login-button',
      intro: 'Click here to login!',
    },
    {
      element: '#dashboard',
      title: 'Dashboard',
      intro: 'This is your dashboard.',
    },
  ];
  
  return (
    <TourProvider steps={steps}>
      <button onClick={startTour}>Start Tour</button>
      {/* Your app content */}
    </TourProvider>
  );
}

With SpeakAvatar Integration

import speakAvatarTour from '@speakavatar/onboarding';
import '@speakavatar/onboarding/dist/style.css';

speakAvatarTour
  .setSpeakAvatarConfig({
    playerUrl: 'https://your-domain.com/api/sdk/v1/embed',
    getSessionToken: async () => {
      const response = await fetch('/api/sdk/v1/auth/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          customerId: 'your-customer-id',
          apiKey: 'your-api-key',
        }),
      });
      const { token } = await response.json();
      return token;
    },
    defaultAvatar: { style: 'realistic' },
  })
  .setOptions({
    steps: [{
      element: '#login-button',
      intro: 'Click here to login!',
      speakAvatar: {
        text: 'Click here to login to your account!',
        avatar: { style: 'realistic', mood: 'happy' },
      },
    }],
  })
  .start();

API Reference

Vanilla JS API

speakAvatarTour.setOptions(options)

Configure tour options.

Options:

• steps (Array): Array of step configurations
• showProgress (boolean): Show progress indicator (default: true)
• showButtons (boolean): Show navigation buttons (default: true)
• prevLabel (string): Previous button label (default: 'Previous')
• nextLabel (string): Next button label (default: 'Next')
• skipLabel (string): Skip button label (default: 'Skip')
• doneLabel (string): Done button label (default: 'Done')
• showSkip (boolean): Show skip button (default: true)
• exitOnOverlayClick (boolean): Exit on overlay click (default: true)
• exitOnEscape (boolean): Exit on escape key (default: true)
• keyboardNavigation (boolean): Enable keyboard navigation (default: true)
• onStart (Function): Callback when tour starts
• onStepChange (Function): Callback when step changes
• onComplete (Function): Callback when tour completes
• onExit (Function): Callback when tour exits

speakAvatarTour.setSpeakAvatarConfig(config)

Configure SpeakAvatar integration.

Config:

• playerUrl (string): SpeakAvatar player URL
• getSessionToken (Function): Async function that returns session token
• defaultAvatar (Object): Default avatar configuration
• defaultVoice (string): Default voice ID

speakAvatarTour.start()

Start the tour.

speakAvatarTour.exit()

Exit the tour.

speakAvatarTour.nextStep()

Go to next step.

speakAvatarTour.prevStep()

Go to previous step.

speakAvatarTour.goToStep(index)

Go to specific step by index.

Step Configuration

Each step can have the following properties:

• element (string|HTMLElement): CSS selector or element to highlight
• intro (string): Step description text
• title (string): Step title (optional)
• position (string): Tooltip position - 'top', 'bottom', 'left', 'right', or 'auto' (default: 'auto')
• scrollTo (boolean): Scroll to element (default: true)
• scrollOffset (number): Scroll offset in pixels (default: 0)
• speakAvatar (Object): SpeakAvatar configuration for this step
  • text (string): Text for avatar to speak
  • avatar (Object): Avatar configuration
  • voice (string): Voice ID
• onBeforeStepChange (Function): Callback before step changes
• onStepChange (Function): Callback when step changes

React API

<TourProvider>

React context provider for tour.

Props:

• steps (Array): Array of step configurations
• options (Object): Tour options (same as vanilla API)
• speakAvatarConfig (Object): SpeakAvatar configuration

useTour()

React hook to access tour instance.

Returns:

• tour: Tour instance
• startTour(): Function to start tour
• exitTour(): Function to exit tour
• nextStep(): Function to go to next step
• prevStep(): Function to go to previous step
• goToStep(index): Function to go to specific step
• isActive: Boolean indicating if tour is active
• currentStepIndex: Current step index
• currentStep: Current step object

Step-by-Step Setup Guide

1. Installation

npm install @speakavatar/onboarding

Import the styles:

import '@speakavatar/onboarding/dist/style.css';

2. Basic Tour (Without Avatar)

Vanilla JavaScript:

import speakAvatarTour from '@speakavatar/onboarding';
import '@speakavatar/onboarding/dist/style.css';

speakAvatarTour.setOptions({
  steps: [
    { element: '#feature-1', title: 'Feature 1', intro: 'This is your first feature.' },
    { element: '#feature-2', title: 'Feature 2', intro: 'This is your second feature.' },
  ]
}).start();

React:

import { TourProvider, useTour } from '@speakavatar/onboarding/react';
import '@speakavatar/onboarding/dist/style.css';

function App() {
  const { startTour } = useTour();
  const steps = [
    { element: '#feature-1', title: 'Feature 1', intro: 'This is your first feature.' },
    { element: '#feature-2', title: 'Feature 2', intro: 'This is your second feature.' },
  ];
  
  return (
    <TourProvider steps={steps}>
      <button onClick={startTour}>Start Tour</button>
      {/* Your app content */}
    </TourProvider>
  );
}

3. Adding SpeakAvatar Integration

To add a speaking avatar, you need to:

1. Get API credentials from SpeakAvatar.ai
2. Create a session token function (call from your backend for security):

async function getSessionToken() {
  const response = await fetch('/api/sdk/v1/auth/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      customerId: 'your-customer-id',
      apiKey: 'your-api-key',
      permissions: ['generate', 'preview']
    })
  });
  const data = await response.json();
  return data.token;
}

3. Configure SpeakAvatar and add speakAvatar to your steps:

React Example:

import { useCallback, useMemo } from 'react';
import { TourProvider, useTour } from '@speakavatar/onboarding/react';

function App() {
  const { startTour } = useTour();
  
  const getSessionToken = useCallback(async () => {
    const response = await fetch('/api/sdk/v1/auth/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        customerId: 'your-customer-id',
        apiKey: 'your-api-key',
        permissions: ['generate', 'preview']
      })
    });
    const data = await response.json();
    return data.token;
  }, []);

  const steps = useMemo(() => [
    {
      element: '#feature-1',
      title: 'Feature 1',
      intro: 'This is your first feature.',
      speakAvatar: {
        text: 'Welcome! This is your first feature. Let me show you how it works.',
      },
    },
  ], []);

  const speakAvatarConfig = useMemo(() => ({
    playerUrl: 'https://www.speakavatar.ai/api/sdk/v1/frameworks/react/embed',
    getSessionToken: getSessionToken,
    defaultAvatar: { avatarId: 'lumo' },
    avatarPosition: 'dynamic', // 'dynamic', 'next', or 'static'
  }), [getSessionToken]);

  return (
    <TourProvider steps={steps} speakAvatarConfig={speakAvatarConfig}>
      <button onClick={startTour}>Start Tour</button>
      {/* Your app content */}
    </TourProvider>
  );
}

Vanilla JavaScript Example:

import speakAvatarTour from '@speakavatar/onboarding';

async function getSessionToken() {
  const response = await fetch('/api/sdk/v1/auth/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      customerId: 'your-customer-id',
      apiKey: 'your-api-key',
      permissions: ['generate', 'preview']
    })
  });
  const data = await response.json();
  return data.token;
}

speakAvatarTour.setSpeakAvatarConfig({
  playerUrl: 'https://www.speakavatar.ai/api/sdk/v1/frameworks/react/embed',
  getSessionToken: getSessionToken,
  defaultAvatar: { avatarId: 'lumo' },
  avatarPosition: 'dynamic',
});

speakAvatarTour.setOptions({
  steps: [
    {
      element: '#feature-1',
      title: 'Feature 1',
      intro: 'This is your first feature.',
      speakAvatar: {
        text: 'Welcome! This is your first feature.',
      },
    },
  ],
}).start();

4. Avatar Position Options

• 'dynamic' (Recommended): Avatar moves with the tooltip
• 'next': Avatar positions next to tooltip
• 'static': Avatar stays in top-right corner

5. Important Security Note

⚠️ Never expose your API key in client-side code! Always call getSessionToken from your backend server to keep credentials secure.

Examples

Basic Tour

import speakAvatarTour from '@speakavatar/onboarding';
import '@speakavatar/onboarding/dist/style.css';

speakAvatarTour.setOptions({
  steps: [
    { element: '#step1', intro: 'This is step 1' },
    { element: '#step2', intro: 'This is step 2' },
  ],
}).start();

Custom Styling

Override CSS variables:

:root {
  --sat-tooltip-bg: #ffffff;
  --sat-button-bg: #007bff;
  --sat-highlight-border: 2px solid #007bff;
}

Programmatic Control

import { Tour } from '@speakavatar/onboarding';

const tour = new Tour({
  steps: [...],
  onStepChange: (step, tour) => {
    console.log('Step changed:', step);
  },
});

tour.start();
tour.next();
tour.prev();
tour.exit();

Troubleshooting

Avatar Not Appearing

• Verify getSessionToken is working and returning a valid token
• Check browser console for errors
• Ensure speakAvatarConfig is provided correctly
• Verify API credentials are correct

Avatar Not Positioning Correctly

• Try different avatarPosition values: 'dynamic', 'next', or 'static'
• Ensure tooltip elements are visible and have valid dimensions

Tour Not Starting

• Verify all element selectors match actual DOM elements
• Ensure elements are visible when tour starts
• Check that steps array is not empty

Session Token Errors

• Ensure user is logged in and has credentials
• Verify backend API endpoint is correct
• Check that getSessionToken function is provided in config

For more detailed troubleshooting, see GUIDE.md.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Additional Resources

• Complete Step-by-Step Guide - Comprehensive walkthrough for new users
• API Reference - Detailed API documentation
• Examples - Code examples and use cases

License

Proprietary - All rights reserved