tapp-analytics

Unified analytics SDK for web, mobile, and API tracking with automatic UX monitoring and custom event support.

Features

• Automatic Tracking: Page views, scroll depth, time on page, session management
• Semi-Automatic: Form tracking, error tracking, conversion tracking
• Custom Events: Full control for business-specific tracking
• Cross-Platform: Web, mobile, and API event correlation
• TypeScript Support: Full type definitions included
• Zero Dependencies: Lightweight and fast

Installation

npm install tapp-analytics

Quick Start

import analytics from 'tapp-analytics';

// Initialize with your configuration
analytics.init({
  writeKey: 'your-rudderstack-write-key',
  dataPlaneUrl: 'https://your-data-plane.com',
  source: 'web',
  branch: 'main',
  environment: 'production'
});

// Automatic tracking begins immediately!
// Page views, scrolls, time tracking work out of the box

Configuration

Required Parameters

| Parameter | Type | Description | Example | |-----------|------|-------------|---------| | writeKey | string | Your RudderStack write key | '34MmxSiPhy18kfNdHkG4FuO1XeX' | | dataPlaneUrl | string | RudderStack data plane URL | 'https://usetappadgukvk.dataplane.rudderstack.com' | | source | string | Platform identifier | 'web', 'mobile_ios', 'mobile_android', 'api' | | branch | string | Git branch name | 'main', 'develop', 'feature-xyz' | | environment | string | Deployment environment | 'production', 'staging', 'test' |

Optional Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | respectDoNotTrack | boolean | false | Respect browser Do Not Track setting |

Three-Tier Tracking System

Tier 1: Automatic Tracking (No Code Required)

These events are tracked automatically without any developer implementation:

// These happen automatically:
// - page_view (on navigation)
// - scroll_depth (at 25%, 50%, 75%, 100%)
// - page_exit (with time on page)
// - session_started (on first visit)
// - user_idle (when tab becomes inactive)
// - session_resumed (when tab becomes active)

Tier 2: Semi-Automatic Tracking (Minimal Code)

Helper methods that require minimal developer input:

// Form tracking
analytics.trackFormStart({ formName: 'checkout' });
analytics.trackFormSubmit({ formName: 'checkout' });

// Error tracking
analytics.trackError({
  errorType: 'validation',
  errorMessage: 'Email is required'
});

// Conversion tracking
analytics.trackConversion({
  goalName: 'signup_completed',
  value: 0
});

Tier 3: Custom Tracking (Full Control)

For business-specific events with complete control:

// E-commerce tracking
analytics.trackEvent('add_to_cart', {
  product_id: 'prod_123',
  product_name: 'iPhone 15',
  product_price: 999,
  category: 'electronics'
});

// Custom business events
analytics.trackEvent('feature_used', {
  feature_name: 'advanced_search',
  search_query: 'wireless headphones'
});

API Reference

Core Methods

analytics.init(config)

Initialize the analytics SDK with your configuration.

analytics.identify(userId)

Identify a logged-in user for cross-platform tracking.

analytics.logout()

Clear user identification (call on logout).

Tracking Methods

analytics.trackPageView(event)

Manually track a page view (usually automatic).

analytics.trackPageView({
  pageUrl: '/products',
  pageTitle: 'Products - My Store'
});

analytics.trackFormStart(event)

Track when a user starts filling a form.

analytics.trackFormStart({
  formName: 'checkout',
  formId: 'checkout-form'
});

analytics.trackFormSubmit(event)

Track when a user submits a form.

analytics.trackFormSubmit({
  formName: 'checkout',
  formId: 'checkout-form'
});

analytics.trackError(event)

Track errors and validation issues.

analytics.trackError({
  errorType: 'validation',
  errorMessage: 'Invalid email format',
  pageUrl: '/signup'
});

analytics.trackConversion(event)

Track goal completions and conversions.

analytics.trackConversion({
  goalName: 'purchase_completed',
  value: 149.99,
  metadata: {
    order_id: 'ORD-2025-001',
    items_count: 3
  }
});

analytics.trackEvent(eventName, properties)

Track custom events with full control.

analytics.trackEvent('button_click', {
  button_text: 'Add to Cart',
  button_id: 'add-to-cart-btn',
  product_id: 'prod_123'
});

Event Categories

The SDK automatically categorizes events:

• UX Events: page_view, scroll_depth, form_started, error, etc.
• Payment Events: payment_initiated, payment_completed (future)
• AI Events: ai_inference_made, recommendation_generated (future)
• System Events: session_started, user_idle (future)

Cross-Platform Tracking

Events are linked across platforms using user_id:

// Web app
analytics.identify('user_123');
analytics.trackEvent('product_viewed', { product_id: 'prod_123' });

// Mobile app (same user_id)
analytics.identify('user_123');
analytics.trackEvent('add_to_cart', { product_id: 'prod_123' });

// Both events are linked to the same user in analytics

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• Internet Explorer 11 (with polyfills)

TypeScript Support

Full TypeScript definitions are included:

import analytics, { AnalyticsConfig } from '@tapp/analytics';

const config: AnalyticsConfig = {
  writeKey: 'your-key',
  dataPlaneUrl: 'https://your-url.com',
  source: 'web',
  branch: 'main',
  environment: 'production'
};

analytics.init(config);

Examples

React Integration

import React, { useEffect } from 'react';
import analytics from '@tapp/analytics';

function App() {
  useEffect(() => {
    analytics.init({
      writeKey: process.env.REACT_APP_RUDDERSTACK_KEY,
      dataPlaneUrl: process.env.REACT_APP_RUDDERSTACK_URL,
      source: 'web',
      branch: process.env.REACT_APP_BRANCH || 'main',
      environment: process.env.NODE_ENV
    });
  }, []);

  const handlePurchase = () => {
    analytics.trackConversion({
      goalName: 'purchase_completed',
      value: 99.99
    });
  };

  return <button onClick={handlePurchase}>Buy Now</button>;
}

Vue Integration

import { createApp } from 'vue';
import analytics from '@tapp/analytics';

const app = createApp({});

// Initialize analytics
analytics.init({
  writeKey: import.meta.env.VITE_RUDDERSTACK_KEY,
  dataPlaneUrl: import.meta.env.VITE_RUDDERSTACK_URL,
  source: 'web',
  branch: import.meta.env.VITE_BRANCH || 'main',
  environment: import.meta.env.MODE
});

app.mount('#app');

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@tapp/analytics/dist/index.umd.min.js"></script>
</head>
<body>
  <script>
    TappAnalytics.init({
      writeKey: 'your-key',
      dataPlaneUrl: 'https://your-url.com',
      source: 'web',
      branch: 'main',
      environment: 'production'
    });
  </script>
</body>
</html>

License

MIT

Support

• Documentation
• Issues
• Changelog