Data Studio SDK

A TypeScript SDK for tracking user interactions, sessions, and events in your application. The SDK automatically handles client creation, session management, and event tracking with seamless backend synchronization via AWS SQS.

Table of Contents

• Installation
• Quick Start
• API Reference
  • Initialization
  • Client Management
  • Session Management
  • Event Tracking
• Event Types
• Type Definitions
• Examples
• Best Practices
• Error Handling

Installation

npm install data-studio-sdk
# or
yarn add data-studio-sdk

Quick Start

import { DataStudioSDK } from "data-studio-sdk";

// Initialize the SDK with your API key
// Format: "tenantId@apiKey"
const sdk = new DataStudioSDK({
  apiKey: "your-tenant-id@your-api-key",
});

// The SDK automatically creates a client on initialization
// Start a session
await sdk.startSession();

// Track events
await sdk.sendRatingEvent({
  rating: 1,
  max: 5,
  raterId: "user-123",
});

// End session when done
await sdk.endSession();

API Reference

Initialization

new DataStudioSDK(config: DataStudioSDKConfig)

Creates a new instance of the Data Studio SDK.

Parameters:

• config.apiKey (string, required): API key in the format "apiKey" (e.g., "123@1234-567-890")

Note: Your API key is available to copy from the Data Studio console.

Example:

const sdk = new DataStudioSDK({
  apiKey: "your-api-key",
});

Note: The SDK automatically:

• Fetches credentials from the API
• Initializes sync services (Client, Session, Event)
• Creates a client on initialization

Client Management

createClient(input?: ClientInput): Promise<Client>

Creates a new client. This is automatically called during SDK initialization, but you can call it manually if needed.

Parameters:

• input (ClientInput, optional): Manual client configuration. If not provided, the SDK auto-detects browser information in browser environments.

Returns: Promise<Client>

Example:

// Browser environment - auto-detects info
const client = await sdk.createClient();

// Node.js/server environment - manual input
const client = await sdk.createClient({
  clientType: "server",
  ip: "192.168.1.1",
  region: "us-east-1",
  city: "New York",
  timezone: "America/New_York",
});

getClient(): Client | null

Returns the current client instance.

Returns: Client | null

Example:

const client = sdk.getClient();
if (client) {
  console.log(`Client ID: ${client.id}`);
}

closeClient(): Promise<void>

Closes the current client. This automatically ends any active session and syncs the updated client to the backend.

Example:

await sdk.closeClient();

Session Management

startSession(input?: SessionInput): Promise<Session>

Starts a new session. A client must be created before starting a session.

Parameters:

• input (SessionInput, optional): Session configuration
  • userId?: string - Optional user identifier
  • country?: string - Country code
  • deviceType?: string - Device type
  • referrer?: string - Referrer URL

Returns: Promise<Session>

Example:

const session = await sdk.startSession({
  userId: "user-123",
  country: "US",
  deviceType: "desktop",
  referrer: "https://example.com",
});

endSession(): Promise<void>

Ends the current active session. Calculates session duration and syncs to backend.

Example:

await sdk.endSession();

getCurrentSession(): Session | null

Returns the current active session.

Returns: Session | null

Example:

const session = sdk.getCurrentSession();
if (session) {
  console.log(`Session ID: ${session.id}, Status: ${session.status}`);
}

Event Tracking

The SDK provides methods for tracking various types of events. All event methods require an active session.

Feedback & Quality Events

Helpful for experience analytics.

Rating Submitted

sendRatingEvent(event: RatingEvent): Promise<void>

Sends a rating submitted event.

Parameters:

• event.rating (number, required): rating value
• event.max (number, required): Maximum rating value
• event.source (string, optional): Source of the rating
• event.raterId (string, optional): ID of the user providing the rating

Example:

await sdk.sendRatingEvent({
  rating: 1,
  max: 5,
  source: "product-page",
  raterId: "user-123",
});

Feedback Submitted

sendFeedbackEvent(event: FeedbackEvent): Promise<void>

Sends a feedback submitted event.

