@technoapple/ga4 1.0.3 → 1.1.0

package/src/ga4/ga4.ts

@@ -1,41 +1,70 @@
-import { ga4Option } from "./ga4option";
-import { DataLayerObject } from "../types/dataLayer";
-import { KeyValueParams, gtag } from "../types/gtag";
-import {} from '../types/global';
-
-class ga4 {
-
-    private static instance: ga4;
-
-    private constructor() {
-    }
-
-    public init(option:ga4Option){
-        window.dataLayer = window.dataLayer || Array<DataLayerObject>;
-        window.gtag = window.gtag || function() {
-            window.dataLayer.push(arguments);
-        }
-        window.gtag('js', new Date());
-        window.gtag('config', option.targetId);
-    }
-
-    public static getInstance():ga4 {
-        if (!ga4.instance) {
-            ga4.instance = new ga4();
-        }               
-        return ga4.instance;
-    }
-
-    public send(eventName:string, eventParameters: KeyValueParams ): boolean {
-
-        window.gtag('event', eventName, eventParameters);
-
-        return true;
-    }
-
-    get gtag() : gtag {
-        return window.gtag;
-    }
-}
-
+import { ga4Option } from "./ga4option";
+import { DataLayerObject } from "../types/dataLayer";
+import { KeyValueParams, gtag } from "../types/gtag";
+import { GA4Plugin, SendFunction } from "../types/plugins";
+import {} from '../types/global';
+
+class ga4 {
+
+    private static instance: ga4;
+    private _plugins: GA4Plugin[] = [];
+
+    private constructor() {
+    }
+
+    public init(option:ga4Option){
+        window.dataLayer = window.dataLayer || Array<DataLayerObject>;
+        window.gtag = window.gtag || function() {
+            window.dataLayer.push(arguments);
+        }
+        window.gtag('js', new Date());
+        window.gtag('config', option.targetId);
+    }
+
+    public static getInstance():ga4 {
+        if (!ga4.instance) {
+            ga4.instance = new ga4();
+        }               
+        return ga4.instance;
+    }
+
+    public send(eventName:string, eventParameters: KeyValueParams ): boolean {
+
+        window.gtag('event', eventName, eventParameters);
+
+        return true;
+    }
+
+    /**
+     * Register a plugin with the GA4 instance.
+     * @param PluginClass The plugin class constructor
+     * @param options Plugin-specific configuration options
+     * @returns The plugin instance (call `.remove()` to unregister)
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public use<T extends GA4Plugin>(
+        PluginClass: new (send: SendFunction, options?: any) => T,
+        options?: any
+    ): T {
+        const send: SendFunction = (eventName: string, params: Record<string, unknown>) => {
+            window.gtag('event', eventName, params as KeyValueParams);
+        };
+        const plugin = new PluginClass(send, options);
+        this._plugins.push(plugin);
+        return plugin;
+    }
+
+    /**
+     * Remove all registered plugins and clean up their listeners.
+     */
+    public removeAll(): void {
+        this._plugins.forEach(p => p.remove());
+        this._plugins = [];
+    }
+
+    get gtag() : gtag {
+        return window.gtag;
+    }
+}
+
 export {ga4};

package/src/ga4/ga4option.ts

@@ -1,5 +1,5 @@
-interface ga4Option {
-    targetId:string;
-}
-
+interface ga4Option {
+    targetId:string;
+}
+
 export {ga4Option};

package/src/ga4/index.ts

@@ -1,5 +1,5 @@
-import {ga4} from './ga4';
-
-const ga = ga4.getInstance();
-
+import {ga4} from './ga4';
+
+const ga = ga4.getInstance();
+
 export {ga};

package/src/helpers/debounce.ts

@@ -0,0 +1,28 @@
+export interface DebouncedFunction<T extends (...args: never[]) => void> {
+    (...args: Parameters<T>): void;
+    cancel(): void;
+}
+
+export function debounce<T extends (...args: never[]) => void>(
+    fn: T,
+    delay: number
+): DebouncedFunction<T> {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const debounced = function (this: unknown, ...args: Parameters<T>) {
+        if (timer !== null) clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            fn.apply(this, args);
+        }, delay);
+    } as DebouncedFunction<T>;
+
+    debounced.cancel = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    };
+
+    return debounced;
+}

