quala-widget/README.md

Smart feedback widget for SaaS trial optimization

# Quala React SDK

> **Stop losing 60%+ of your trial users without knowing why.**

Smart feedback widget purpose-built for SaaS trial-to-paid conversion optimization. Unlike generic survey tools, Quala knows when to ask the right questions during your user's trial journey.

## ⚡ Why Quala vs Generic Tools?

| Generic Tools (Hotjar $32, Typeform $25) | Quala ($25) |
|-----------------------------------|--------|
| ❌ Same questions for everyone | ✅ Trial-specific questions |
| ❌ Random timing | ✅ Smart triggers (Day 3, 7, 14) |
| ❌ Too late when users churn | ✅ Real-time trial insights |
| ❌ Developers needed for changes | ✅ Dashboard control |

## 🚀 Quick Start

### Install
```bash
npm install quala-widget
```

### Setup (2 minutes)
```tsx
import React, { useEffect } from 'react';
import { useQualaInit, useQuala } from 'quala-widget';

// 1. Initialize once at app root
function App() {
  useQualaInit({
    apiKey: 'qla_xxxxxxxxxxxxxxxx' // Get key at getquala.xyz
  });
  return <YourApp />;
}

// 2. Identify trial users
function Dashboard() {
  const { identifyUser, trackEvent, triggerSmartFeedback } = useQuala();

  useEffect(() => {
    identifyUser({
      userId: 'user-123',
      email: 'user@company.com',
      trialStartDate: '2024-01-15T00:00:00Z'
    });

    // Check for feedback (dashboard controls when/what to show)
    triggerSmartFeedback();
  }, []);

  const handleFeatureUse = () => {
    trackEvent('feature_used', { feature: 'dashboard' });
  };

  return <button onClick={handleFeatureUse}>Use Feature</button>;
}
```

**Done!** Your dashboard at [getquala.xyz](https://getquala.xyz) controls all questions and timing.

## 🎨 Custom Styling

Match Quala to your brand with detailed color customization:

```tsx
useQualaInit({
  apiKey: 'your-api-key',
  modalStyle: {
    modalColor: 'rgba(0, 0, 0, 0.7)',      // Backdrop overlay
    modalBoxColor: '#ffffff',              // Modal background  
    triggerColor: '#007bff',               // Trigger button
    progressBarColor: '#007bff',           // Progress fill
    progressTrackColor: '#e9ecef',         // Progress track
    buttonColor: '#007bff',                // Primary buttons
    backButtonColor: '#6c757d',            // Back button
    inputFocusColor: '#007bff',            // Input focus border
  }
});
```

### Preset Themes

**Professional Blue**
```tsx
modalStyle: {
  triggerColor: '#007bff',
  progressBarColor: '#007bff', 
  buttonColor: '#007bff',
  inputFocusColor: '#007bff',
}
```

**Modern Purple**
```tsx
modalStyle: {
  modalColor: 'rgba(0, 0, 0, 0.8)',
  modalBoxColor: '#2d3748',
  triggerColor: '#9f7aea',
  progressBarColor: '#9f7aea',
  buttonColor: '#9f7aea',
  inputFocusColor: '#9f7aea',
}
```

**Success Green**
```tsx
modalStyle: {
  triggerColor: '#28a745',
  progressBarColor: '#28a745',
  buttonColor: '#28a745',
  inputFocusColor: '#28a745',
}
```

## 📚 API Reference

### `useQualaInit(config)`
```tsx
useQualaInit({
  apiKey: string;                    // Required: Your API key
  modalStyle?: {                     // Optional: Color customization
    modalColor?: string;             // Modal backdrop color
    modalBoxColor?: string;          // Modal box background color
    triggerColor?: string;           // Trigger button background color
    progressBarColor?: string;       // Progress bar fill color
    progressTrackColor?: string;     // Progress bar track color
    buttonColor?: string;            // Primary button background color
    backButtonColor?: string;        // Back button background color
    inputFocusColor?: string;        // Input border color on focus
  };
  options?: {
    debug?: boolean;                 // Enable logging
  };
});
```

### `useQuala()`
```tsx
const { identifyUser, trackEvent, triggerSmartFeedback } = useQuala();
```

- **`identifyUser(user)`** - Call when trial starts
- **`trackEvent(event, props)`** - Track user actions  
- **`triggerSmartFeedback()`** - Check if feedback should show

## 🌐 Works With Any Framework

The SDK works with **any web framework** - it creates an isolated React widget that your framework never sees:

### React
```tsx
import { useQualaInit, useQuala } from 'quala-widget';

function App() {
  useQualaInit({ 
    apiKey: 'your-api-key',
    modalStyle: {
      buttonColor: '#your-brand-color'
    }
  });
  return <YourApp />;
}
```

### Next.js (App Router)
```tsx
// components/QualaProvider.tsx
"use client";
import { useQualaInit } from 'quala-widget';

export function QualaProvider() {
  useQualaInit({
    apiKey: 'your-api-key',
    modalStyle: {
      triggerColor: '#007bff',
      buttonColor: '#007bff',
    }
  });
  return null;
}

// app/layout.tsx
import { QualaProvider } from './components/QualaProvider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <QualaProvider />
        {children}
      </body>
    </html>
  );
}
```

### Next.js (Pages Router)
```tsx
// pages/_app.tsx
import { useQualaInit } from 'quala-widget';

export default function App({ Component, pageProps }) {
  useQualaInit({ 
    apiKey: 'your-api-key',
    modalStyle: {
      buttonColor: '#your-brand-color'
    }
  });
  
  return <Component {...pageProps} />;
}
```

### Vue.js
```javascript
import { qualaSdk } from 'quala-widget';

// In your Vue component
mounted() {
  qualaSdk.initialize('your-api-key', {
    modalStyle: {
      buttonColor: '#your-brand-color'
    }
  });
  qualaSdk.identifyUser({ userId: 'user-123' });
  qualaSdk.triggerSmartFeedback();
}
```

### Angular
```javascript
import { qualaSdk } from 'quala-widget';

// In your Angular component
ngOnInit() {
  qualaSdk.initialize('your-api-key', {
    modalStyle: {
      buttonColor: '#your-brand-color'
    }
  });
  qualaSdk.identifyUser({ userId: 'user-123' });
  qualaSdk.triggerSmartFeedback();
}
```

### Vanilla JS
```javascript
import { qualaSdk } from 'quala-widget';

qualaSdk.initialize('your-api-key', {
  modalStyle: {
    triggerColor: '#007bff',
    buttonColor: '#007bff',
  }
});
qualaSdk.identifyUser({ userId: 'user-123' });
qualaSdk.triggerSmartFeedback();
```

## 🎯 Current Features (v1.0)

- ✅ **Day-based triggers**: Day 3, 7, 14 trial check-ins
- ✅ **Dashboard control**: Change questions without code deploys
- ✅ **Universal compatibility**: React, Vue, Angular, Svelte, Vanilla JS
- ✅ **Session tracking**: No localStorage issues
- ✅ **Custom styling**: 8-point color customization system

## 🚧 Coming Soon

- **Feature-based triggers**: After premium feature usage
- **Milestone triggers**: First project, usage thresholds
- **Advanced analytics**: Conversion insights

## 📞 Support

- 📖 **Dashboard**: [getquala.xyz](https://getquala.xyz)
- 💬 **Support**: support@getquala.xyz

**Ready to understand why your trial users churn?**

🚀 [Start Free Trial →](https://getquala.xyz)

---

## 📄 License

MIT License