@connectaryal/google-analytics

Modern Google Analytics 4 - Type-safe, performance-optimized, production-ready React library.

Why Choose This Library?

Unlike other GA4 libraries, this one is built for modern React applications with enterprise-grade features:

• Zero Configuration - Works out of the box with sensible defaults
• 100% Type Safe - Full TypeScript support with intelligent autocomplete
• Performance Optimized - Event batching, memory leak prevention, and automatic initialization
• Complete Ecommerce - Enhanced ecommerce tracking with all GA4 events
• React Hooks - Modern React patterns with custom hooks
• No Script Conflicts - Prevents duplicate GA script loading
• Debug Mode - Development-friendly error reporting and validation
• Event Validation - Automatic parameter validation and sanitization

---

Quick Start

Installation

npm install @connectaryal/google-analytics
# or
yarn add @connectaryal/google-analytics
# or
pnpm add @connectaryal/google-analytics

Basic Setup

// 1. Wrap your app with GAProvider
import { GAProvider } from "@connectaryal/google-analytics";

function App() {
  const gaConfig = {
    measurementId: "G-XXXXXXXXXX",
    debug: process.env.NODE_ENV === "development",
  };

  return (
    <GAProvider config={gaConfig}>
      <YourApp />
    </GAProvider>
  );
}

Using Analytics Hooks

import {
  useGoogleAnalytics,
  useGAEcommerce,
} from "@connectaryal/google-analytics";

function HomePage() {
  const { trackPage, trackCustomEvent } = useGoogleAnalytics();
  const { trackCart } = useGAEcommerce();

  // Track page views automatically
  useEffect(() => {
    trackPage({ title: "Home Page" });
  }, [trackPage]);

  // Track custom events
  const handleHeroCTA = () => {
    trackCustomEvent({
      name: "hero_cta_click",
      params: {
        button_text: "Get Started",
        section: "hero",
      },
    });
  };

  // Track ecommerce events
  const handleAddToCart = (product) => {
    trackCart({
      action: "add_to_cart",
      items: [
        {
          item_id: product.id,
          item_name: product.name,
          price: product.price,
          quantity: 1,
        },
      ],
      value: product.price,
    });
  };

  return (
    <div>
      <button onClick={handleHeroCTA}>Get Started</button>
      <button onClick={() => handleAddToCart(product)}>Add to Cart</button>
    </div>
  );
}

---

Core Features

Page Tracking

const { trackPage } = useGoogleAnalytics();

// Basic page tracking
trackPage();

// Custom page tracking with parameters
trackPage({
  path: "/products/wireless-headphones",
  title: "Wireless Headphones - Best Audio Experience",
  referrer: "https://google.com",
});

// Track single-page application navigation
const router = useRouter();
useEffect(() => {
  const handleRouteChange = (url) => {
    trackPage({ path: url });
  };

  router.events.on("routeChangeComplete", handleRouteChange);
  return () => router.events.off("routeChangeComplete", handleRouteChange);
}, [router, trackPage]);

Custom Event Tracking

const {
  trackCustomEvent,
  trackEngagement,
  trackSearch,
  trackFormSubmission,
  trackVideoPlay,
  trackException,
} = useGoogleAnalytics();

// Simple custom event
trackCustomEvent({
  name: "newsletter_signup",
  params: {
    method: "popup",
    location: "homepage",
  },
});

// User engagement tracking
trackEngagement({
  type: "scroll",
  options: {
    scroll_depth: 75,
    page_title: "Product Details",
  },
});

// Search tracking
trackSearch({
  searchTerm: "wireless headphones",
  options: {
    search_results: 24,
    search_category: "electronics",
  },
});

// Form submission tracking
trackFormSubmission({
  formId: "contact_form",
  formData: {
    form_type: "contact",
    user_type: "new_visitor",
  },
});

// Video interaction tracking
trackVideoPlay({
  title: "Product Demo Video",
  url: "https://example.com/video.mp4",
  duration: 120,
  customParams: {
    video_category: "product_demo",
  },
});

// Exception tracking
trackException({
  description: "Payment processing failed",
  fatal: false,
  customParams: {
    error_code: "PAYMENT_001",
    user_id: "user123",
  },
});

Authentication Events

// User login tracking
const { trackLogin, trackSignUp } = useGAAuth();

trackLogin({
  method: "google",
  customParams: {
    user_type: "returning",
  },
});

// User signup tracking
trackSignUp({
  method: "email",
  customParams: {
    campaign: "summer_sale",
  },
});

Social Sharing

// Track social shares
const { trackShare } = useGoogleAnalytics();

trackShare({
  contentType: "article",
  contentId: "how-to-setup-analytics",
  method: "twitter",
  customParams: {
    share_location: "article_bottom",
  },
});

---

Complete Ecommerce Tracking

Product Interactions

const { trackItem } = useGAEcommerce();

// View item
trackItem({
  action: "view_item",
  items: [
    {
      item_id: "SKU123",
      item_name: "Wireless Headphones",
      item_category: "Electronics",
      item_brand: "AudioTech",
      price: 99.99,
      quantity: 1,
    },
  ],
  value: 99.99,
  customParams: {
    source: "product_list",
  },
});

// View item list
trackItem({
  action: "view_item_list",
  items: products,
  item_list_id: "electronics_featured",
  item_list_name: "Featured Electronics",
});

// Select item
trackItem({
  action: "select_item",
  items: [selectedProduct],
  item_list_id: "search_results",
  item_list_name: "Search Results",
});

Shopping Cart

const { trackCart } = useGAEcommerce();

// Add to cart
trackCart({
  action: "add_to_cart",
  items: [
    {
      item_id: "SKU123",
      item_name: "Wireless Headphones",
      price: 99.99,
      quantity: 2,
    },
  ],
  value: 199.98,
  customParams: {
    add_source: "product_page",
  },
});

