@ordersune/crm-web-sdk 1.0.12 → 1.0.14

package/README.md

@@ -1,6 +1,6 @@
 # Order Sune CRM TypeScript SDK
 
-A powerful TypeScript SDK for integrating the Order Sune CRM solution into your web applications. Enables seamless user tracking, event monitoring, and customer data management.
+A comprehensive TypeScript SDK for integrating the Order Sune CRM solution into your web applications. Enables seamless user tracking, event monitoring, purchase analytics, in-app messaging, and customer data management.
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm install @ordersune/crm-web-sdk
 yarn add @ordersune/crm-web-sdk
 ```
 
-## Usage
+## Quick Start
 
 ### Initialize the SDK
 
@@ -20,32 +20,35 @@ import { WebSDK } from '@ordersune/crm-web-sdk';
 const crm = new WebSDK({
   apiKey: 'your-api-key',
   endpoint: 'https://api.example.com',
-  debug: false 
+  debug: false,
+  batchSize: 10,
+  batchInterval: 10000
 });
 ```
 
-### User Identification
+## Core Features
 
-Identify and track users with custom traits:
+### User Management
+
+#### User Identification
+Track both registered and guest users:
 
 ```typescript
 // Identify a registered user
-crm.identify('user123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-  subscription: 'premium'
-});
+crm.identify('user123');
 
 // Get current user profile
 const userProfile = crm.getUserProfile();
+
+// Clear user data and generate new device ID
+crm.clearUserData();
 ```
 
 ### Event Tracking
 
-Track user events with custom properties:
-
+#### Basic Event Tracking
 ```typescript
-// Basic event tracking
+// Simple event
 crm.trackEvent('page_view');
 
 // Event with properties
@@ -65,34 +68,113 @@ crm.trackEvent('custom_event',
 );
 ```
 
+#### Purchase Tracking
+Track detailed purchase events:
+
+```typescript
+crm.logProductPurchase(
+  'order_123',        // orderId
+  'item_456',         // itemId
+  'Premium Widget',   // itemName
+  29.99,              // unitPrice
+  2,                  // quantity
+  'web',              // source
+  'direct',           // channel
+  'electronics'       // itemCategory (optional)
+);
+```
+
 ### Custom Attributes
 
-Track persistent user attributes:
+Track persistent user attributes that are sent with every batch:
 
 ```typescript
 crm.trackCustomAttribute('preference_theme', 'dark');
 crm.trackCustomAttribute('notification_enabled', true);
+crm.trackCustomAttribute('user_tier', 'premium');
+```
+
+### Push Notifications
+
+#### Token Management
+```typescript
+// Set push notification token
+crm.setToken('your-push-token');
+
+// Log push notification clicks
+crm.logClick('campaign_123');
+```
+
+### In-App Messaging
+
+Display rich in-app messages with customizable styling:
+
+```typescript
+const messageData = JSON.stringify({
+  header: "Welcome!",
+  message: "Check out our new features",
+  modal: {
+    button1: {
+      type: "Continue",
+      backgroundColor: "#007AFF",
+      textColor: "#FFFFFF",
+      borderColor: "#007AFF",
+      webOnClickValue: "redirect_to_web_url",
+      webOnClickAction: "https://example.com"
+    },
+    button2: {
+      type: "Skip",
+      backgroundColor: "#F2F2F2",
+      textColor: "#000000",
+      borderColor: "#CCCCCC"
+    },
+    dismissMessageAutomatically: true,
+    dismissMessageInSeconds: "10",
+    headerColor: "#000000",
+    messageColor: "#666666",
+    closeColor: "#999999"
+  },
+  mediaConfig: {
+    inAppImage: "https://example.com/image.png"
+  }
+});
+
+crm.displayInAppMessage(messageData, 'campaign_456');
+```
+
+### Batch Processing
+
+#### Manual Control
+```typescript
+// Force send all queued events immediately
+await crm.forceSend();
+
+// Clean up resources
+crm.dispose();
 ```
 
-## Types
+## Configuration Options
 
 ### SDKConfig
 
 ```typescript
 interface SDKConfig {
-  apiKey: string;      // Your API key
-  endpoint: string;    // API endpoint URL
-  debug?: boolean;     // Enable debug logging
+  apiKey: string;           // Your API key (required)
+  endpoint: string;         // API endpoint URL (required)
+  debug?: boolean;          // Enable debug logging
+  batchSize?: number;       // Events per batch (default: 10)
+  batchInterval?: number;   // Batch interval in ms (default: 10000)
 }
 ```
 
+## Data Types
+
 ### UserProfile
 
 ```typescript
 interface UserProfile {
-  id: string;                    // User identifier
-  user_type: string;             // 'registered' or 'guest'
-  traits: Record<string, any>;   // Custom user traits
+  id: string;              // User identifier
+  guestUserId?: string;    // Guest user identifier
 }
 ```
 
@@ -100,32 +182,68 @@ interface UserProfile {
 
 ```typescript
 interface EventOptions {
-  timestamp?: string;    // Custom event timestamp
-  requestId?: string;    // Custom request identifier
+  timestamp?: string;      // Custom event timestamp
+  requestId?: string;      // Custom request identifier
 }
 ```
 
-## Features
+### PurchasePayload
 
-- Automatic session tracking
-- Device and browser detection
-- Batch event processing
-- Offline event queuing
-- TypeScript support with full type definitions
-- Debug mode for development
+```typescript
+interface PurchasePayload {
+  externalId: string;      // Order ID
+  itemId: string;          // Product/item ID
+  itemName: string;        // Product name
+  unitPrice: number;       // Price per unit
+  quantity: number;        // Number of items
+  source: string;          // Purchase source
+  channel: string;         // Purchase channel
+  itemCategory?: string;   // Product category
+}
+```
+
+## Key Features
+
+### Automatic Functionality
+- **Session Management**: Automatic session tracking with device ID generation
+- **Guest User Handling**: Seamless guest-to-registered user transition
+- **Batch Processing**: Efficient event batching with configurable size and interval
+- **Offline Support**: Event queuing when offline with automatic retry
+- **Device Detection**: Automatic platform and device information collection
+- **Timezone Detection**: Automatic timezone detection and tracking
+
+### Performance Optimizations
+- **Event Queuing**: Intelligent batching to reduce network requests
+- **Session Storage**: Persistent storage for user data and custom attributes
+- **Error Handling**: Robust error handling with automatic retry mechanisms
+- **Memory Management**: Efficient cleanup and disposal methods
+
+### Developer Experience
+- **TypeScript Support**: Full type definitions included
+- **Debug Mode**: Comprehensive logging for development
+- **Flexible Configuration**: Customizable batch sizes and intervals
+- **Modern API**: Promise-based async operations
 
 ## Requirements
 
-- TypeScript 5.0+
-- Modern browser environment with localStorage support
-- Stable internet connection for event sending
+- **TypeScript**: 5.0+
+- **Browser**: Modern browsers with sessionStorage support
+- **Network**: Internet connection for event transmission
+- **Dependencies**: UUID library (automatically installed)
+
+## Browser Compatibility
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
 
 ## License
 
 MIT License
 
-For detailed API documentation and examples, visit our [documentation site](https://docs.ordersune.com/crm).
-
----
+## Support & Documentation
 
-Need help? [Contact Support](mailto:support@ordersune.com)
+- [API Documentation](https://docs.ordersune.com/crm)
+- [Support Portal](mailto:support@ordersune.com)
+- [GitHub Issues](https://github.com/ordersune/crm-web-sdk/issues)