@achado/feature-tracking

Feature usage tracking via data attributes for the Achado platform. Automatically track feature views, interactions, exposures, and conversions using simple HTML attributes.

Installation

npm install @achado/core @achado/feature-tracking

Quick Start

import { AchadoClient } from '@achado/core';
import { FeatureTracking } from '@achado/feature-tracking';

const client = new AchadoClient({ apiKey: 'your-api-key' });
const featureTracking = new FeatureTracking(client);

await client.initialize();
await featureTracking.initialize();

// Features are now tracked automatically via data attributes!

<!-- Automatically tracked features -->
<button data-feature="signup-button">Sign Up</button>
<div data-feature="pricing-table">Pricing content...</div>
<form data-feature="contact-form">Contact form...</form>

Features

🏷️ Attribute-Based Tracking

• Simple data-feature attributes
• Automatic detection and tracking
• No code changes required for tracking

👁️ View Tracking

• Automatic visibility detection
• Intersection Observer-based
• Viewport-aware measurement

🖱️ Interaction Tracking

• Click, focus, and submission events
• Element context capture
• Interaction type classification

⏱️ Exposure Tracking

• Time-based visibility measurement
• Configurable exposure thresholds
• Scroll-based exposure detection

📈 Conversion Tracking

• Goal completion measurement
• Funnel analysis support
• Custom conversion events

🧪 A/B Testing

• Built-in experiment management
• Variant assignment and tracking
• Feature flag integration

📊 Analytics Dashboard

• Real-time usage statistics
• Conversion rate analysis
• Feature performance metrics

Configuration

interface FeatureTrackingConfig {
  enabled?: boolean; // Default: true
  autoTrack?: boolean; // Default: true
  trackViews?: boolean; // Default: true
  trackInteractions?: boolean; // Default: true
  trackExposure?: boolean; // Default: true
  exposureThreshold?: number; // Default: 0.5 (50% visible)
  debounceMs?: number; // Default: 250
  attributeName?: string; // Default: 'data-feature'
  excludeFeatures?: string[]; // Features to exclude
  includeFeatures?: string[]; // Only track these features
}

Example Configuration

const featureTracking = new FeatureTracking(client, {
  enabled: true,
  autoTrack: true,
  exposureThreshold: 0.75, // 75% visible for exposure
  debounceMs: 500,
  attributeName: 'data-track-feature',
  excludeFeatures: ['debug-panel', 'admin-tools'],
  includeFeatures: [], // Empty = track all (except excluded)
});

API Reference

FeatureTracking Class

Constructor

new FeatureTracking(client: AchadoClient, config?: FeatureTrackingConfig)

Methods

initialize(): Promise<void>

Start automatic feature tracking.

trackFeature(featureName: string, eventType: 'view' | 'interaction' | 'exposure' | 'conversion', properties?: Record<string, any>): void

Manually track a feature event.

featureTracking.trackFeature('signup-button', 'view', {
  location: 'header',
  variant: 'blue',
});

trackConversion(featureName: string, properties?: Record<string, any>): void

Track a conversion event.

featureTracking.trackConversion('signup-button', {
  userId: 'user-123',
  revenue: 29.99,
  plan: 'premium',
});

trackInteraction(featureName: string, interactionType: string, properties?: Record<string, any>): void

Track a specific interaction.

featureTracking.trackInteraction('video-player', 'play', {
  duration: 120,
  quality: '1080p',
});

Experiment Management

// Set up an experiment
featureTracking.setExperiment('button-color', 'red', true, {
  variant: 'A',
  startDate: '2024-01-01',
});

// Get experiment info
const experiment = featureTracking.getExperiment('button-color');
const variant = featureTracking.getExperimentVariant('button-color');
const isEnabled = featureTracking.isExperimentEnabled('button-color');

Analytics Methods

// Get feature statistics
const stats = featureTracking.getFeatureStats('signup-button');

// Get all feature stats
const allStats = featureTracking.getAllFeatureStats();

// Get top performing features
const topFeatures = featureTracking.getTopFeatures(10);

// Get features by conversion rate
const bestConverting = featureTracking.getFeaturesByConversionRate(5);

// Export all analytics data
const analyticsData = featureTracking.exportAnalytics();

Configuration Management

// Update config at runtime
featureTracking.updateConfig({
  exposureThreshold: 0.8,
  debounceMs: 300,
});

// Manage feature lists
featureTracking.addFeatureToExclude('beta-feature');
featureTracking.removeFeatureFromExclude('beta-feature');
featureTracking.addFeatureToInclude('important-feature');

HTML Usage

Basic Feature Tracking

<!-- Button tracking -->
<button data-feature="signup-cta">Sign Up Now</button>

<!-- Section tracking -->
<section data-feature="pricing-section">
  <h2>Pricing Plans</h2>
  <!-- Pricing content -->
</section>

<!-- Form tracking -->
<form data-feature="newsletter-signup">
  <input type="email" placeholder="Your email" />
  <button type="submit">Subscribe</button>
</form>

Advanced Feature Tracking

<!-- Custom attribute name -->
<div data-track-feature="hero-banner">Hero content</div>

<!-- Multiple features on one element -->
<button
  data-feature="primary-cta"
  data-experiment="button-color"
  data-variant="blue"
>
  Get Started
</button>

<!-- Excluded from tracking -->
<div data-feature="admin-panel" data-no-track>Admin only content</div>