Parameters:

• event.text (string, required): Feedback text
• event.category (string, optional): Feedback category
• event.rating (number, optional): Associated rating value
• event.source (string, optional): Source of the feedback

Example:

await sdk.sendFeedbackEvent({
  text: "Great product! Very satisfied with the quality.",
  category: "product-quality",
  rating: 5,
  source: "feedback-form",
});

Bug Reported

sendBugReportEvent(event: BugReportEvent): Promise<void>

Sends a bug reported event.

Parameters:

• event.description (string, required): Bug description
• event.severity (string, optional): Bug severity level (e.g., "low", "medium", "high", "critical")
• event.stepsToReproduce (string, optional): Steps to reproduce the bug
• event.component (string, optional): Affected component or area

Example:

await sdk.sendBugReportEvent({
  description: "Button not responding on mobile devices",
  severity: "high",
  stepsToReproduce:
    "1. Open app on mobile 2. Click submit button 3. Nothing happens",
  component: "checkout-form",
});

Survey Started / Completed

sendSurveyEvent(event: SurveyEvent): Promise<void>

Sends a survey started or completed event.

Parameters:

• event.surveyId (string, required): Unique survey identifier
• event.status ("started" | "completed", required): Survey status
• event.questionCount (number, optional): Number of questions in the survey
• event.duration (number, optional): Duration in milliseconds

Example:

// Survey started
await sdk.sendSurveyEvent({
  surveyId: "survey-123",
  status: "started",
  questionCount: 10,
});

// Survey completed
await sdk.sendSurveyEvent({
  surveyId: "survey-123",
  status: "completed",
  questionCount: 10,
  duration: 120000, // 2 minutes in milliseconds
});

User Complaint Received

sendComplaintEvent(event: ComplaintEvent): Promise<void>

Sends a user complaint received event.

Parameters:

• event.text (string, required): Complaint text
• event.category (string, optional): Complaint category
• event.priority (string, optional): Priority level (e.g., "low", "medium", "high", "urgent")
• event.status (string, optional): Complaint status (e.g., "new", "in-progress", "resolved")

Example:

await sdk.sendComplaintEvent({
  text: "Unable to access my account after password reset",
  category: "account-access",
  priority: "high",
  status: "new",
});

Workflow & Business Process Events

Perfect for automation and internal tools.

sendWorkflowStartedEvent(event: WorkflowStartedEvent): Promise<void>

Sends a workflow started event.

Parameters:

• event.workflowId (string, required): Unique workflow identifier
• event.workflowName (string, optional): Name of the workflow
• event.workflowType (string, optional): Type or category of the workflow
• event.initiatorId (string, optional): ID of the user or system that initiated the workflow

Example:

await sdk.sendWorkflowStartedEvent({
  workflowId: "workflow-123",
  workflowName: "Order Processing",
  workflowType: "e-commerce",
  initiatorId: "user-456",
});

sendWorkflowStepCompletedEvent(event: WorkflowStepCompletedEvent): Promise<void>

Sends a workflow step completed event.

Parameters:

• event.workflowId (string, required): Unique workflow identifier
• event.stepId (string, required): Unique step identifier
• event.stepName (string, optional): Name of the completed step
• event.duration (number, optional): Duration of the step in milliseconds
• event.status (string, optional): Status of the step completion

Example:

await sdk.sendWorkflowStepCompletedEvent({
  workflowId: "workflow-123",
  stepId: "step-456",
  stepName: "Payment Processing",
  duration: 2500,
  status: "success",
});

sendWorkflowErrorEvent(event: WorkflowErrorEvent): Promise<void>

Sends a workflow error event.

Parameters:

• event.workflowId (string, required): Unique workflow identifier
• event.stepId (string, optional): Step identifier where the error occurred
• event.errorType (string, optional): Type or category of the error
• event.errorMessage (string, optional): Detailed error message
• event.errorCode (string, optional): Error code or identifier
• event.severity (string, optional): Error severity level (e.g., "low", "medium", "high", "critical")

Example:

await sdk.sendWorkflowErrorEvent({
  workflowId: "workflow-123",
  stepId: "step-456",
  errorType: "validation_error",
  errorMessage: "Invalid payment method",
  errorCode: "PAYMENT_001",
  severity: "high",
});

sendWorkflowAbortedEvent(event: WorkflowAbortedEvent): Promise<void>

Sends a workflow aborted event.

Parameters:

• event.workflowId (string, required): Unique workflow identifier
• event.reason (string, optional): Reason for aborting the workflow
• event.abortedBy (string, optional): ID of the user or system that aborted the workflow

Example:

await sdk.sendWorkflowAbortedEvent({
  workflowId: "workflow-123",
  reason: "User cancelled operation",
  abortedBy: "user-456",
});

sendDocumentCreatedEvent(event: DocumentCreatedEvent): Promise<void>

Sends a document created event.

Parameters:

• event.documentId (string, required): Unique document identifier
• event.documentType (string, optional): Type of document (e.g., "invoice", "contract", "report")
• event.documentName (string, optional): Name of the document
• event.creatorId (string, optional): ID of the user who created the document
• event.templateId (string, optional): Template identifier if document was created from a template

Example:

await sdk.sendDocumentCreatedEvent({
  documentId: "doc-123",
  documentType: "invoice",
  documentName: "Invoice #2024-001",
  creatorId: "user-456",
  templateId: "template-invoice-v2",
});

sendDocumentApprovedEvent(event: DocumentApprovedEvent): Promise<void>

Sends a document approved event.

Parameters:

• event.documentId (string, required): Unique document identifier
• event.approverId (string, optional): ID of the user who approved the document
• event.reason (string, optional): Reason for approval
• event.comment (string, optional): Additional comments

Example:

await sdk.sendDocumentApprovedEvent({
  documentId: "doc-123",
  approverId: "user-789",
  reason: "All requirements met",
  comment: "Approved for production",
});

sendDocumentRejectedEvent(event: DocumentRejectedEvent): Promise<void>

Sends a document rejected event.

Parameters:

• event.documentId (string, required): Unique document identifier
• event.approverId (string, optional): ID of the user who rejected the document
• event.reason (string, optional): Reason for rejection
• event.comment (string, optional): Additional comments or feedback

Example:

await sdk.sendDocumentRejectedEvent({
  documentId: "doc-123",
  approverId: "user-789",
  reason: "Missing required information",
  comment: "Please add customer signature before resubmission",
});

sendTaskAssignedEvent(event: TaskAssignedEvent): Promise<void>

Sends a task assigned event.

Parameters:

• event.taskId (string, required): Unique task identifier
• event.taskName (string, optional): Name of the task
• event.assigneeId (string, optional): ID of the user assigned to the task
• event.assignerId (string, optional): ID of the user who assigned the task
• event.priority (number, optional): Task priority level (higher numbers indicate higher priority)
• event.dueDate (number, optional): Due date timestamp in milliseconds

Example:

await sdk.sendTaskAssignedEvent({
  taskId: "task-123",
  taskName: "Review quarterly report",
  assigneeId: "user-456",
  assignerId: "user-789",
  priority: 5,
  dueDate: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days from now
});

sendTaskCompletedEvent(event: TaskCompletedEvent): Promise<void>

Sends a task completed event.

Parameters:

• event.taskId (string, required): Unique task identifier
• event.completedBy (string, optional): ID of the user who completed the task
• event.duration (number, optional): Duration to complete the task in milliseconds
• event.status (string, optional): Completion status (e.g., "completed", "cancelled", "failed")
• event.outcome (string, optional): Outcome or result of the task

Example:

await sdk.sendTaskCompletedEvent({
  taskId: "task-123",
  completedBy: "user-456",
  duration: 3600000, // 1 hour in milliseconds
  status: "completed",
  outcome: "All items reviewed and approved",
});

E-Commerce Events

Track shopping behavior and order lifecycles.

Product Viewed

sendProductViewedEvent(event: ProductViewedEvent): Promise<void>

