@tinytapanalytics/sdk

TinyTap Analytics JavaScript SDK

Behavioral psychology platform that detects visitor frustration, predicts abandonment, and helps you save at-risk conversions in real-time.

Stop guessing why visitors leave. Know in real-time.

🎯 What Makes TinyTap Analytics Different

Unlike traditional analytics that tell you what happened after visitors leave, TinyTap Analytics detects how users are feeling while they're still on your site - giving you the chance to intervene before they abandon.

Real-Time Behavioral Intelligence

• Detect frustrated visitors - Rage clicks, hesitation patterns, form anxiety
• Calculate abandonment risk - Real-time psychology scoring (0-100)
• Get actionable alerts - Know when high-value sessions are at risk

Explainable Psychology Metrics

• "4 rage clicks detected" not "78.4% ML prediction"
• Understand why scores change with transparent metrics
• Trust insights you can explain to your team

Privacy-First by Design

• No session recording or screen capture
• Client-side analysis - behavioral signals, not sensitive data
• GDPR/CCPA compliant - collect patterns, not PII

🧠 Core Capabilities

1. Micro-Interaction Detection

Track HOW users interact with your site, not just what they click:

// Automatically detects:
// - Rage clicks (frustrated rapid clicking on non-responsive elements)
// - Hesitation duration (hovering 3+ seconds before acting)
// - Form anxiety (excessive backspaces, slow fill speed)
// - Error encounters (form validation failures, broken elements)
// - Cursor distance (erratic movements indicating confusion)

2. Session Psychology Profiling

Real-time behavioral analysis generates actionable scores:

{
  frustrationScore: 0.85,      // High frustration (rage clicks, errors)
  confidenceScore: 0.32,       // Low confidence (hesitation, backspaces)
  engagementScore: 0.61,       // Moderate engagement (scroll patterns)
  abandonmentRisk: 0.78,       // 78% likely to abandon
  conversionProbability: 0.15  // 15% likely to convert
}

3. Real-Time Abandonment Alerts

Get notified when sessions need intervention:

{
  alertType: 'frustration',
  riskScore: 0.85,
  triggerReason: '4 rage clicks, 3 errors encountered, high hesitation',
  suggestedIntervention: 'Show live chat offer',
  pageUrl: '/checkout',
  sessionId: 'session-123'
}

🚀 Quick Start (5 minutes)

Installation

npm install @tinytapanalytics/sdk

Basic Setup

<!-- Option 1: Direct script tag (minimal version - 1.0 KB gzipped) -->
<script src="https://cdn.tinytapanalytics.com/sdk/tinytapanalytics-minimal.min.js"
        data-api-key="your-api-key"
        data-website-id="your-website-id"></script>

<!-- Option 2: NPM/ES modules -->
<script type="module">
  import TinyTap Analytics from '@tinytapanalytics/sdk/minimal';

  const ciq = new TinyTap Analytics({
    apiKey: 'your-api-key',
    websiteId: 'your-website-id'
  });

  // Page views and conversions tracked automatically
  // Micro-interactions detected automatically

  // Optional: Track custom events
  ciq.track('custom_event', { key: 'value' });
</script>

Advanced Setup with Psychology Features

import TinyTap Analytics from '@tinytapanalytics/sdk';
import { MicroInteractionTracking } from '@tinytapanalytics/sdk/features/MicroInteractionTracking';

const ciq = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',

  // Enable behavioral psychology features
  enableMicroInteractions: true,
  batchInterval: 5000, // Send behavioral data every 5 seconds

  // Privacy settings
  enablePrivacyMode: true
});

// Initialize micro-interaction tracking
const microTracking = new MicroInteractionTracking(ciq);
microTracking.start({
  trackRageClicks: true,
  trackHesitation: true,
  trackFormAnxiety: true,
  trackScrollPatterns: true
});

📦 Bundle Options & Tree-Shaking

TinyTap Analytics offers multiple bundle options optimized for different use cases:

Bundle	Size (Gzipped)	Features	Best For
Minimal	1.0 KB	Core tracking only	Basic event tracking
Core	14.2 KB	Full SDK with behavioral features	Most applications
Full	14.2 KB	All features pre-loaded	Feature-rich apps
Micro-Interactions	10.8 KB	Psychology tracking module	E-commerce, SaaS

Tree-Shaking Examples