package/src/helpers/delegate.ts

@@ -0,0 +1,51 @@
+export interface DelegateHandle {
+    destroy(): void;
+}
+
+export interface DelegateOptions {
+    composed?: boolean;
+    useCapture?: boolean;
+}
+
+export function delegate(
+    target: EventTarget,
+    eventType: string,
+    selector: string,
+    handler: (event: Event, element: Element) => void,
+    options?: DelegateOptions
+): DelegateHandle {
+    const useCapture = options?.useCapture ?? false;
+
+    const listener = (event: Event) => {
+        let element: Element | null = event.target as Element | null;
+
+        // Handle composed events (shadow DOM)
+        if (options?.composed && typeof event.composedPath === 'function') {
+            const path = event.composedPath();
+            for (const node of path) {
+                if (node === target) break;
+                if (node instanceof Element && node.matches(selector)) {
+                    handler(event, node);
+                    return;
+                }
+            }
+            return;
+        }
+
+        while (element && element !== target) {
+            if (element.matches(selector)) {
+                handler(event, element);
+                return;
+            }
+            element = element.parentElement;
+        }
+    };
+
+    target.addEventListener(eventType, listener, useCapture);
+
+    return {
+        destroy() {
+            target.removeEventListener(eventType, listener, useCapture);
+        },
+    };
+}

package/src/helpers/dom-ready.ts

@@ -0,0 +1,7 @@
+export function domReady(callback: () => void): void {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', callback, { once: true });
+    } else {
+        callback();
+    }
+}

package/src/helpers/parse-url.ts

@@ -0,0 +1,37 @@
+export interface ParsedUrl {
+    href: string;
+    protocol: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    origin: string;
+}
+
+export function parseUrl(url: string): ParsedUrl {
+    try {
+        const parsed = new URL(url, location.href);
+        return {
+            href: parsed.href,
+            protocol: parsed.protocol,
+            hostname: parsed.hostname,
+            port: parsed.port,
+            pathname: parsed.pathname,
+            search: parsed.search,
+            hash: parsed.hash,
+            origin: parsed.origin,
+        };
+    } catch {
+        return {
+            href: url,
+            protocol: '',
+            hostname: '',
+            port: '',
+            pathname: url,
+            search: '',
+            hash: '',
+            origin: '',
+        };
+    }
+}

package/src/helpers/session.ts

@@ -0,0 +1,39 @@
+const SESSION_KEY_PREFIX = 'ga4_session_';
+
+export function isSessionExpired(key: string, timeoutMinutes: number): boolean {
+    try {
+        const stored = sessionStorage.getItem(SESSION_KEY_PREFIX + key);
+        if (!stored) return true;
+        const timestamp = parseInt(stored, 10);
+        if (isNaN(timestamp)) return true;
+        return (Date.now() - timestamp) > timeoutMinutes * 60 * 1000;
+    } catch {
+        return true;
+    }
+}
+
+export function updateSessionTimestamp(key: string): void {
+    try {
+        sessionStorage.setItem(SESSION_KEY_PREFIX + key, String(Date.now()));
+    } catch {
+        // sessionStorage may be unavailable or full
+    }
+}
+
+export function getSessionValue<T>(key: string): T | null {
+    try {
+        const stored = sessionStorage.getItem(SESSION_KEY_PREFIX + key);
+        if (stored === null) return null;
+        return JSON.parse(stored) as T;
+    } catch {
+        return null;
+    }
+}
+
+export function setSessionValue(key: string, value: unknown): void {
+    try {
+        sessionStorage.setItem(SESSION_KEY_PREFIX + key, JSON.stringify(value));
+    } catch {
+        // sessionStorage may be unavailable or full
+    }
+}

package/src/index.ts

