Medusa Google Analytics Logic

This package provides a unified interface for Google Tag Manager (GTM) and Meta Conversions API (CAPI) tracking.

Installation

npm install medusa-google-analytics-logic

Local Development

For local testing, use npm link in this directory and then npm link medusa-google-analytics-logic in your consumer project.

Usage

1. Initialization

Initialize GTM in your application's entry point (e.g., main.tsx or _app.tsx):

import { initGTM } from 'medusa-google-analytics-logic';

initGTM('GTM-XXXXXXX');

2. Tracking Hook

Use the useTracking hook to track events:

import { useTracking } from 'medusa-google-analytics-logic';

const MyComponent = () => {
    const { trackLead, trackCustomEvent } = useTracking();

    const handleSignup = async () => {
        await trackLead('Signup Form');
    };

    const handlePurchase = async () => {
        await trackCustomEvent('Purchase', {
            value: 99.99,
            currency: 'USD'
        });
    };

    return (
        <div>
            <button onClick={handleSignup}>Track Lead</button>
            <button onClick={handlePurchase}>Track Purchase</button>
        </div>
    );
};

3. Cookie Consent Hook

Manage user consent with useCookieConsent:

import { useCookieConsent } from 'medusa-google-analytics-logic';

const CookieBanner = () => {
    const { consent, acceptConsent, rejectConsent, isFirstVisit } = useCookieConsent();

    if (!isFirstVisit) return null;

    return (
        <div className="banner">
            <p>We use cookies for analytics and ads.</p>
            <button onClick={acceptConsent}>Accept</button>
            <button onClick={rejectConsent}>Decline</button>
        </div>
    );
};

4. Meta CAPI

The useTracking hook automatically sends events to Meta Conversions API via a /meta/event endpoint. Ensure your server handles this endpoint and includes the necessary Meta Pixel ID and Access Token.

API Reference

Services

• initGTM(id: string): Initializes Google Tag Manager.
• trackEvent(eventName: string, params?: object): Pushes a GTM event to the dataLayer.
• sendCAPIEvent(event: string | CAPIEvent, extraData?: object): Sends a request to the CAPI proxy.

Hooks

• useTracking(): Returns trackLead and trackCustomEvent.
• useCookieConsent(): Manages local storage consent and GTM consent mode updates.