// Import only what you need
import { MinimalTinyTap Analytics } from '@tinytapanalytics/sdk/minimal';
import { MicroInteractionTracking } from '@tinytapanalytics/sdk/features/MicroInteractionTracking';

// Or use dynamic imports for code splitting
const loadPsychologyFeatures = async () => {
  const { MicroInteractionTracking } = await import('@tinytapanalytics/sdk/features/MicroInteractionTracking');
  return new MicroInteractionTracking(config);
};

🎯 Framework Integration

React

// hooks/useTinyTap Analytics.js
import { useEffect, useRef } from 'react';
import TinyTap Analytics from '@tinytapanalytics/sdk';

export function useTinyTap Analytics(config) {
  const sdk = useRef(null);

  useEffect(() => {
    sdk.current = new TinyTap Analytics({
      ...config,
      enableMicroInteractions: true // Enable behavioral psychology
    });

    return () => {
      // Cleanup if needed
    };
  }, [config]);

  return {
    track: (event, data) => sdk.current?.track(event, data),
    trackConversion: (value, currency, metadata) =>
      sdk.current?.trackConversion(value, currency, metadata)
  };
}

// Component usage
function CheckoutPage() {
  const { trackConversion } = useTinyTap Analytics({
    apiKey: process.env.REACT_APP_CONVERSION_IQ_API_KEY,
    websiteId: process.env.REACT_APP_CONVERSION_IQ_WEBSITE_ID
  });

  const handlePurchase = async (orderData) => {
    // Process payment...

    // Track conversion
    await trackConversion(orderData.total, 'USD', {
      orderId: orderData.id,
      items: orderData.items
    });
  };

  return (
    <button onClick={() => handlePurchase(order)}>
      Complete Purchase
    </button>
  );
}

Vue 3 (Composition API)

// composables/useTinyTap Analytics.js
import { ref, onMounted } from 'vue';
import TinyTap Analytics from '@tinytapanalytics/sdk';

export function useTinyTap Analytics(config) {
  const sdk = ref(null);

  onMounted(() => {
    sdk.value = new TinyTap Analytics({
      ...config,
      enableMicroInteractions: true
    });
  });

  const track = (event, data) => sdk.value?.track(event, data);
  const trackConversion = (value, currency = 'USD', metadata = {}) => {
    sdk.value?.trackConversion(value, currency, metadata);
  };

  return { track, trackConversion };
}

Next.js

// lib/tinytapanalytics.js
import TinyTap Analytics from '@tinytapanalytics/sdk';

let sdk = null;

export function initTinyTap Analytics() {
  if (typeof window !== 'undefined' && !sdk) {
    sdk = new TinyTap Analytics({
      apiKey: process.env.NEXT_PUBLIC_CONVERSION_IQ_API_KEY,
      websiteId: process.env.NEXT_PUBLIC_CONVERSION_IQ_WEBSITE_ID,
      enableMicroInteractions: true, // Enable behavioral psychology
      debug: process.env.NODE_ENV === 'development'
    });
  }
  return sdk;
}

// pages/_app.js
import { useEffect } from 'react';
import { useRouter } from 'next/router';
import { initTinyTap Analytics } from '../lib/tinytapanalytics';

export default function App({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    const ciq = initTinyTap Analytics();

    const handleRouteChange = () => {
      ciq?.trackPageView();
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    handleRouteChange(); // Track initial page view

    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return <Component {...pageProps} />;
}

🧪 Real-World Use Cases

E-commerce: Reduce Cart Abandonment

import TinyTap Analytics from '@tinytapanalytics/sdk';
import { MicroInteractionTracking } from '@tinytapanalytics/sdk/features/MicroInteractionTracking';

const ciq = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  enableMicroInteractions: true
});

const microTracking = new MicroInteractionTracking(ciq);

// Start tracking checkout behavior
microTracking.start();

// Listen for high-risk abandonment alerts
microTracking.on('abandonmentRisk', (alert) => {
  if (alert.riskScore > 0.7 && alert.pageUrl.includes('/checkout')) {
    // Show intervention
    showExitIntentPopup({
      message: 'Having trouble? Chat with us!',
      offer: '10% off if you complete your order now'
    });
  }
});

SaaS: Improve Onboarding Completion