E-commerce Examples

<!-- Product tracking -->
<div data-feature="product-card" data-product-id="prod-123">
  <img src="product.jpg" alt="Product" />
  <h3>Product Name</h3>
  <button data-feature="add-to-cart">Add to Cart</button>
</div>

<!-- Checkout flow -->
<form data-feature="checkout-form">
  <div data-feature="payment-methods">
    <input type="radio" data-feature="credit-card" /> Credit Card
    <input type="radio" data-feature="paypal" /> PayPal
  </div>
  <button data-feature="complete-purchase">Complete Purchase</button>
</form>

SaaS Application Examples

<!-- Feature adoption tracking -->
<div data-feature="dashboard-widget" data-widget-type="analytics">
  <h3>Analytics Widget</h3>
  <button data-feature="widget-configure">Configure</button>
</div>

<!-- Onboarding flow -->
<div data-feature="onboarding-step" data-step="3">
  <h2>Step 3: Connect Your Data</h2>
  <button data-feature="connect-integration">Connect</button>
  <button data-feature="skip-step">Skip for Now</button>
</div>

Tracked Events

Feature View

{
  eventName: 'feature_usage',
  properties: {
    featureName: 'signup-button',
    eventType: 'view',
    timestamp: 1640995200000,
    element: {
      tagName: 'button',
      id: 'signup-btn',
      className: 'btn btn-primary',
      textContent: 'Sign Up Now'
    },
    context: {
      url: 'https://example.com',
      viewport: { width: 1920, height: 1080 },
      elementPosition: { x: 100, y: 200, width: 120, height: 40 }
    }
  }
}

Feature Interaction

{
  eventName: 'feature_usage',
  properties: {
    featureName: 'signup-button',
    eventType: 'interaction',
    properties: {
      interactionType: 'click'
    },
    timestamp: 1640995250000,
    // ... element and context data
  }
}

Feature Conversion

{
  eventName: 'feature_usage',
  properties: {
    featureName: 'signup-button',
    eventType: 'conversion',
    properties: {
      userId: 'user-123',
      revenue: 29.99,
      plan: 'premium'
    },
    timestamp: 1640995300000
  }
}

Analytics Data

Feature Usage Statistics

interface FeatureUsage {
  featureName: string;
  totalViews: number;
  totalInteractions: number;
  totalExposures: number;
  totalConversions: number;
  firstSeen: number;
  lastSeen: number;
  uniqueSessions: number;
  averageTimeToInteraction: number;
  conversionRate: number;
}

Usage Example

const stats = featureTracking.getFeatureStats('signup-button');
console.log(`Conversion rate: ${stats.conversionRate * 100}%`);
console.log(`Total interactions: ${stats.totalInteractions}`);
console.log(`Unique sessions: ${stats.uniqueSessions.size}`);

A/B Testing Integration

Setting Up Experiments

// Create experiment variants
featureTracking.setExperiment('pricing-display', 'monthly-first', true, {
  testGroup: 'A',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});

featureTracking.setExperiment('pricing-display', 'annual-first', true, {
  testGroup: 'B',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
});

Using Experiments in HTML

<!-- Variant A -->
<div
  data-feature="pricing-table"
  data-experiment="pricing-display"
  data-variant="monthly-first"
>
  <div>Monthly: $29/month</div>
  <div>Annual: $290/year</div>
</div>

<!-- Variant B -->
<div
  data-feature="pricing-table"
  data-experiment="pricing-display"
  data-variant="annual-first"
>
  <div>Annual: $290/year (Save 20%!)</div>
  <div>Monthly: $29/month</div>
</div>

Experiment Analysis

// Get conversion rates by variant
const experiments = featureTracking.getAllExperiments();
experiments.forEach((exp) => {
  const stats = featureTracking.getFeatureStats(exp.name);
  console.log(`${exp.variant}: ${stats.conversionRate * 100}% conversion`);
});

Performance

Optimization Features

• Intersection Observer: Efficient visibility detection
• Debounced Events: Prevents event spam
• Smart Querying: Optimized DOM queries
• Memory Management: Automatic cleanup

Performance Impact

• DOM Queries: < 5ms per page scan
• Event Processing: < 1ms per interaction
• Memory Usage: < 1MB for typical usage
• Network: Minimal additional payload

Browser Support

• Chrome 70+
• Firefox 65+
• Safari 12+
• Edge 79+

Examples

E-commerce Setup

const featureTracking = new FeatureTracking(client, {
  enabled: true,
  trackViews: true,
  trackInteractions: true,
  trackExposure: true,
  exposureThreshold: 0.6,
  includeFeatures: [
    'product-card',
    'add-to-cart',
    'checkout-form',
    'payment-method',
    'complete-purchase',
  ],
});

SaaS Dashboard Setup

const featureTracking = new FeatureTracking(client, {
  enabled: true,
  autoTrack: true,
  exposureThreshold: 0.8,
  excludeFeatures: ['admin-panel', 'debug-info', 'internal-tools'],
  debounceMs: 500,
});

Content Site Setup

const featureTracking = new FeatureTracking(client, {
  enabled: true,
  trackExposure: true,
  exposureThreshold: 0.5,
  includeFeatures: [
    'article-content',
    'social-share',
    'newsletter-signup',
    'related-articles',
    'comment-section',
  ],
});