@@ -1,7 +1,34 @@
-import {ga} from './ga4/index';
-import {get} from './dataLayer';
-
-const dataLayerHelper = { get };
-const ga4 = ga;
-
-export {ga4, dataLayerHelper};
+import {ga} from './ga4/index';
+import {get} from './dataLayer';
+
+const dataLayerHelper = { get };
+const ga4 = ga;
+
+export {ga4, dataLayerHelper};
+
+// Plugin exports
+export { EventTracker } from './plugins/event-tracker';
+export { OutboundLinkTracker } from './plugins/outbound-link-tracker';
+export { OutboundFormTracker } from './plugins/outbound-form-tracker';
+export { PageVisibilityTracker } from './plugins/page-visibility-tracker';
+export { UrlChangeTracker } from './plugins/url-change-tracker';
+export { ImpressionTracker } from './plugins/impression-tracker';
+export { CleanUrlTracker } from './plugins/clean-url-tracker';
+export { MediaQueryTracker } from './plugins/media-query-tracker';
+
+// Type exports
+export type {
+    GA4Plugin,
+    SendFunction,
+    EventTrackerOptions,
+    OutboundLinkTrackerOptions,
+    OutboundFormTrackerOptions,
+    PageVisibilityTrackerOptions,
+    UrlChangeTrackerOptions,
+    ImpressionTrackerOptions,
+    ImpressionElementConfig,
+    CleanUrlTrackerOptions,
+    MediaQueryTrackerOptions,
+    MediaQueryDefinition,
+    MediaQueryDefinitionItem,
+} from './types/plugins';

package/src/plugins/clean-url-tracker.ts

@@ -0,0 +1,112 @@
+import { GA4Plugin, SendFunction, CleanUrlTrackerOptions } from '../types/plugins';
+
+/**
+ * Normalizes URLs before they are sent with `page_view` events.
+ *
+ * Intercepts `gtag()` calls for `config` and `page_view` events
+ * and cleans the `page_location` and `page_path` parameters
+ * (strip query params, normalize trailing slashes, apply custom filters).
+ */
+export class CleanUrlTracker implements GA4Plugin {
+    private opts: CleanUrlTrackerOptions;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    private originalGtag: Function | null = null;
+
+    constructor(_send: SendFunction, options?: CleanUrlTrackerOptions) {
+        this.opts = {
+            stripQuery: options?.stripQuery ?? false,
+            queryParamsAllowlist: options?.queryParamsAllowlist,
+            queryParamsDenylist: options?.queryParamsDenylist,
+            trailingSlash: options?.trailingSlash,
+            urlFilter: options?.urlFilter,
+        };
+
+        if (typeof window !== 'undefined' && window.gtag) {
+            this.originalGtag = window.gtag;
+            const self = this;
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (window as any).gtag = function () {
+                // eslint-disable-next-line prefer-rest-params
+                const args = Array.prototype.slice.call(arguments);
+
+                if (args.length >= 3 && typeof args[2] === 'object' && args[2] !== null) {
+                    const isPageView = args[0] === 'event' && args[1] === 'page_view';
+                    const isConfig = args[0] === 'config';
+
+                    if (isPageView || isConfig) {
+                        args[2] = self.cleanParams({ ...args[2] });
+                    }
+                }
+
+                return self.originalGtag!.apply(window, args);
+            };
+        }
+    }
+
+    private cleanParams(params: Record<string, unknown>): Record<string, unknown> {
+        if (typeof params.page_location === 'string') {
+            params.page_location = this.cleanUrl(params.page_location);
+        }
+        if (typeof params.page_path === 'string') {
+            params.page_path = this.cleanPath(params.page_path);
+        }
+        return params;
+    }
+
+    cleanUrl(url: string): string {
+        try {
+            const u = new URL(url);
+            u.pathname = this.cleanPath(u.pathname);
+
+            if (this.opts.stripQuery) {
+                if (this.opts.queryParamsAllowlist && this.opts.queryParamsAllowlist.length > 0) {
+                    const allowed = new URLSearchParams();
+                    this.opts.queryParamsAllowlist.forEach((param) => {
+                        if (u.searchParams.has(param)) {
+                            allowed.set(param, u.searchParams.get(param)!);
+                        }
+                    });
+                    u.search = allowed.toString() ? '?' + allowed.toString() : '';
+                } else {
+                    u.search = '';
+                }
+            } else if (this.opts.queryParamsDenylist && this.opts.queryParamsDenylist.length > 0) {
+                this.opts.queryParamsDenylist.forEach((param) => {
+                    u.searchParams.delete(param);
+                });
+                u.search = u.searchParams.toString() ? '?' + u.searchParams.toString() : '';
+            }
+
+            let result = u.toString();
+            if (this.opts.urlFilter) {
+                result = this.opts.urlFilter(result);
+            }
+            return result;
+        } catch {
+            return url;
+        }
+    }
+
+    cleanPath(path: string): string {
+        let result = path;
+
+        if (this.opts.trailingSlash === 'remove') {
+            result = result.length > 1 ? result.replace(/\/+$/, '') : result;
+        } else if (this.opts.trailingSlash === 'add') {
+            if (!result.endsWith('/') && !result.split('/').pop()?.includes('.')) {
+                result += '/';
+            }
+        }
+
+        return result;
+    }
+
+    remove(): void {
+        if (this.originalGtag) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (window as any).gtag = this.originalGtag;
+            this.originalGtag = null;
+        }
+    }
+}