Sends a product viewed event.

Parameters:

• event.productId (string, required): Unique product identifier
• event.name (string, required): Product name
• event.category (string, optional): Product category
• event.currency (string, optional): Currency code (e.g., "USD")
• event.variant (string, optional): Product variant
• event.price (number, optional): Product price

Example:

await sdk.sendProductViewedEvent({
  productId: "prod-123",
  name: "Red T-Shirt",
  category: "Apparel",
  currency: "USD",
  price: 29.99,
});

Order Created

sendOrderCreatedEvent(event: OrderCreatedEvent): Promise<void>

Sends an order created event.

Parameters:

• event.orderId (string, required): Unique order identifier
• event.currency (string, optional): Currency code
• event.couponCode (string, optional): Applied coupon code
• event.totalValue (number, optional): Total order value
• event.itemCount (number, optional): Total number of items

Example:

await sdk.sendOrderCreatedEvent({
  orderId: "order-123",
  currency: "USD",
  totalValue: 150.00,
  itemCount: 3,
});

Checkout Started

sendCheckoutStartedEvent(event: CheckoutStartedEvent): Promise<void>

Sends a checkout started event.

Parameters:

• event.orderId (string, required): Unique order identifier
• event.currency (string, optional): Currency code
• event.totalValue (number, optional): Total value at start of checkout
• event.itemCount (number, optional): Number of items in cart

Example:

await sdk.sendCheckoutStartedEvent({
  orderId: "order-123",
  currency: "USD",
  totalValue: 99.99,
  itemCount: 2,
});

Custom Events

sendCustomEvent(event: Event): Promise<void>

Sends a custom event with full control over the event structure.

Parameters:

• event (Event, required): Custom event object conforming to the Event interface

Example:

await sdk.sendCustomEvent({
  id: "custom-event-123",
  tenantId: "tenant-123",
  sessionId: "session-123",
  timestamp: Date.now(),
  eventType: "custom",
  properties: {
    string1: "custom-value",
    num1: 42,
    bool1: true,
  },
});

Event Types

The SDK supports the following event types:

