cdp-lite-sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,846 @@
+# CDP Lite SDK 🚀
+
+**Customer Data Platform SDK** for tracking events and users. A lightweight, powerful analytics SDK for JavaScript/TypeScript applications.
+
+[![npm version](https://img.shields.io/npm/v/cdp-lite-sdk.svg)](https://www.npmjs.com/package/cdp-lite-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Core Methods](#core-methods)
+- [Advanced Usage](#advanced-usage)
+- [React Integration](#react-integration)
+- [TypeScript Support](#typescript-support)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## ✨ Features
+
+- ✅ **Event Tracking** - Track custom events with properties
+- ✅ **User Identification** - Identify and track users
+- ✅ **Batch Processing** - Auto-batch events for optimal performance
+- ✅ **Device Detection** - Auto-detect device information
+- ✅ **Anonymous Tracking** - Track users before identification
+- ✅ **Page/Screen Views** - Built-in page and screen tracking
+- ✅ **TypeScript Support** - Full TypeScript definitions
+- ✅ **Framework Agnostic** - Works with React, Vue, Angular, vanilla JS
+- ✅ **Browser & Node.js** - Universal JavaScript support
+- ✅ **Queue Management** - Smart event queueing and flushing
+- ✅ **Debug Mode** - Easy debugging with console logs
+
+---
+
+## 📦 Installation
+
+### NPM
+
+```bash
+npm install cdp-lite-sdk
+```
+
+### Yarn
+
+```bash
+yarn add cdp-lite-sdk
+```
+
+### CDN (Browser)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/cdp-lite-sdk/dist/cdp-lite-sdk.min.js"></script>
+```
+
+---
+
+## 🚀 Quick Start
+
+### ES6 Import (Recommended)
+
+```javascript
+import CdpLiteSdk from 'cdp-lite-sdk';
+
+// Initialize SDK
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  source: 'YourApp',
+  serviceName: 'YourService',
+  isTest: true,
+  debug: true
+});
+
+// Identify user
+cdp.identify('user_123', {
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Track event
+cdp.track('button_clicked', {
+  button_name: 'Sign Up',
+  page: 'Landing'
+});
+```
+
+### CommonJS (Node.js)
+
+```javascript
+const CdpLiteSdk = require('cdp-lite-sdk');
+
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  source: 'BackendService'
+});
+```
+
+### Browser (Script Tag)
+
+```html
+<script src="path/to/cdp-lite-sdk.min.js"></script>
+<script>
+  const cdp = new CdpLiteSdk({
+    apiKey: 'your-api-key',
+    source: 'WebApp'
+  });
+  
+  cdp.track('page_view', { page: 'Home' });
+</script>
+```
+
+---
+
+## ⚙️ Configuration
+
+### Configuration Options
+
+```javascript
+const cdp = new CdpLiteSdk({
+  // Required
+  apiKey: 'string',              // Your API key
+  
+  // Optional
+  source: 'string',              // Source name (default: 'Web')
+  serviceName: 'string',         // Service name (default: 'DefaultService')
+  baseUrl: 'string',             // API base URL
+  isTest: boolean,               // Test mode (default: false)
+  debug: boolean,                // Enable debug logs (default: false)
+  batchSize: number,             // Events per batch (default: 10)
+  batchInterval: number,         // Batch interval in ms (default: 5000)
+  autoTrackDevice: boolean       // Auto detect device (default: true)
+});
+```
+
+### Example Configurations
+
+#### Development
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: 'dev-api-key',
+  source: 'MyApp',
+  serviceName: 'MyService',
+  baseUrl: 'https://vconnect-dev.vietcredit.com.vn',
+  isTest: true,
+  debug: true,
+  batchSize: 5,
+  batchInterval: 3000
+});
+```
+
+#### Production
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: process.env.CDP_API_KEY,
+  source: 'MyApp',
+  serviceName: 'MyService',
+  baseUrl: 'https://vconnect.vietcredit.com.vn',
+  isTest: false,
+  debug: false,
+  batchSize: 20,
+  batchInterval: 10000
+});
+```
+
+---
+
+## 📚 Core Methods
+
+### 1. Track Events
+
+Track custom events with properties.
+
+```javascript
+cdp.track(eventName, properties, options);
+```
+
+**Parameters:**
+- `eventName` (string) - Name of the event
+- `properties` (object) - Event properties (optional)
+- `options` (object) - Additional options (optional)
+
+**Example:**
+
+```javascript
+// Basic event
+cdp.track('purchase_completed', {
+  product_id: 'PROD123',
+  amount: 99.99,
+  currency: 'USD'
+});
+
+// With loan code
+cdp.track('loan_application', {
+  amount: 50000000,
+  term: 12
+}, {
+  loanCode: 'LOAN123'
+});
+
+// With campaign data
+cdp.track('signup', {
+  method: 'email'
+}, {
+  campaign: {
+    source: 'facebook',
+    medium: 'cpc',
+    campaign: 'summer_sale'
+  }
+});
+```
+
+### 2. Identify Users
+
+Identify users and set their attributes.
+
+```javascript
+cdp.identify(userId, traits);
+```
+
+**Parameters:**
+- `userId` (string) - Unique user identifier
+- `traits` (object) - User attributes (optional)
+
+**Example:**
+
+```javascript
+cdp.identify('user_123', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  phone: '+84901234567',
+  age: 30,
+  city: 'Hanoi',
+  plan: 'premium'
+});
+```
+
+### 3. Page Views
+
+Track page views (for web applications).
+
+```javascript
+cdp.page(pageName, properties);
+```
+
+**Example:**
+
+```javascript
+cdp.page('Home', {
+  url: window.location.href,
+  title: document.title,
+  referrer: document.referrer
+});
+
+cdp.page('Product Details', {
+  product_id: 'PROD123',
+  category: 'Electronics'
+});
+```
+
+### 4. Screen Views
+
+Track screen views (for mobile applications).
+
+```javascript
+cdp.screen(screenName, properties);
+```
+
+**Example:**
+
+```javascript
+cdp.screen('Home Screen', {
+  tab: 'featured'
+});
+
+cdp.screen('Product Detail', {
+  product_id: 'PROD123'
+});
+```
+
+### 5. Update User Attributes
+
+Update user attributes without re-identifying.
+
+```javascript
+cdp.setUserAttributes(traits);
+```
+
+**Example:**
+
+```javascript
+cdp.setUserAttributes({
+  subscription: 'premium',
+  last_login: new Date().toISOString(),
+  total_purchases: 5
+});
+```
+
+### 6. Set Device Info
+
+Manually set device information.
+
+```javascript
+cdp.setDeviceInfo(deviceInfo);
+```
+
+**Example:**
+
+```javascript
+cdp.setDeviceInfo({
+  platform: 'ios',
+  brand: 'Apple',
+  model: 'iPhone 14 Pro',
+  app_version: '2.1.0',
+  os_version: '16.3'
+});
+```
+
+### 7. Flush Events
+
+Manually send all queued events immediately.
+
+```javascript
+await cdp.flush();
+```
+
+**Example:**
+
+```javascript
+// Add multiple events
+cdp.track('event_1');
+cdp.track('event_2');
+cdp.track('event_3');
+
+// Send all immediately
+await cdp.flush();
+```
+
+### 8. Reset User
+
+Clear user data (useful for logout).
+
+```javascript
+cdp.reset();
+```
+
+**Example:**
+
+```javascript
+function handleLogout() {
+  cdp.reset();
+  // Redirect to login page
+}
+```
+
+### 9. Cleanup
+
+Clean up resources when done.
+
+```javascript
+cdp.destroy();
+```
+
+---
+
+## 🔥 Advanced Usage
+
+### Batch Processing
+
+SDK automatically batches events for efficiency.
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  batchSize: 20,        // Send after 20 events
+  batchInterval: 10000  // Or after 10 seconds
+});
+
+// These will be batched
+cdp.track('event_1');
+cdp.track('event_2');
+cdp.track('event_3');
+// ... will send when 20 events or 10 seconds
+```
+
+### Disable Batching
+
+Send events immediately:
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  batchSize: 1  // Send immediately
+});
+```
+
+### Error Handling
+
+```javascript
+try {
+  await cdp.track('event_name', { data: 'value' });
+  console.log('Event tracked successfully');
+} catch (error) {
+  console.error('Failed to track event:', error);
+}
+```
+
+### Custom Context
+
+```javascript
+cdp.track('checkout', {
+  total: 299.99
+}, {
+  context: {
+    ip: '192.168.1.1',
+    locale: 'vi_VN',
+    timezone: 'Asia/Ho_Chi_Minh',
+    user_agent: navigator.userAgent
+  }
+});
+```
+
+---
+
+## ⚛️ React Integration
+
+### Setup Analytics Context
+
+```javascript
+// analytics.js
+import CdpLiteSdk from 'cdp-lite-sdk';
+
+export const cdp = new CdpLiteSdk({
+  apiKey: process.env.REACT_APP_CDP_API_KEY,
+  source: 'WebApp',
+  serviceName: 'MyApp',
+  debug: process.env.NODE_ENV === 'development'
+});
+
+export default cdp;
+```
+
+### Custom Hook
+
+```javascript
+// useAnalytics.js
+import { useCallback } from 'react';
+import { cdp } from './analytics';
+
+export function useAnalytics() {
+  const trackEvent = useCallback((eventName, properties) => {
+    cdp.track(eventName, properties);
+  }, []);
+
+  const identifyUser = useCallback((userId, traits) => {
+    cdp.identify(userId, traits);
+  }, []);
+
+  const trackPageView = useCallback((pageName, properties) => {
+    cdp.page(pageName, properties);
+  }, []);
+
+  return { trackEvent, identifyUser, trackPageView };
+}
+```
+
+### Usage in Components
+
+```javascript
+// Component.jsx
+import { useAnalytics } from './useAnalytics';
+
+function ProductPage({ product }) {
+  const { trackEvent, trackPageView } = useAnalytics();
+
+  useEffect(() => {
+    trackPageView('Product Detail', {
+      product_id: product.id,
+      product_name: product.name
+    });
+  }, [product]);
+
+  const handleAddToCart = () => {
+    trackEvent('add_to_cart', {
+      product_id: product.id,
+      price: product.price
+    });
+  };
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <button onClick={handleAddToCart}>Add to Cart</button>
+    </div>
+  );
+}
+```
+
+### Auto Page Tracking
+
+```javascript
+// App.jsx
+import { useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+import { cdp } from './analytics';
+
+function App() {
+  const location = useLocation();
+
+  useEffect(() => {
+    cdp.page(location.pathname, {
+      path: location.pathname,
+      search: location.search
+    });
+  }, [location]);
+
+  return <YourApp />;
+}
+```
+
+---
+
+## 🎯 TypeScript Support
+
+Full TypeScript support with type definitions.
+
+```typescript
+import CdpLiteSdk, { CdpConfig, EventProperties, UserTraits } from 'cdp-lite-sdk';
+
+const config: CdpConfig = {
+  apiKey: 'your-api-key',
+  source: 'MyApp',
+  debug: true
+};
+
+const cdp = new CdpLiteSdk(config);
+
+const userTraits: UserTraits = {
+  name: 'John Doe',
+  email: 'john@example.com',
+  age: 30
+};
+
+cdp.identify('user_123', userTraits);
+
+const eventProps: EventProperties = {
+  product_id: '123',
+  price: 99.99,
+  currency: 'USD'
+};
+
+cdp.track('purchase', eventProps);
+```
+
+---
+
+## 📖 API Reference
+
+### Constructor
+
+```typescript
+new CdpLiteSdk(config: CdpConfig)
+```
+
+### Methods
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `track()` | `eventName, properties?, options?` | `Promise<any> \| void` | Track an event |
+| `identify()` | `userId, traits?` | `Promise<any> \| void` | Identify a user |
+| `page()` | `pageName, properties?` | `Promise<any> \| void` | Track page view |
+| `screen()` | `screenName, properties?` | `Promise<any> \| void` | Track screen view |
+| `setUserAttributes()` | `traits` | `Promise<any> \| void` | Update user attrs |
+| `setDeviceInfo()` | `deviceInfo` | `void` | Set device info |
+| `flush()` | - | `Promise<any>` | Flush event queue |
+| `reset()` | - | `void` | Reset user data |
+| `destroy()` | - | `void` | Cleanup resources |
+
+---
+
+## 💡 Examples
+
+### E-commerce Tracking
+
+```javascript
+// Product viewed
+cdp.track('product_viewed', {
+  product_id: 'SKU123',
+  product_name: 'iPhone 14',
+  price: 20000000,
+  currency: 'VND',
+  category: 'Electronics'
+});
+
+// Add to cart
+cdp.track('add_to_cart', {
+  product_id: 'SKU123',
+  quantity: 1,
+  price: 20000000
+});
+
+// Checkout
+cdp.track('checkout_started', {
+  cart_total: 20000000,
+  item_count: 1
+});
+
+// Purchase
+cdp.track('purchase_completed', {
+  order_id: 'ORDER789',
+  total: 20000000,
+  currency: 'VND',
+  payment_method: 'credit_card'
+});
+```
+
+### Loan Application Flow
+
+```javascript
+// Start application
+cdp.track('loan_application_started', {
+  loan_amount: 50000000,
+  loan_term: 12,
+  loan_type: 'personal'
+});
+
+// Step completed
+cdp.track('application_step_completed', {
+  step_name: 'personal_info',
+  step_number: 1
+}, {
+  loanCode: 'LOAN123'
+});
+
+// Submit application
+cdp.track('loan_application_submitted', {
+  loan_amount: 50000000,
+  loan_term: 12
+}, {
+  loanCode: 'LOAN123'
+});
+```
+
+### User Authentication
+
+```javascript
+// Registration
+cdp.track('user_registered', {
+  method: 'email',
+  source: 'organic'
+});
+
+cdp.identify('user_123', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  created_at: new Date().toISOString()
+});
+
+// Login
+cdp.track('user_logged_in', {
+  method: 'email'
+});
+
+// Logout
+cdp.track('user_logged_out');
+cdp.reset();
+```
+
+### Form Tracking
+
+```javascript
+// Form started
+cdp.track('form_started', {
+  form_name: 'contact_form',
+  form_id: 'contact_123'
+});
+
+// Field completed
+cdp.track('form_field_completed', {
+  form_name: 'contact_form',
+  field_name: 'email'
+});
+
+// Form submitted
+cdp.track('form_submitted', {
+  form_name: 'contact_form',
+  fields_count: 5,
+  time_spent: 120 // seconds
+});
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Events Not Sending
+
+**Problem:** Events are not being tracked
+
+**Solutions:**
+1. Check API key is correct
+2. Enable debug mode: `debug: true`
+3. Check network tab in DevTools
+4. Verify baseUrl is correct
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  debug: true  // Enable logging
+});
+```
+
+### Import Errors
+
+**Problem:** `SyntaxError: The requested module does not provide an export named 'default'`
+
+**Solutions:**
+
+Use one of these import methods:
+
+```javascript
+// Method 1: Default import (recommended)
+import CdpLiteSdk from 'cdp-lite-sdk';
+
+// Method 2: Named import
+import { CdpLiteSdk } from 'cdp-lite-sdk';
+
+// Method 3: CommonJS
+const CdpLiteSdk = require('cdp-lite-sdk');
+```
+
+### CORS Issues
+
+**Problem:** CORS error in browser console
+
+**Solution:** Ensure your domain is whitelisted on the API server.
+
+### Events Delayed
+
+**Problem:** Events take time to send
+
+**Explanation:** Events are batched by default for performance.
+
+**Solutions:**
+
+```javascript
+// Reduce batch size
+const cdp = new CdpLiteSdk({
+  apiKey: 'your-api-key',
+  batchSize: 1  // Send immediately
+});
+
+// Or manually flush
+cdp.track('important_event', {...});
+await cdp.flush();
+```
+
+### TypeScript Errors
+
+**Problem:** Type errors in TypeScript
+
+**Solution:** Ensure types are imported:
+
+```typescript
+import CdpLiteSdk, { CdpConfig } from 'cdp-lite-sdk';
+
+const config: CdpConfig = {
+  apiKey: 'your-api-key'
+};
+
+const cdp = new CdpLiteSdk(config);
+```
+
+---
+
+## 📝 Event Naming Best Practices
+
+Use `object_action` format:
+
+```javascript
+// ✅ Good
+cdp.track('product_viewed');
+cdp.track('cart_item_added');
+cdp.track('checkout_completed');
+cdp.track('user_registered');
+
+// ❌ Avoid
+cdp.track('viewProduct');
+cdp.track('AddItemToCart');
+cdp.track('CHECKOUT');
+```
+
+---
+
+## 🔒 Privacy & Security
+
+- SDK automatically generates anonymous IDs
+- User data is only sent after explicit `identify()` call
+- All data transmitted over HTTPS
+- API keys should be kept secure
+- Never commit API keys to version control
+
+---
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+---
+
+## 🤝 Support
+
+- **Email:** vinv@vega.com.vn
+
+---
+
+## 🎉 Quick Reference
+
+```javascript
+// Initialize
+const cdp = new CdpLiteSdk({ apiKey: 'key' });
+
+// Identify
+cdp.identify('user_id', { name: 'John' });
+
+// Track
+cdp.track('event_name', { prop: 'value' });
+
+// Page
+cdp.page('Page Name');
+
+// Flush
+await cdp.flush();
+
+// Reset
+cdp.reset();
+```
+
+---
+
+Made with ❤️ by Your Team