TourGuide Widget

Embeddable onboarding tour widget with Three.js 3D avatars and advanced analytics.

🚀 Features

• Lightweight: ~50KB gzipped
• Framework Agnostic: Works with any JavaScript framework or vanilla JS
• 3D Avatars: Optional Three.js animated characters
• Smart Positioning: Automatic tooltip positioning with collision detection
• Resume Support: Automatically saves progress to localStorage
• Analytics: Built-in event tracking and session management
• Responsive: Mobile-friendly design
• Accessible: ARIA labels and keyboard navigation
• Customizable: Theme support, custom CSS, and JavaScript hooks

📦 Installation

Option 1: CDN (Script Tag)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tourguide-widget.js"></script>
<script>
  TourGuide.init({
    tourId: 'your_tour_id',
    apiKey: 'your_api_key'
  });
</script>

Option 2: NPM

npm install @tourguide/widget

import TourGuide from '@tourguide/widget';
import '@tourguide/widget/dist/styles.css';

TourGuide.init({
  tourId: 'your_tour_id',
  apiKey: 'your_api_key'
});

Option 3: React

import { useEffect } from 'react';
import TourGuide from '@tourguide/widget';
import '@tourguide/widget/dist/styles.css';

function App() {
  useEffect(() => {
    TourGuide.init({
      tourId: 'your_tour_id',
      apiKey: 'your_api_key',
      autoStart: true
    });

    return () => {
      TourGuide.destroy();
    };
  }, []);

  return <div>Your App</div>;
}

🎯 API Reference

TourGuide.init(config)

Initialize the tour widget.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tourId | string | Yes | Your tour ID from the dashboard | | apiKey | string | Yes | Your API key | | autoStart | boolean | No | Auto-start the tour (default: true) | | theme | 'light' \| 'dark' \| 'auto' | No | Theme (default: 'light') | | onComplete | function | No | Callback when tour completes | | onSkip | function | No | Callback when tour is skipped | | onStepChange | function | No | Callback when step changes | | debug | boolean | No | Enable debug logging |

Example:

TourGuide.init({
  tourId: 'tour_abc123',
  apiKey: 'pk_live_xyz789',
  autoStart: false,
  theme: 'dark',
  onComplete: () => {
    console.log('Tour completed!');
  },
  onSkip: () => {
    console.log('Tour skipped');
  },
  onStepChange: (step) => {
    console.log('Current step:', step);
  }
});

TourGuide.start()

Manually start the tour.

TourGuide.start();

TourGuide.next()

Go to the next step.

TourGuide.next();

TourGuide.back()

Go to the previous step.

TourGuide.back();

TourGuide.skip()

Skip the tour.

TourGuide.skip();

TourGuide.restart()

Restart the tour from the beginning.

TourGuide.restart();

TourGuide.destroy()

Destroy the tour instance and clean up.

TourGuide.destroy();

🎨 Customization

Custom Styling

Override default styles by targeting the CSS classes:

.tourguide-tooltip-inner {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.tourguide-btn-primary {
  background: #your-brand-color;
}

Custom Theme

TourGuide.init({
  tourId: 'your_tour_id',
  apiKey: 'your_api_key',
  theme: 'dark' // or 'light', 'auto'
});

3D Avatar

Enable 3D avatars in your tour configuration from the dashboard.

📊 Analytics

The widget automatically tracks:

• Session starts
• Step views and completions
• Time spent per step
• Skip and abandonment rates
• Device and browser information
• User interactions

All analytics are sent to your TourGuide dashboard in real-time.

🔒 Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• Mobile browsers (iOS Safari, Chrome Mobile)

🛠️ Development

Build

npm run build

Development Server

npm run dev

Type Checking

npm run type-check

📝 License

MIT

🤝 Contributing

This is part of the HNG Internship Stage 8 project.

📧 Support

For issues or questions, please contact the team or create an issue in the repository.# Mee