| Event Type | Constant | Description | | ----------------------- | ------------------------- | -------------------------------------- | | Rating | RATING | User rating events | | Custom | CUSTOM | Custom events with flexible properties | | Feedback Submitted | FEEDBACK_SUBMITTED | User feedback submission | | Bug Reported | BUG_REPORTED | Bug report events | | Survey | SURVEY | Survey started/completed events | | Complaint Received | COMPLAINT_RECEIVED | User complaint events | | Workflow Started | WORKFLOW_STARTED | Workflow initiation events | | Workflow Step Completed | WORKFLOW_STEP_COMPLETED | Workflow step completion events | | Workflow Error | WORKFLOW_ERROR | Workflow error events | | Workflow Aborted | WORKFLOW_ABORTED | Workflow abortion events | | Document Created | DOCUMENT_CREATED | Document creation events | | Document Approved | DOCUMENT_APPROVED | Document approval events | | Document Rejected | DOCUMENT_REJECTED | Document rejection events | | Task Assigned | TASK_ASSIGNED | Task assignment events | | Task Completed | TASK_COMPLETED | Task completion events | | Product Viewed | PRODUCT_VIEWED | Product view events | | Category Viewed | CATEGORY_VIEWED | Category view events | | Product Added to Cart | PRODUCT_ADDED_TO_CART | Add to cart events | | Product Removed | PRODUCT_REMOVED_FROM_CART| Remove from cart events | | Cart Cleared | CART_CLEARED | Cart cleared events | | Cart Viewed | CART_VIEWED | Cart view events | | Search Performed | SEARCH_PERFORMED | Search events | | Search Cleared | SEARCH_CLEARED | Search cleared events | | Filter Applied/Removed | FILTER_APPLIED_REMOVED | Filter interaction events | | Checkout Started | CHECKOUT_STARTED | Checkout initiation events | | Checkout Abandoned | CHECKOUT_ABANDONED | Checkout abandonment events | | Payment Attempted | PAYMENT_ATTEMPTED | Payment attempt events | | Payment Failed | PAYMENT_FAILED | Payment failure events | | Payment Success | PAYMENT_SUCCESS | Payment success events | | Order Created | ORDER_CREATED | Order creation events | | Order Confirmed | ORDER_CONFIRMED | Order confirmation events | | Order Packed | ORDER_PACKED | Order packed events | | Order Shipped | ORDER_SHIPPED | Order shipment events | | Order Delivered | ORDER_DELIVERED | Order delivery events | | Order Cancelled | ORDER_CANCELLED | Order cancellation events | | Order Refunded | ORDER_REFUNDED | Order refund events | | Order Item Added | ORDER_ITEM_ADDED | Order item addition events | | Order Item Updated | ORDER_ITEM_UPDATED | Order item update events | | Order Item Removed | ORDER_ITEM_REMOVED | Order item removal events | | Item Delivered | ITEM_DELIVERED | Item delivery events | | Item Delivery Failed | ITEM_DELIVERY_FAILED | Item delivery failure events | | Device Online | DEVICE_ONLINE | Device online events | | Device Offline | DEVICE_OFFLINE | Device offline events | | Device Rebooted | DEVICE_REBOOTED | Device reboot events | | Firmware Updated | FIRMWARE_UPDATED | Firmware update events | | Temperature Reading | TEMPERATURE_READING | Temperature sensor reading events | | Humidity Reading | HUMIDITY_READING | Humidity sensor reading events | | Voltage / Power Level | VOLTAGE_POWER_LEVEL | Voltage/power level events | | Motion Detected | MOTION_DETECTED | Motion detection events | | GPS Update | GPS_UPDATE | GPS location update events | | Screen Media Update | SCREEN_MEDIA_UPDATE | Screen media update events | | Queue Updated | QUEUE_UPDATED | Queue update events | | Fault Detected | FAULT_DETECTED | Device fault detection events | | Battery Low | BATTERY_LOW | Low battery warning events | | Overheating | OVERHEATING | Overheating warning events | | Unauthorized Access | UNAUTHORIZED_ACCESS | Unauthorized access attempt events | | Command Sent | COMMAND_SENT | Device command sent events | | Command Acknowledged | COMMAND_ACKNOWLEDGED | Device command acknowledgment events | | Command Failed | COMMAND_FAILED | Device command failure events |

Type Definitions

ClientInput

interface ClientInput {
  clientType: "browser" | "server";
  ip?: string;
  region?: string;
  city?: string;
  timezone?: string;
  os?: string;
  osVersion?: string;
  browser?: string;
  browserVersion?: string;
  screenResolution?: string;
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
}

SessionInput

interface SessionInput {
  userId?: string;
  country?: string;
  deviceType?: string;
  referrer?: string;
}

RatingEvent

interface RatingEvent {
  min: number;
  max: number;
  source?: string;
  raterId?: string;
}

FeedbackEvent

interface FeedbackEvent {
  text: string;
  category?: string;
  rating?: number;
  source?: string;
}

BugReportEvent

interface BugReportEvent {
  description: string;
  severity?: string;
  stepsToReproduce?: string;
  component?: string;
}

SurveyEvent

interface SurveyEvent {
  surveyId: string;
  status: "started" | "completed";
  questionCount?: number;
  duration?: number;
}

ComplaintEvent

interface ComplaintEvent {
  text: string;
  category?: string;
  priority?: string;
  status?: string;
}

WorkflowStartedEvent

interface WorkflowStartedEvent {
  workflowId: string;
  workflowName?: string;
  workflowType?: string;
  initiatorId?: string;
}

WorkflowStepCompletedEvent

interface WorkflowStepCompletedEvent {
  workflowId: string;
  stepId: string;
  stepName?: string;
  duration?: number;
  status?: string;
}

WorkflowErrorEvent

interface WorkflowErrorEvent {
  workflowId: string;
  stepId?: string;
  errorType?: string;
  errorMessage?: string;
  errorCode?: string;
  severity?: string;
}