// Detect users struggling with onboarding
microTracking.on('frustrationDetected', (session) => {
  if (session.frustrationScore > 0.8 && isOnboardingPage()) {
    // Trigger helpful intervention
    showContextualHelp({
      message: 'Need help getting started?',
      action: 'Schedule 15-min onboarding call'
    });
  }
});

B2B: Save High-Value Leads

// Track form hesitation on demo request
microTracking.on('formAnxiety', (data) => {
  if (data.backspaceCount > 5 && data.hesitationDuration > 3000) {
    // Reduce form friction
    showInlineChatAssist({
      message: 'Questions about the demo? Ask away!'
    });
  }
});

📊 Understanding Psychology Metrics

Frustration Score (0-100)

Indicates user frustration based on:

• Rage clicks: Rapid repeated clicks on non-responsive elements
• Error encounters: Form validation failures, broken interactions
• Excessive hesitation: Long delays before actions
• High backspace count: Repeated corrections in forms

Interpretation:

• 0-30: Low frustration (normal behavior)
• 30-60: Moderate friction (watch closely)
• 60-100: High frustration (intervention recommended)

Confidence Score (0-100)

Indicates user confidence based on:

• Click speed: Fast, decisive clicks vs. hesitant hovering
• Form fill patterns: Smooth entry vs. corrections
• Navigation certainty: Direct paths vs. backtracking
• Error recovery: Quick fixes vs. abandonment

Interpretation:

• 70-100: High confidence (likely to convert)
• 40-70: Moderate confidence (needs support)
• 0-40: Low confidence (high risk)

Abandonment Risk (0-1 probability)

Predictive score based on:

• Frustration score > 70
• Confidence score < 30
• Multiple error encounters
• Extended hesitation on key actions
• Exit-intent signals

Intervention Thresholds:

• 0.0-0.3: Low risk (monitor)
• 0.3-0.7: Medium risk (prepare intervention)
• 0.7-1.0: High risk (intervene immediately)

🔧 Advanced Configuration

import TinyTap Analytics from '@tinytapanalytics/sdk';

const sdk = new TinyTap Analytics({
  // Required
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',

  // Behavioral Psychology Features
  enableMicroInteractions: true,

  // Batching & Performance
  batchSize: 10,           // Events per batch
  batchInterval: 5000,     // Send behavioral data every 5s
  timeout: 5000,           // Request timeout (ms)

  // Privacy & Compliance
  enablePrivacyMode: true, // GDPR/CCPA compliance

  // Retry configuration
  retry: {
    maxAttempts: 3,
    baseDelay: 1000,
    maxDelay: 10000
  },

  // Debugging
  debug: false
});

🛡️ Privacy & GDPR Compliance

TinyTap Analytics is privacy-first by design:

What We DON'T Collect

• ❌ No session recordings or screen captures
• ❌ No personally identifiable information (PII)
• ❌ No form field values or sensitive data
• ❌ No full-page screenshots

What We DO Collect

• ✅ Behavioral signals (click patterns, scroll speed)
• ✅ Element selectors (which button, not what's in it)
• ✅ Interaction timing (hesitation, rage clicks)
• ✅ Psychology scores (calculated client-side)

Privacy Controls

// Check privacy status
const privacyStatus = sdk.getPrivacyStatus();
console.log(privacyStatus); // { analytics: false, microInteractions: true }

// Update consent
sdk.updatePrivacyConsent({
  essential: true,         // Always required
  analytics: true,         // Usage analytics
  microInteractions: true  // Behavioral psychology
});

// Conditional tracking based on consent
if (privacyStatus.microInteractions) {
  microTracking.start();
}

🆚 How TinyTap Analytics Compares

vs. Google Analytics

Google Analytics tells you what happened after visitors leave. TinyTap Analytics tells you why they're leaving and alerts you in real-time.

Use together: GA for traffic analytics, TinyTap Analytics for behavioral insights.

vs. Hotjar / Crazy Egg

Hotjar shows where users click with heatmaps and session recordings. TinyTap Analytics shows how they're feeling without privacy-invasive recordings.

The difference: Psychology signals vs. video surveillance.

vs. FullStory / LogRocket

FullStory records everything for debugging. TinyTap Analytics detects what matters without storing sensitive data.

The difference: Behavioral intelligence, not session replay.

vs. Heap / Amplitude

Heap tracks feature usage and product analytics. TinyTap Analytics detects emotional state and abandonment risk.

The difference: Product analytics vs. behavioral psychology.

🚨 Error Handling & Debugging

// Enable debug mode
const sdk = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  debug: true // Logs all SDK activity
});

