test-unified-analytics

v1.0.1

Published

4 days ago

Unified analytics library supporting multiple providers (Countly, PostHog) for React Native and Web

0High
0Medium
0Low

rameshgotagi

analytics countly posthog react-native react nextjs web

Unified Analytics Library

A pure facade layer for analytics that provides a single, unified API across multiple analytics providers (Countly, PostHog) on both React Native and Web (React.js / Next.js).

Core Philosophy

One API to rule them all. The app code uses only unified methods - no provider-specific code required. The library internally maps to the appropriate provider implementations with graceful degradation when features aren't supported.

Key Features

Pure Facade Pattern: Single unified API, no provider-specific exposure
Cross-Platform: Works on React Native and Web (React.js/Next.js)
Graceful Degradation: Features return null/false when not supported instead of errors
Multi-Provider Support: Use Countly, PostHog, or both simultaneously
React Hooks: Easy integration with useAnalytics() hook
Zero Configuration: Auto-detects platform, works with one or both providers

Installation

Copy this library to your project (e.g., libs/unified-analytics)
Install the provider SDK(s) you want to use:

React Native:

# For Countly
yarn add countly-sdk-react-native-bridge@^24.4.0

# For PostHog
yarn add posthog-react-native@^3.0.0

Web (React.js / Next.js):

# For Countly
yarn add countly-sdk-web

# For PostHog
yarn add posthog-js

Quick Start

React Native Setup

1. Initialize Analytics

// App.js
import { analytics, AnalyticsProvider } from './libs/unified-analytics';

await analytics.init({
  platform: 'native', // optional, auto-detected

  countly: {
    serverUrl: 'https://your-countly-server.com',
    appKey: 'your-app-key',
    enableCrashReporting: true,
  },

  posthog: {
    apiKey: 'phc_xxxxx',
    enableSessionReplay: true,
    captureNativeAppLifecycleEvents: true,
  },

  debug: __DEV__,
});

// Wrap your app
export default function App() {
  return (
    <AnalyticsProvider>
      <Navigation />
    </AnalyticsProvider>
  );
}

2. Setup Navigation Tracking (React Navigation)

import { analytics } from './libs/unified-analytics';

function App() {
  const navigationRef = useRef();

  const { onReady, onStateChange } = analytics.createNavigationHandlers(navigationRef);

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={onReady}
      onStateChange={onStateChange}
    >
      <Navigator />
    </NavigationContainer>
  );
}

Web (Next.js) Setup

1. Initialize Analytics

// _app.js or layout.js
import { analytics, AnalyticsProvider } from 'unified-analytics';

await analytics.init({
  platform: 'web',

  countly: {
    serverUrl: 'https://your-countly-server.com',
    appKey: 'your-web-app-key',
    debug: process.env.NODE_ENV === 'development',
  },

  posthog: {
    apiKey: 'phc_xxxxx',
    host: 'https://us.i.posthog.com',
    debug: process.env.NODE_ENV === 'development',
    enableSessionReplay: true,
    autocapture: {
      captureClicks: true,
      capturePageviews: false, // We handle this manually
    },
  },

  debug: process.env.NODE_ENV === 'development',
});

2. Setup Navigation Tracking

Next.js Pages Router:

import Router from 'next/router';
import { analytics } from 'unified-analytics';

const { onRouteChange } = analytics.createWebNavigationHandlers();
Router.events.on('routeChangeComplete', onRouteChange);

Next.js App Router:

'use client';
import { usePathname } from 'next/navigation';
import { analytics } from 'unified-analytics';
import { useEffect, useRef } from 'react';

function NavigationTracker() {
  const pathname = usePathname();
  const handlersRef = useRef(analytics.createWebNavigationHandlers());

  useEffect(() => {
    handlersRef.current.onRouteChange(pathname);
  }, [pathname]);

  return null;
}

React Router:

import { useLocation } from 'react-router-dom';
import { analytics } from 'unified-analytics';
import { useEffect, useRef } from 'react';

function NavigationTracker() {
  const location = useLocation();
  const handlersRef = useRef(analytics.createWebNavigationHandlers());

  useEffect(() => {
    handlersRef.current.onRouteChange(location.pathname);
  }, [location]);

  return null;
}

3. Use in Components (Same on Both Platforms)

import { useAnalytics } from 'unified-analytics';

function MyComponent() {
  const {
    trackEvent,
    setGlobalProperties,
    trackError,
    getFeatureFlag,
  } = useAnalytics();

  const handleLogin = (user) => {
    setGlobalProperties({
      user_id: user.id,
      role: user.role,
      organization: user.org,
    });

    trackEvent('login', { method: 'email' });
  };

  const handleButtonClick = () => {
    trackEvent('button_click', {
      button: 'submit',
      screen: 'Profile',
    });
  };

  const handleError = (error) => {
    trackError(error, {
      screen: 'Profile',
      action: 'update_profile',
    });
  };

  const checkFeature = () => {
    const isEnabled = getFeatureFlag('new_feature');
    if (isEnabled) {
      // Show new feature
    }
  };

  return <Button onPress={handleButtonClick} title="Submit" />;
}

Platform Configuration

Platform Detection

The library auto-detects the platform, but you can explicitly set it:

analytics.init({
  platform: 'native', // or 'web'
  // ...
});

Auto-detection logic:

Native: navigator.product === 'ReactNative'
Web: typeof window !== 'undefined' and not React Native

Platform Utilities

import { setPlatform, getPlatform, isWeb, isNative } from 'unified-analytics';

console.log(getPlatform()); // 'web' or 'native'
console.log(isWeb());       // true/false
console.log(isNative());    // true/false

Complete API Reference