@product7/feedback-sdk 1.1.8 → 1.2.0

package/README.md

@@ -368,6 +368,462 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
+## Survey Widget
+
+The SDK includes a powerful survey widget for collecting structured user feedback through NPS, CSAT, CES, and custom surveys. Surveys can be triggered manually, on specific events, or managed through the backend dashboard.
+
+### Survey Types
+
+| Type       | Description           | Scale                    |
+| ---------- | --------------------- | ------------------------ |
+| **NPS**    | Net Promoter Score    | 0-10 numeric scale       |
+| **CSAT**   | Customer Satisfaction | 5-point emoji scale      |
+| **CES**    | Customer Effort Score | 5-level difficulty scale |
+| **Custom** | Multi-question forms  | Flexible input types     |
+
+### Quick Start
+
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'your-workspace',
+	boardId: 'your-board-id',
+});
+
+await feedback.init();
+
+// Show NPS survey
+feedback.showSurvey({
+	surveyType: 'nps',
+	title: 'How likely are you to recommend us?',
+	onSubmit: (response) => {
+		console.log('Survey submitted:', response);
+	},
+});
+```
+
+### Survey Configuration Options
+
+```javascript
+feedback.showSurvey({
+	surveyId: 'backend-survey-id', // Optional: links response to backend survey
+	surveyType: 'nps', // 'nps' | 'csat' | 'ces' | 'custom'
+	position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'center' | 'bottom'
+	theme: 'light', // 'light' | 'dark'
+	title: 'Your survey title',
+	description: 'Optional description',
+	lowLabel: 'Not likely', // Low end label (NPS/CES)
+	highLabel: 'Very likely', // High end label (NPS/CES)
+	customQuestions: [], // For custom surveys
+	onSubmit: (response) => {},
+	onDismiss: () => {},
+});
+```
+
+---
+
+### Backend-Driven Surveys
+
+For surveys configured in the Product7 dashboard, use `showSurveyById()` to fetch and display them:
+
+```javascript
+// Show a specific survey by its backend ID
+await feedback.showSurveyById('survey_abc123', {
+	position: 'center', // Override position if needed
+	onSubmit: (response) => {
+		console.log('Survey completed:', response);
+	},
+});
+```
+
+### Fetching Active Surveys
+
+Retrieve surveys that match the current user's targeting criteria:
+
+```javascript
+// Get all active surveys for the current context
+const surveys = await feedback.getActiveSurveys();
+
+console.log('Available surveys:', surveys);
+// [{ id: 'survey_123', type: 'nps', title: '...', ... }]
+
+// Show the first matching survey
+if (surveys.length > 0) {
+	await feedback.showSurveyById(surveys[0].id);
+}
+```
+
+With custom targeting context:
+
+```javascript
+const surveys = await feedback.getActiveSurveys({
+	url: '/dashboard/settings', // Override current URL
+	userProperties: {
+		plan: 'enterprise',
+		feature_usage: 'high',
+	},
+});
+```
+
+---
+
+### Survey Types
+
+#### NPS Survey (Net Promoter Score)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'nps',
+	title: 'How likely are you to recommend us to a friend?',
+	lowLabel: 'Not at all likely',
+	highLabel: 'Extremely likely',
+	position: 'bottom-right',
+	onSubmit: (response) => {
+		console.log('Score:', response.score); // 0-10
+		console.log('Feedback:', response.feedback);
+	},
+});
+```
+
+#### CSAT Survey (Customer Satisfaction)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'csat',
+	title: 'How satisfied are you with our service?',
+	position: 'center',
+	theme: 'dark',
+	onSubmit: (response) => {
+		console.log('Satisfaction:', response.score); // 1-5
+	},
+});
+```
+
+#### CES Survey (Customer Effort Score)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'ces',
+	title: 'How easy was it to complete your task?',
+	position: 'bottom',
+	onSubmit: (response) => {
+		console.log('Effort score:', response.score); // 1-5
+	},
+});
+```
+
+#### Custom Survey
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'custom',
+	title: 'Quick Feedback',
+	customQuestions: [
+		{
+			id: 'feature',
+			type: 'select',
+			label: 'Which feature do you use most?',
+			options: [
+				{ value: 'dashboard', label: 'Dashboard' },
+				{ value: 'reports', label: 'Reports' },
+				{ value: 'settings', label: 'Settings' },
+			],
+		},
+		{
+			id: 'improvement',
+			type: 'text',
+			label: 'What could we improve?',
+			placeholder: 'Your suggestions...',
+		},
+	],
+	onSubmit: (response) => {
+		console.log('Answers:', response.customAnswers);
+		// { feature: 'dashboard', improvement: 'Better charts' }
+	},
+});
+```
+
+---
+
+### Event-Triggered Surveys
+
+Trigger surveys based on user actions:
+
+```javascript
+// After completing a purchase
+document.getElementById('checkout-btn').addEventListener('click', async () => {
+	await processPayment();
+
+	feedback.showSurvey({
+		surveyType: 'csat',
+		title: 'How was your checkout experience?',
+		position: 'center',
+	});
+});
+
+// After closing support chat
+chatWidget.on('close', () => {
+	feedback.showSurvey({
+		surveyType: 'ces',
+		title: 'How easy was it to get help?',
+		position: 'bottom-right',
+	});
+});
+
+// On page exit intent
+document.addEventListener('mouseleave', (e) => {
+	if (e.clientY < 0 && !sessionStorage.getItem('exit_survey_shown')) {
+		sessionStorage.setItem('exit_survey_shown', 'true');
+		feedback.showSurvey({
+			surveyType: 'nps',
+			title: 'Before you go...',
+			description: 'How likely are you to recommend us?',
+			position: 'center',
+		});
+	}
+});
+```
+
+### Time-Based Surveys
+
+```javascript
+// Show after 60 seconds on page
+setTimeout(() => {
+	feedback.showSurvey({
+		surveyType: 'nps',
+		title: 'Enjoying our product?',
+		position: 'bottom-right',
+	});
+}, 60000);
+
+// Show after N page views
+const pageViews = parseInt(localStorage.getItem('page_views') || '0') + 1;
+localStorage.setItem('page_views', pageViews);
+
+if (pageViews === 5) {
+	feedback.showSurvey({
+		surveyType: 'csat',
+		title: 'How are you finding things so far?',
+	});
+}
+```
+
+---
+
+### React Integration
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { FeedbackSDK } from '@product7/feedback-sdk';
+
+function useSurvey() {
+	const sdkRef = useRef(null);
+
+	useEffect(() => {
+		const sdk = new FeedbackSDK({
+			workspace: 'your-workspace',
+			userContext: {
+				user_id: currentUser.id,
+				email: currentUser.email,
+			},
+		});
+
+		sdk.init().then(() => {
+			sdkRef.current = sdk;
+		});
+
+		return () => sdk.destroy();
+	}, []);
+
+	const showNPS = (options = {}) => {
+		sdkRef.current?.showSurvey({
+			surveyType: 'nps',
+			...options,
+		});
+	};
+
+	const showCSAT = (options = {}) => {
+		sdkRef.current?.showSurvey({
+			surveyType: 'csat',
+			...options,
+		});
+	};
+
+	return { showNPS, showCSAT };
+}
+
+// Usage in component
+function CheckoutSuccess() {
+	const { showCSAT } = useSurvey();
+
+	useEffect(() => {
+		showCSAT({
+			title: 'How was your checkout experience?',
+			position: 'center',
+		});
+	}, []);
+
+	return <div>Thank you for your purchase!</div>;
+}
+```
+
+### Vue.js Integration
+
+```vue
+<script setup>
+	import { onMounted, onUnmounted, ref } from 'vue';
+	import { FeedbackSDK } from '@product7/feedback-sdk';
+
+	const sdk = ref(null);
+
+	onMounted(async () => {
+		sdk.value = new FeedbackSDK({
+			workspace: 'your-workspace',
+			userContext: {
+				user_id: currentUser.value.id,
+				email: currentUser.value.email,
+			},
+		});
+		await sdk.value.init();
+	});
+
+	onUnmounted(() => {
+		sdk.value?.destroy();
+	});
+
+	const showSurvey = (type, options = {}) => {
+		sdk.value?.showSurvey({
+			surveyType: type,
+			...options,
+		});
+	};
+
+	// Trigger on button click
+	const handleFeedbackClick = () => {
+		showSurvey('nps', {
+			title: 'How likely are you to recommend us?',
+			position: 'center',
+		});
+	};
+</script>
+```
+
+---
+
+### Survey Events
+
+```javascript
+// Survey displayed
+feedback.eventBus.on('survey:shown', (data) => {
+	console.log('Survey displayed:', data.type);
+	analytics.track('Survey Shown', { type: data.type });
+});
+
+// Survey submitted
+feedback.eventBus.on('survey:submitted', (data) => {
+	console.log('Survey submitted:', data.response);
+	analytics.track('Survey Completed', {
+		type: data.response.type,
+		score: data.response.score,
+	});
+});
+
+// Survey dismissed without completing
+feedback.eventBus.on('survey:dismissed', (data) => {
+	console.log('Survey dismissed');
+	analytics.track('Survey Dismissed');
+});
+```
+
+### Response Data Format
+
+```javascript
+// NPS/CSAT/CES response
+{
+  type: 'nps',
+  score: 9,
+  feedback: 'Great product!',
+  timestamp: '2025-01-26T10:30:00.000Z'
+}
+
+// Custom survey response
+{
+  type: 'custom',
+  score: null,
+  feedback: 'Additional comments here',
+  customAnswers: {
+    feature: 'dashboard',
+    improvement: 'Better mobile support'
+  },
+  timestamp: '2025-01-26T10:30:00.000Z'
+}
+```
+
+---
+
+### Position Options
+
+| Position       | Description                   |
+| -------------- | ----------------------------- |
+| `bottom-right` | Bottom right corner (default) |
+| `bottom-left`  | Bottom left corner            |
+| `center`       | Centered modal with backdrop  |
+| `bottom`       | Full-width bottom bar         |
+
+### Theme Options
+
+| Theme   | Description                           |
+| ------- | ------------------------------------- |
+| `light` | White background, dark text (default) |
+| `dark`  | Dark background, light text           |
+
+---
+
+### Programmatic Control
+
+```javascript
+// Create survey widget for later use
+const survey = feedback.createWidget('survey', {
+	surveyType: 'nps',
+	title: 'Rate us',
+});
+survey.mount();
+
+// Show when ready
+survey.show();
+
+// Hide programmatically
+survey.hide();
+
+// Destroy when done
+survey.destroy();
+```
+
+### Survey Rate Limiting
+
+Avoid survey fatigue by tracking when surveys were last shown:
+
+```javascript
+const SURVEY_COOLDOWN = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+function canShowSurvey(surveyType) {
+	const lastShown = localStorage.getItem(`survey_${surveyType}_shown`);
+	if (!lastShown) return true;
+	return Date.now() - parseInt(lastShown) > SURVEY_COOLDOWN;
+}
+
+function showSurveyWithCooldown(options) {
+	if (!canShowSurvey(options.surveyType)) {
+		console.log('Survey on cooldown');
+		return null;
+	}
+
+	localStorage.setItem(`survey_${options.surveyType}_shown`, Date.now());
+	return feedback.showSurvey(options);
+}
+```
+
+---
+
 ## Related
 
 - [Product7 Platform](https://product7.io)