// Handle errors gracefully
sdk.track('purchase', purchaseData).catch(error => {
  console.warn('TinyTap Analytics tracking failed:', error);
  // Continue with user flow - never block conversions
});

// Check SDK health
if (window.TinyTap Analytics) {
  console.log('TinyTap Analytics SDK loaded');
  console.log('Config:', window.TinyTap Analytics.config);
}

📝 TypeScript Support

import TinyTap Analytics, {
  TinyTap AnalyticsConfig,
  MicroInteractionEvent,
  SessionPsychologyProfile,
  AbandonmentAlert
} from '@tinytapanalytics/sdk';

const config: TinyTap AnalyticsConfig = {
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  enableMicroInteractions: true
};

const sdk = new TinyTap Analytics(config);

// Type-safe event tracking
const eventData: MicroInteractionEvent = {
  type: 'rage_click',
  elementSelector: 'button#checkout',
  clickCount: 5,
  timestamp: Date.now()
};

sdk.track('micro_interaction', eventData);

📈 Performance Best Practices

1. Use the Right Bundle

• Minimal (1.0 KB): Basic tracking only
• Core (14.2 KB): Full SDK with behavioral features
• Micro-Interactions (10.8 KB): Psychology module only

2. Batch Behavioral Data

const sdk = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  batchSize: 10,        // Send 10 events at once
  batchInterval: 5000   // Or every 5 seconds
});

3. Lazy Load Advanced Features

// Load psychology features only on key pages
if (isCheckoutPage()) {
  const { MicroInteractionTracking } = await import('@tinytapanalytics/sdk/features/MicroInteractionTracking');
  const tracker = new MicroInteractionTracking(config);
  tracker.start();
}

🧪 Testing

Unit Testing

import TinyTap Analytics from '@tinytapanalytics/sdk/minimal';

global.fetch = jest.fn();

describe('TinyTap Analytics SDK', () => {
  let sdk;

  beforeEach(() => {
    fetch.mockClear();
    sdk = new TinyTap Analytics({
      apiKey: 'test-key',
      websiteId: 'test-site'
    });
  });

  test('tracks micro-interactions with correct payload', async () => {
    fetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({ success: true })
    });

    await sdk.track('rage_click', {
      elementSelector: 'button#submit',
      clickCount: 5
    });

    expect(fetch).toHaveBeenCalledWith(
      expect.stringContaining('/micro-interactions'),
      expect.objectContaining({
        method: 'POST'
      })
    );
  });
});

🛠️ Troubleshooting

Events not tracking

// Check configuration
console.log('SDK Config:', sdk.config);

// Enable debug mode
const sdk = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  debug: true // This will log all SDK activity
});

// Verify network requests in DevTools > Network tab

Micro-interactions not detected

// Ensure feature is enabled
const sdk = new TinyTap Analytics({
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  enableMicroInteractions: true // Must be true
});

// Verify module is loaded
import { MicroInteractionTracking } from '@tinytapanalytics/sdk/features/MicroInteractionTracking';
const tracker = new MicroInteractionTracking(sdk);
tracker.start(); // Must call start()

📚 API Reference

Core Methods

new TinyTap Analytics(config)

Creates a new SDK instance with behavioral psychology features.

Parameters:

• config.apiKey (string, required): Your TinyTap Analytics API key
• config.websiteId (string, required): Your website ID
• config.enableMicroInteractions (boolean): Enable behavioral psychology (default: false)
• config.batchInterval (number): Batch send interval in ms (default: 5000)

track(eventType, data)

Track custom events or micro-interactions.

Returns: Promise

trackConversion(value, currency, metadata)

Track conversion events with value.

Returns: Promise

updatePrivacyConsent(consents)

Update privacy consent for behavioral tracking.

Parameters:

• consents.microInteractions (boolean): Allow micro-interaction tracking

For complete API documentation, visit docs.tinytapanalytics.com.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License. See LICENSE for details.

🆘 Support

• 📧 Email: [e-mail]
• 💬 Community: TinyTap Analytics Community
• 📖 Documentation: docs.tinytapanalytics.com
• 🐛 Issues: GitHub Issues

Built with behavioral psychology by the TinyTap Analytics Team