WorkflowAbortedEvent

interface WorkflowAbortedEvent {
  workflowId: string;
  reason?: string;
  abortedBy?: string;
}

DocumentCreatedEvent

interface DocumentCreatedEvent {
  documentId: string;
  documentType?: string;
  documentName?: string;
  creatorId?: string;
  templateId?: string;
}

DocumentApprovedEvent

interface DocumentApprovedEvent {
  documentId: string;
  approverId?: string;
  reason?: string;
  comment?: string;
}

DocumentRejectedEvent

interface DocumentRejectedEvent {
  documentId: string;
  approverId?: string;
  reason?: string;
  comment?: string;
}

TaskAssignedEvent

interface TaskAssignedEvent {
  taskId: string;
  taskName?: string;
  assigneeId?: string;
  assignerId?: string;
  priority?: number;
  dueDate?: number;
}

TaskCompletedEvent

interface TaskCompletedEvent {
  taskId: string;
  completedBy?: string;
  duration?: number;
  status?: string;
  outcome?: string;
}

ProductViewedEvent

interface ProductViewedEvent {
  productId: string;
  name: string;
  category?: string;
  currency?: string;
  variant?: string;
  price?: number;
}

OrderCreatedEvent

interface OrderCreatedEvent {
  orderId: string;
  currency?: string;
  couponCode?: string;
  totalValue?: number;
  itemCount?: number;
}

CheckoutStartedEvent

interface CheckoutStartedEvent {
  orderId: string;
  currency?: string;
  totalValue?: number;
  itemCount?: number;
}

DeviceOnlineEvent

interface DeviceOnlineEvent {
  deviceId: string;
  deviceType?: string;
  location?: string;
  firmwareVersion?: string;
}

DeviceOfflineEvent

interface DeviceOfflineEvent {
  deviceId: string;
  reason?: string;
  lastSeen?: number;
}

DeviceRebootedEvent

interface DeviceRebootedEvent {
  deviceId: string;
  reason?: string;
  uptimeBeforeReboot?: number;
}

FirmwareUpdatedEvent

interface FirmwareUpdatedEvent {
  deviceId: string;
  oldVersion?: string;
  newVersion: string;
}

TemperatureReadingEvent

interface TemperatureReadingEvent {
  deviceId: string;
  sensorId?: string;
  temperature: number;
  unit?: string;
  location?: string;
}

HumidityReadingEvent

interface HumidityReadingEvent {
  deviceId: string;
  sensorId?: string;
  humidity: number;
  unit?: string;
  location?: string;
}

VoltagePowerLevelEvent

interface VoltagePowerLevelEvent {
  deviceId: string;
  voltage?: number;
  powerLevel?: number;
  batteryLevel?: number;
}

MotionDetectedEvent

interface MotionDetectedEvent {
  deviceId: string;
  sensorId?: string;
  location?: string;
  motionType?: string;
}

GpsUpdateEvent

interface GpsUpdateEvent {
  deviceId: string;
  latitude: number;
  longitude: number;
  altitude?: number;
  accuracy?: number;
}

ScreenMediaUpdateEvent

interface ScreenMediaUpdateEvent {
  deviceId: string;
  mediaType?: string;
  mediaId?: string;
  duration?: number;
}

QueueUpdatedEvent

interface QueueUpdatedEvent {
  deviceId: string;
  queueId?: string;
  queueLength: number;
  action?: string;
}

FaultDetectedEvent

interface FaultDetectedEvent {
  deviceId: string;
  faultType?: string;
  faultCode?: string;
  severity?: string;
  description?: string;
}

BatteryLowEvent

interface BatteryLowEvent {
  deviceId: string;
  batteryLevel: number;
  threshold?: number;
}

OverheatingEvent

interface OverheatingEvent {
  deviceId: string;
  temperature: number;
  threshold?: number;
}

UnauthorizedAccessEvent

interface UnauthorizedAccessEvent {
  deviceId: string;
  accessType?: string;
  source?: string;
  attemptCount?: number;
}

CommandSentEvent