// Remove from cart
trackCart({
  action: "remove_from_cart",
  items: [removedItem],
  value: removedItem.price * removedItem.quantity,
});

// View cart
trackCart({
  action: "view_cart",
  items: cartItems,
  value: cartTotal,
});

Checkout Process

const { trackBeginCheckout, trackShippingInfo, trackPaymentInfo } =
  useGAEcommerce();

// Begin checkout
trackBeginCheckout({
  value: 199.98,
  items: cartItems,
  customParams: {
    checkout_step: 1,
    checkout_option: "guest",
  },
});

// Add shipping info
trackShippingInfo({
  items: cartItems,
  value: 199.98,
  shipping_tier: "standard",
  customParams: {
    shipping_cost: 9.99,
  },
});

// Add payment info
trackPaymentInfo(
  cartItems,
  209.97, // total with shipping
  "credit_card",
  {
    payment_provider: "stripe",
  }
);

Purchase & Refunds

// Track purchase
const { trackPurchase, trackRefund } = useGAEcommerce();

// Track purchase
trackPurchase({
  transactionId: "ORDER_12345",
  value: 209.97,
  items: purchasedItems,
  customParams: {
    affiliation: "Online Store",
    coupon: "SAVE10",
    shipping: 9.99,
    tax: 16.8,
  },
});

// Track refund
trackRefund({
  transactionId: "ORDER_12345",
  value: 99.99,
  items: [refundedItem],
  customParams: {
    refund_reason: "defective_product",
  },
});

Wishlist Tracking

const { trackWishlist } = useGAEcommerce();

// Add to wishlist
trackWishlist({
  action: "add_to_wishlist",
  items: [product],
  value: product.price,
  customParams: {
    wishlist_name: "favorites",
  },
});

// View wishlist
trackWishlist({
  action: "view_wishlist",
  items: wishlistItems,
  value: wishlistTotal,
});

Promotion Tracking

const { trackPromotion } = useGAEcommerce();

// View promotion
trackPromotion({
  action: "view_promotion",
  items: promotionalItems,
  creative_name: "Summer Sale Banner",
  creative_slot: "hero_banner",
  promotion_id: "SUMMER2024",
  promotion_name: "Summer Sale 50% Off",
});

// Select promotion
trackPromotion({
  action: "select_promotion",
  items: promotionalItems,
  creative_name: "Summer Sale Banner",
  creative_slot: "hero_banner",
  promotion_id: "SUMMER2024",
  promotion_name: "Summer Sale 50% Off",
});

---

Framework Integration

Next.js App Router

// app/layout.tsx
import { GAProvider } from "@connectaryal/google-analytics";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const gaConfig = {
    measurementId: "G-XXXXXXXXXX",
    debug: process.env.NODE_ENV === "development",
    currency: "USD",
  };

  return (
    <html lang="en">
      <body>
        <GAProvider config={gaConfig}>{children}</GAProvider>
      </body>
    </html>
  );
}

Suggestion: Wrap by a custom provider

// app/components/AnalyticsTracker.tsx
"use client";

import { usePathname } from "next/navigation";
import { useGoogleAnalytics } from "@connectaryal/google-analytics";
import { useEffect } from "react";

export function AnalyticsLayout() {
  const pathname = usePathname();
  const { trackPage } = useGoogleAnalytics();

  useEffect(() => {
    trackPage({ path: pathname });
  }, [pathname, trackPage]);

  return null;
}

Next.js Pages Router

// pages/_app.tsx
import type { AppProps } from "next/app";
import { GAProvider } from "@connectaryal/google-analytics";
import { useRouter } from "next/router";
import { useGoogleAnalytics } from "@connectaryal/google-analytics";
import { useEffect } from "react";

function AnalyticsTracker() {
  const router = useRouter();
  const { trackPage } = useGoogleAnalytics();

  useEffect(() => {
    const handleRouteChange = (url: string) => {
      trackPage({ path: url });
    };

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

  return null;
}

export default function App({ Component, pageProps }: AppProps) {
  const gaConfig = {
    measurementId: "G-XXXXXXXXXX",
    debug: process.env.NODE_ENV === "development",
    currency: "USD",
  };

  return (
    <GAProvider config={gaConfig}>
      <AnalyticsTracker />
      <Component {...pageProps} />
    </GAProvider>
  );
}

React Router

import { BrowserRouter, useLocation } from "react-router-dom";
import { GAProvider, useGoogleAnalytics } from "@connectaryal/google-analytics";

function AnalyticsTracker() {
  const location = useLocation();
  const { trackPage } = useGoogleAnalytics();

  useEffect(() => {
    trackPage({ path: location.pathname });
  }, [location, trackPage]);

  return null;
}

function App() {
  return (
    <GAProvider config={{ measurementId: "G-XXXXXXXXXX" }}>
      <BrowserRouter>
        <AnalyticsTracker />
        <Routes>{/* Your routes */}</Routes>
      </BrowserRouter>
    </GAProvider>
  );
}

---

Advanced Configuration

Complete Configuration Options

const gaConfig = {
  measurementId: "G-XXXXXXXXXX",
  debug: process.env.NODE_ENV === "development",
  currency: "USD",
  disableGA: false,
  customConfig: {
    // GDPR/Privacy compliance
    analytics_storage: "granted",
    ad_storage: "denied",
    ad_user_data: "denied",
    ad_personalization: "denied",

    // Custom settings
    send_page_view: false, // Disable automatic page views
    custom_map: {
      custom_parameter_1: "user_type",
    },
  },
};

<GAProvider config={gaConfig}>
  <App />