package/src/plugins/event-tracker.ts

@@ -0,0 +1,90 @@
+import { GA4Plugin, SendFunction, EventTrackerOptions } from '../types/plugins';
+import { delegate, DelegateHandle } from '../helpers/delegate';
+
+function kebabToSnake(str: string): string {
+    return str.replace(/-/g, '_');
+}
+
+function getAttributeParams(element: Element, prefix: string): Record<string, unknown> {
+    const params: Record<string, unknown> = {};
+    const reservedSuffixes = ['on', 'event-name'];
+
+    for (let i = 0; i < element.attributes.length; i++) {
+        const attr = element.attributes[i];
+        if (!attr.name.startsWith(prefix)) continue;
+
+        const suffix = attr.name.slice(prefix.length);
+        if (reservedSuffixes.includes(suffix)) continue;
+
+        params[kebabToSnake(suffix)] = attr.value;
+    }
+
+    return params;
+}
+
+/**
+ * Declarative event tracking via HTML `data-ga4-*` attributes.
+ *
+ * Listens for DOM events on elements with `data-ga4-on` attributes
+ * and sends GA4 events based on attribute values.
+ *
+ * @example
+ * ```html
+ * <button
+ *   data-ga4-on="click"
+ *   data-ga4-event-name="video_play"
+ *   data-ga4-video-title="My Video">
+ *   Play
+ * </button>
+ * ```
+ */
+export class EventTracker implements GA4Plugin {
+    private delegates: DelegateHandle[] = [];
+    private send: SendFunction;
+    private events: string[];
+    private attributePrefix: string;
+    private hitFilter?: EventTrackerOptions['hitFilter'];
+
+    constructor(send: SendFunction, options?: EventTrackerOptions) {
+        this.send = send;
+        this.events = options?.events ?? ['click'];
+        this.attributePrefix = options?.attributePrefix ?? 'data-ga4-';
+        this.hitFilter = options?.hitFilter;
+
+        const selector = `[${this.attributePrefix}on]`;
+
+        this.events.forEach((eventType) => {
+            const handle = delegate(
+                document,
+                eventType,
+                selector,
+                (event, element) => this.handleEvent(event, element),
+                { composed: true, useCapture: true }
+            );
+            this.delegates.push(handle);
+        });
+    }
+
+    private handleEvent(event: Event, element: Element): void {
+        const prefix = this.attributePrefix;
+        const onAttr = element.getAttribute(`${prefix}on`);
+
+        if (onAttr !== event.type) return;
+
+        const eventName = element.getAttribute(`${prefix}event-name`) || event.type;
+        let params = getAttributeParams(element, prefix);
+
+        if (this.hitFilter) {
+            const filtered = this.hitFilter(params, element, event);
+            if (filtered === null) return;
+            params = filtered;
+        }
+
+        this.send(eventName, params);
+    }
+
+    remove(): void {
+        this.delegates.forEach((d) => d.destroy());
+        this.delegates = [];
+    }
+}