interface CommandSentEvent {
  deviceId: string;
  commandType: string;
  commandId?: string;
  parameters?: string;
}

CommandAcknowledgedEvent

interface CommandAcknowledgedEvent {
  deviceId: string;
  commandId: string;
  timestamp?: number;
}

CommandFailedEvent

interface CommandFailedEvent {
  deviceId: string;
  commandId: string;
  errorCode?: string;
  errorMessage?: string;
}

Examples

Complete Workflow Example

import { DataStudioSDK } from "data-studio-sdk";

async function trackUserJourney() {
  // Initialize SDK
  const sdk = new DataStudioSDK({
    apiKey: "your-tenant-id@your-api-key",
  });

  try {
    // Client is automatically created on initialization
    // Start a session
    await sdk.startSession({
      userId: "user-123",
      country: "US",
    });

    // Track various events
    await sdk.sendRatingEvent({
      rating: 1,
      max: 5,
      raterId: "user-123",
    });

    await sdk.sendFeedbackEvent({
      text: "Love the new design!",
      category: "ui-feedback",
      rating: 5,
    });

    await sdk.sendSurveyEvent({
      surveyId: "satisfaction-survey-2024",
      status: "started",
      questionCount: 5,
    });

    // ... user completes survey ...

    await sdk.sendSurveyEvent({
      surveyId: "satisfaction-survey-2024",
      status: "completed",
      questionCount: 5,
      duration: 45000, // 45 seconds
    });

    // End session
    await sdk.endSession();

    // Close client
    await sdk.closeClient();
  } catch (error) {
    console.error("Error tracking events:", error);
  }
}

Browser Integration Example

// In your React/Vue/Angular component
import { DataStudioSDK } from "data-studio-sdk";

// Initialize once (e.g., in app initialization)
const sdk = new DataStudioSDK({
  apiKey: process.env.REACT_APP_DATA_STUDIO_API_KEY!,
});

// Start session when user lands on page
useEffect(() => {
  sdk.startSession({
    userId: currentUser?.id,
    referrer: document.referrer,
  });

  return () => {
    // End session on component unmount
    sdk.endSession();
  };
}, []);

// Track events on user interactions
const handleRatingSubmit = async (rating: number) => {
  await sdk.sendRatingEvent({
    rating: 1,
    max: 5,
    raterId: currentUser?.id,
  });
};

const handleFeedbackSubmit = async (feedback: string) => {
  await sdk.sendFeedbackEvent({
    text: feedback,
    category: "general",
    source: "contact-form",
  });
};

Node.js/Server Example

import { DataStudioSDK } from "data-studio-sdk";

// Initialize with server-specific configuration
const sdk = new DataStudioSDK({
  apiKey: process.env.DATA_STUDIO_API_KEY!,
});

// Create client with server info
await sdk.createClient({
  clientType: "server",
  ip: req.ip,
  region: "us-east-1",
  city: "New York",
  timezone: "America/New_York",
});

// Start session
await sdk.startSession({
  userId: req.user.id,
  country: req.headers["cf-ipcountry"] as string,
});

// Track server-side events
await sdk.sendBugReportEvent({
  description: "API endpoint returning 500 error",
  severity: "critical",
  component: "payment-api",
});

Best Practices

1. Initialize Once: Create a single SDK instance and reuse it throughout your application lifecycle.

2. Session Management:

   • Start a session when a user begins their journey
   • End the session when they leave or after a period of inactivity
   • Don't create multiple concurrent sessions

3. Error Handling: Always wrap SDK calls in try-catch blocks to handle potential errors gracefully.

4. Async/Await: All SDK methods are asynchronous. Always use await or handle promises appropriately.

5. Event Context: The SDK automatically adds context (sessionId, clientId, tenantId, timestamp) to all events. You don't need to provide this manually.

6. Browser vs Server:

   • In browser environments, the SDK auto-detects device and browser information
   • In server environments, provide client information manually via createClient()

7. Cleanup: Always call endSession() and closeClient() when appropriate to ensure data is properly synced.