tapp-analytics-react-native

Unified analytics SDK for React Native applications across Web, iOS, and Android platforms. Provides automatic UX monitoring, form tracking, and custom event support with a single API.

Features

• Cross-Platform: Works on Web, iOS, and Android with the same API
• Automatic Tracking: Page views, scroll depth, session management
• Semi-Automatic: Form interactions, errors, conversions
• Custom Events: Full control over event names and properties
• Unified Schema: All events go to a single events_unified table
• TypeScript Support: Full type definitions included

Installation

npm install tapp-analytics-react-native
# or
yarn add tapp-analytics-react-native

iOS Setup

1. Add to your ios/Podfile:

pod 'TappAnalytics', :path => '../node_modules/@tapp/analytics-react-native/ios'

2. Run cd ios && pod install

Android Setup

1. Add to your android/settings.gradle:

include ':tapp-analytics-react-native'
project(':tapp-analytics-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@tapp/analytics-react-native/android')

2. Add to your android/app/build.gradle:

dependencies {
    implementation project(':tapp-analytics-react-native')
}

Quick Start

import TappAnalytics from 'tapp-analytics-react-native';

// Initialize
await TappAnalytics.init({
  writeKey: 'your-rudderstack-write-key',
  dataPlaneUrl: 'https://your-data-plane.com',
  source: 'mobile_ios', // or 'mobile_android', 'web'
  branch: 'main',
  environment: 'production'
});

// Identify user
TappAnalytics.identify('user-123');

// Track page view
TappAnalytics.trackPageView({
  pageUrl: '/dashboard',
  pageTitle: 'Dashboard',
  referrer: '/login'
});

// Track custom event
TappAnalytics.trackEvent('button_clicked', {
  button_name: 'checkout',
  page_url: '/cart'
});

API Reference

Configuration

interface AnalyticsConfig {
  writeKey: string;           // RudderStack write key
  dataPlaneUrl: string;      // RudderStack data plane URL
  source: string;            // 'web', 'mobile_ios', 'mobile_android'
  branch: string;            // Git branch: 'main', 'develop', 'feature-xyz'
  environment: string;       // 'production', 'staging', 'test'
}

Core Methods

init(config: AnalyticsConfig)

Initialize the analytics SDK.

identify(userId: string)

Identify a logged-in user.

logout()

Clear user identification.

Tier 1: Automatic Tracking

trackPageView(event: PageViewEvent)

Track page/screen views.

interface PageViewEvent {
  pageUrl: string;
  pageTitle: string;
  referrer?: string;
}

trackScrollDepth(scrollDepth: number, pageUrl: string)

Track scroll depth (0-100%).

Tier 2: Semi-Automatic Tracking

trackFormStart(event: FormEvent)

Track when a form is started.

trackFormField(event: FormEvent)

Track form field interactions.

trackFormSubmit(event: FormEvent)

Track form submissions.

trackError(event: ErrorEvent)

Track error events.

trackConversion(event: ConversionEvent)

Track conversion/goal completion.

Tier 3: Custom Tracking

trackEvent(eventName: string, properties?: Record<string, any>)

Track custom events with full control.

React Native Navigation Integration

React Navigation

import { useNavigationState } from '@react-navigation/native';

// Track screen changes
useNavigationState(state => {
  const currentRoute = state.routes[state.index];
  TappAnalytics.trackPageView({
    pageUrl: `/${currentRoute.name}`,
    pageTitle: currentRoute.name,
    referrer: previousRoute?.name
  });
  return state;
});

React Router (Web)

import { useLocation } from 'react-router-dom';

const location = useLocation();

useEffect(() => {
  TappAnalytics.trackPageView({
    pageUrl: location.pathname,
    pageTitle: document.title,
    referrer: document.referrer
  });
}, [location]);

Form Tracking

// Form start
TappAnalytics.trackFormStart({
  formName: 'checkout',
  formId: 'checkout-form'
});

// Field interaction
TappAnalytics.trackFormField({
  formName: 'checkout',
  formId: 'checkout-form',
  fieldName: 'email'
});

// Form submission
TappAnalytics.trackFormSubmit({
  formName: 'checkout',
  formId: 'checkout-form'
});

Error Tracking

// JavaScript errors
window.addEventListener('error', (event) => {
  TappAnalytics.trackError({
    errorType: 'javascript_error',
    errorMessage: event.message,
    pageUrl: window.location.pathname
  });
});

// React error boundaries
componentDidCatch(error, errorInfo) {
  TappAnalytics.trackError({
    errorType: 'react_error',
    errorMessage: error.message,
    pageUrl: window.location.pathname
  });
}

Conversion Tracking

// Track conversions
TappAnalytics.trackConversion({
  goalName: 'purchase_completed',
  value: 99.99,
  metadata: {
    product_id: 'prod-123',
    currency: 'USD'
  }
});

Event Categories

Events are automatically categorized:

• UX Events: page_view, scroll_depth, form_*, error, conversion
• Custom Events: Developer-defined events default to ux category

Data Schema

All events are sent to the events_unified table with this structure:

CREATE TABLE events_unified (
  event_id UUID PRIMARY KEY,
  user_id TEXT,
  anonymous_id TEXT NOT NULL,
  session_id TEXT NOT NULL,
  source TEXT NOT NULL,           -- 'web', 'mobile_ios', 'mobile_android'
  branch TEXT NOT NULL,           -- Git branch
  environment TEXT NOT NULL,      -- 'production', 'staging', 'test'
  event_category TEXT NOT NULL,   -- 'ux', 'payment', 'ai', etc.
  event_name TEXT NOT NULL,       -- Event name
  timestamp TIMESTAMP WITH TIME ZONE,
  properties JSONB,               -- Event-specific data
  context JSONB                   -- Device/browser context
);

Context Data

The SDK automatically collects context:

{
  device_type: 'mobile' | 'desktop',
  os: 'iOS' | 'Android' | 'Web',
  os_version: string,
  app_version: string,
  screen_width: number,
  screen_height: number,
  timezone: string,
  locale: string,
  language: string,
  platform: 'ios' | 'android' | 'web'
}

TypeScript Support

Full TypeScript definitions are included:

import TappAnalytics, { 
  AnalyticsConfig, 
  PageViewEvent, 
  FormEvent, 
  ErrorEvent, 
  ConversionEvent 
} from '@tapp/analytics-react-native';

Browser Compatibility

• Web: Modern browsers (ES2015+)
• iOS: iOS 10+
• Android: API 21+ (Android 5.0+)

License

MIT

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation