@technoapple/ga4 1.0.4 → 1.1.0

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 = [];
+    }
+}

package/src/plugins/impression-tracker.ts

@@ -0,0 +1,230 @@
+import { GA4Plugin, SendFunction, ImpressionTrackerOptions, ImpressionElementConfig } from '../types/plugins';
+import { domReady } from '../helpers/dom-ready';
+
+interface NormalizedItem {
+    id: string;
+    threshold: number;
+    trackFirstImpressionOnly: boolean;
+}
+
+/**
+ * Tracks when specific DOM elements become visible in the viewport
+ * using `IntersectionObserver`.
+ *
+ * Useful for tracking ad impressions, CTA visibility, or any
+ * element that enters the user's viewport.
+ */
+export class ImpressionTracker implements GA4Plugin {
+    private send: SendFunction;
+    private rootMargin: string;
+    private attributePrefix: string;
+    private eventName: string;
+    private hitFilter?: ImpressionTrackerOptions['hitFilter'];
+    private items: NormalizedItem[] = [];
+    private elementMap: Record<string, Element | null> = {};
+    private thresholdMap: Record<number, IntersectionObserver> = {};
+    private mutationObserver: MutationObserver | null = null;
+    private impressedIds: Set<string> = new Set();
+    private supported: boolean;
+
+    constructor(send: SendFunction, options?: ImpressionTrackerOptions) {
+        this.supported =
+            typeof IntersectionObserver !== 'undefined' &&
+            typeof MutationObserver !== 'undefined';
+
+        this.send = send;
+        this.rootMargin = options?.rootMargin ?? '0px';
+        this.attributePrefix = options?.attributePrefix ?? 'data-ga4-';
+        this.eventName = options?.eventName ?? 'element_impression';
+        this.hitFilter = options?.hitFilter;
+
+        if (!this.supported) return;
+
+        this.handleIntersectionChanges = this.handleIntersectionChanges.bind(this);
+        this.handleDomMutations = this.handleDomMutations.bind(this);
+
+        const elements = options?.elements;
+        domReady(() => {
+            if (elements && elements.length > 0) {
+                this.observeElements(elements);
+            }
+        });
+    }
+
+    observeElements(elements: Array<string | ImpressionElementConfig>): void {
+        if (!this.supported) return;
+
+        const newItems = this.normalizeElements(elements);
+        this.items = this.items.concat(newItems);
+
+        newItems.forEach((item) => {
+            const observer = this.getObserverForThreshold(item.threshold);
+            const element = document.getElementById(item.id);
+            this.elementMap[item.id] = element;
+            if (element) {
+                observer.observe(element);
+            }
+        });
+
+        if (!this.mutationObserver && document.body) {
+            this.mutationObserver = new MutationObserver(this.handleDomMutations);
+            this.mutationObserver.observe(document.body, {
+                childList: true,
+                subtree: true,
+            });
+        }
+    }
+
+    unobserveElements(elements: Array<string | ImpressionElementConfig>): void {
+        if (!this.supported) return;
+
+        const idsToRemove = new Set(
+            elements.map((el) => (typeof el === 'string' ? el : el.id))
+        );
+
+        this.items = this.items.filter((item) => {
+            if (idsToRemove.has(item.id)) {
+                const element = this.elementMap[item.id];
+                if (element && this.thresholdMap[item.threshold]) {
+                    this.thresholdMap[item.threshold].unobserve(element);
+                }
+                delete this.elementMap[item.id];
+                return false;
+            }
+            return true;
+        });
+
+        if (this.items.length === 0) {
+            this.disconnectAll();
+        }
+    }
+
+    unobserveAllElements(): void {
+        this.disconnectAll();
+        this.items = [];
+        this.elementMap = {};
+    }
+
+    private normalizeElements(elements: Array<string | ImpressionElementConfig>): NormalizedItem[] {
+        return elements.map((el) => {
+            if (typeof el === 'string') {
+                return { id: el, threshold: 0, trackFirstImpressionOnly: true };
+            }
+            return {
+                id: el.id,
+                threshold: el.threshold ?? 0,
+                trackFirstImpressionOnly: el.trackFirstImpressionOnly ?? true,
+            };
+        });
+    }
+
+    private getObserverForThreshold(threshold: number): IntersectionObserver {
+        if (!this.thresholdMap[threshold]) {
+            this.thresholdMap[threshold] = new IntersectionObserver(
+                this.handleIntersectionChanges,
+                {
+                    rootMargin: this.rootMargin,
+                    threshold: [threshold],
+                }
+            );
+        }
+        return this.thresholdMap[threshold];
+    }
+
+    private handleIntersectionChanges(entries: IntersectionObserverEntry[]): void {
+        entries.forEach((entry) => {
+            if (!entry.isIntersecting) return;
+
+            const id = entry.target.id;
+            if (!id) return;
+
+            const item = this.items.find((i) => i.id === id);
+            if (!item) return;
+            if (item.trackFirstImpressionOnly && this.impressedIds.has(id)) return;
+
+            this.impressedIds.add(id);
+
+            const prefix = this.attributePrefix;
+            const attrParams: Record<string, unknown> = {};
+            for (let i = 0; i < entry.target.attributes.length; i++) {
+                const attr = entry.target.attributes[i];
+                if (attr.name.startsWith(prefix)) {
+                    const key = attr.name.slice(prefix.length).replace(/-/g, '_');
+                    attrParams[key] = attr.value;
+                }
+            }
+
+            let params: Record<string, unknown> = {
+                element_id: id,
+                ...attrParams,
+            };
+
+            if (this.hitFilter) {
+                const filtered = this.hitFilter(params, entry.target);
+                if (filtered === null) return;
+                params = filtered;
+            }
+
+            this.send(this.eventName, params);
+
+            if (item.trackFirstImpressionOnly && this.thresholdMap[item.threshold]) {
+                this.thresholdMap[item.threshold].unobserve(entry.target);
+            }
+        });
+    }
+
+    private handleDomMutations(mutations: MutationRecord[]): void {
+        mutations.forEach((mutation) => {
+            mutation.addedNodes.forEach((node) => {
+                if (node.nodeType !== Node.ELEMENT_NODE) return;
+                this.walkNodeTree(node as Element, (id) => {
+                    const element = document.getElementById(id);
+                    if (element) {
+                        this.elementMap[id] = element;
+                        const item = this.items.find((i) => i.id === id);
+                        if (item && this.thresholdMap[item.threshold]) {
+                            this.thresholdMap[item.threshold].observe(element);
+                        }
+                    }
+                });
+            });
+
+            mutation.removedNodes.forEach((node) => {
+                if (node.nodeType !== Node.ELEMENT_NODE) return;
+                this.walkNodeTree(node as Element, (id) => {
+                    const element = this.elementMap[id];
+                    if (element) {
+                        const item = this.items.find((i) => i.id === id);
+                        if (item && this.thresholdMap[item.threshold]) {
+                            this.thresholdMap[item.threshold].unobserve(element);
+                        }
+                    }
+                    this.elementMap[id] = null;
+                });
+            });
+        });
+    }
+
+    private walkNodeTree(node: Element, callback: (id: string) => void): void {
+        if (node.id && node.id in this.elementMap) {
+            callback(node.id);
+        }
+        for (let i = 0; i < node.children.length; i++) {
+            this.walkNodeTree(node.children[i], callback);
+        }
+    }
+
+    private disconnectAll(): void {
+        Object.values(this.thresholdMap).forEach((observer) => observer.disconnect());
+        this.thresholdMap = {};
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+            this.mutationObserver = null;
+        }
+    }
+
+    remove(): void {
+        this.unobserveAllElements();
+        this.impressedIds.clear();
+    }
+}

package/src/plugins/index.ts

@@ -0,0 +1,8 @@
+export { EventTracker } from './event-tracker';
+export { OutboundLinkTracker } from './outbound-link-tracker';
+export { OutboundFormTracker } from './outbound-form-tracker';
+export { PageVisibilityTracker } from './page-visibility-tracker';
+export { UrlChangeTracker } from './url-change-tracker';
+export { ImpressionTracker } from './impression-tracker';
+export { CleanUrlTracker } from './clean-url-tracker';
+export { MediaQueryTracker } from './media-query-tracker';

package/src/plugins/media-query-tracker.ts

@@ -0,0 +1,116 @@
+import { GA4Plugin, SendFunction, MediaQueryTrackerOptions, MediaQueryDefinition } from '../types/plugins';
+import { debounce, DebouncedFunction } from '../helpers/debounce';
+
+interface TrackedQuery {
+    definition: MediaQueryDefinition;
+    mql: MediaQueryList;
+    currentValue: string;
+    listener: ((event: MediaQueryListEvent) => void);
+}
+
+function getMatchingValue(definition: MediaQueryDefinition): string {
+    for (const item of definition.items) {
+        if (window.matchMedia(item.media).matches) {
+            return item.name;
+        }
+    }
+    return '(not set)';
+}
+
+/**
+ * Tracks CSS media query breakpoint matching and changes.
+ *
+ * Fires an event whenever the active breakpoint changes
+ * (e.g. from "mobile" to "desktop"), debounced to avoid
+ * rapid-fire events during window resizing.
+ */
+export class MediaQueryTracker implements GA4Plugin {
+    private send: SendFunction;
+    private changeTimeout: number;
+    private eventName: string;
+    private changeTemplate?: MediaQueryTrackerOptions['changeTemplate'];
+    private hitFilter?: MediaQueryTrackerOptions['hitFilter'];
+    private trackedQueries: TrackedQuery[] = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private debouncedHandlers: DebouncedFunction<any>[] = [];
+
+    constructor(send: SendFunction, options?: MediaQueryTrackerOptions) {
+        this.send = send;
+        this.changeTimeout = options?.changeTimeout ?? 1000;
+        this.eventName = options?.eventName ?? 'media_query_change';
+        this.changeTemplate = options?.changeTemplate;
+        this.hitFilter = options?.hitFilter;
+
+        if (typeof window.matchMedia !== 'function') return;
+
+        const definitions = options?.definitions ?? [];
+        definitions.forEach((definition) => {
+            this.trackDefinition(definition);
+        });
+    }
+
+    private trackDefinition(definition: MediaQueryDefinition): void {
+        const initialValue = getMatchingValue(definition);
+
+        definition.items.forEach((item) => {
+            const mql = window.matchMedia(item.media);
+
+            const debouncedHandler = debounce(() => {
+                const newValue = getMatchingValue(definition);
+                const tracked = this.trackedQueries.find(
+                    (tq) => tq.definition === definition
+                );
+                if (!tracked || newValue === tracked.currentValue) return;
+
+                const oldValue = tracked.currentValue;
+                tracked.currentValue = newValue;
+
+                const changeLabel = this.changeTemplate
+                    ? this.changeTemplate(oldValue, newValue)
+                    : `${oldValue} => ${newValue}`;
+
+                let params: Record<string, unknown> = {
+                    media_query_name: definition.name,
+                    media_query_value: newValue,
+                    media_query_change: changeLabel,
+                };
+
+                if (this.hitFilter) {
+                    const filtered = this.hitFilter(params);
+                    if (filtered === null) return;
+                    params = filtered;
+                }
+
+                this.send(this.eventName, params);
+            }, this.changeTimeout);
+
+            this.debouncedHandlers.push(debouncedHandler);
+
+            const listener = () => {
+                debouncedHandler();
+            };
+
+            if (typeof mql.addEventListener === 'function') {
+                mql.addEventListener('change', listener);
+            }
+
+            this.trackedQueries.push({
+                definition,
+                mql,
+                currentValue: initialValue,
+                listener,
+            });
+        });
+    }
+
+    remove(): void {
+        this.trackedQueries.forEach(({ mql, listener }) => {
+            if (typeof mql.removeEventListener === 'function') {
+                mql.removeEventListener('change', listener);
+            }
+        });
+        this.debouncedHandlers.forEach((d) => d.cancel());
+        this.trackedQueries = [];
+        this.debouncedHandlers = [];
+    }
+}

package/src/plugins/outbound-form-tracker.ts

@@ -0,0 +1,65 @@
+import { GA4Plugin, SendFunction, OutboundFormTrackerOptions } from '../types/plugins';
+import { delegate, DelegateHandle } from '../helpers/delegate';
+import { parseUrl } from '../helpers/parse-url';
+
+function defaultShouldTrack(form: HTMLFormElement, parseUrlFn: (url: string) => { hostname: string; protocol: string; href: string }): boolean {
+    const action = form.action;
+    if (!action) return false;
+    const url = parseUrlFn(action);
+    return url.hostname !== location.hostname && url.protocol.startsWith('http');
+}
+
+/**
+ * Automatically tracks form submissions to external domains.
+ *
+ * Sends an event when a form's `action` attribute points to a
+ * different hostname than the current page.
+ */
+export class OutboundFormTracker implements GA4Plugin {
+    private delegateHandle: DelegateHandle;
+    private send: SendFunction;
+    private eventName: string;
+    private shouldTrackOutboundForm: NonNullable<OutboundFormTrackerOptions['shouldTrackOutboundForm']>;
+    private hitFilter?: OutboundFormTrackerOptions['hitFilter'];
+
+    constructor(send: SendFunction, options?: OutboundFormTrackerOptions) {
+        this.send = send;
+        this.eventName = options?.eventName ?? 'outbound_form_submit';
+        this.shouldTrackOutboundForm = options?.shouldTrackOutboundForm ?? defaultShouldTrack;
+        this.hitFilter = options?.hitFilter;
+
+        const formSelector = options?.formSelector ?? 'form';
+
+        this.delegateHandle = delegate(
+            document,
+            'submit',
+            formSelector,
+            (event, element) => this.handleFormSubmit(event, element as HTMLFormElement),
+            { composed: true, useCapture: true }
+        );
+    }
+
+    private handleFormSubmit(event: Event, form: HTMLFormElement): void {
+        if (!this.shouldTrackOutboundForm(form, parseUrl)) return;
+
+        const url = parseUrl(form.action);
+
+        let params: Record<string, unknown> = {
+            form_action: url.href,
+            form_domain: url.hostname,
+            outbound: true,
+        };
+
+        if (this.hitFilter) {
+            const filtered = this.hitFilter(params, form, event);
+            if (filtered === null) return;
+            params = filtered;
+        }
+
+        this.send(this.eventName, params);
+    }
+
+    remove(): void {
+        this.delegateHandle.destroy();
+    }
+}

package/src/plugins/outbound-link-tracker.ts

@@ -0,0 +1,72 @@
+import { GA4Plugin, SendFunction, OutboundLinkTrackerOptions } from '../types/plugins';
+import { delegate, DelegateHandle } from '../helpers/delegate';
+import { parseUrl } from '../helpers/parse-url';
+
+function defaultShouldTrack(link: Element, parseUrlFn: (url: string) => { hostname: string; protocol: string; href: string }): boolean {
+    const href = link.getAttribute('href') || link.getAttribute('xlink:href');
+    if (!href) return false;
+    const url = parseUrlFn(href);
+    return url.hostname !== location.hostname && url.protocol.startsWith('http');
+}
+
+/**
+ * Automatically tracks clicks on outbound links (links to external domains).
+ *
+ * Sends an event when a user clicks a link whose hostname differs
+ * from the current page's hostname.
+ */
+export class OutboundLinkTracker implements GA4Plugin {
+    private delegates: DelegateHandle[] = [];
+    private send: SendFunction;
+    private events: string[];
+    private linkSelector: string;
+    private eventName: string;
+    private shouldTrackOutboundLink: NonNullable<OutboundLinkTrackerOptions['shouldTrackOutboundLink']>;
+    private hitFilter?: OutboundLinkTrackerOptions['hitFilter'];
+
+    constructor(send: SendFunction, options?: OutboundLinkTrackerOptions) {
+        this.send = send;
+        this.events = options?.events ?? ['click'];
+        this.linkSelector = options?.linkSelector ?? 'a, area';
+        this.eventName = options?.eventName ?? 'outbound_link_click';
+        this.shouldTrackOutboundLink = options?.shouldTrackOutboundLink ?? defaultShouldTrack;
+        this.hitFilter = options?.hitFilter;
+
+        this.events.forEach((eventType) => {
+            const handle = delegate(
+                document,
+                eventType,
+                this.linkSelector,
+                (event, element) => this.handleLinkInteraction(event, element),
+                { composed: true, useCapture: true }
+            );
+            this.delegates.push(handle);
+        });
+    }
+
+    private handleLinkInteraction(event: Event, element: Element): void {
+        if (!this.shouldTrackOutboundLink(element, parseUrl)) return;
+
+        const href = element.getAttribute('href') || element.getAttribute('xlink:href') || '';
+        const url = parseUrl(href);
+
+        let params: Record<string, unknown> = {
+            link_url: url.href,
+            link_domain: url.hostname,
+            outbound: true,
+        };
+
+        if (this.hitFilter) {
+            const filtered = this.hitFilter(params, element, event);
+            if (filtered === null) return;
+            params = filtered;
+        }
+
+        this.send(this.eventName, params);
+    }
+
+    remove(): void {
+        this.delegates.forEach((d) => d.destroy());
+        this.delegates = [];
+    }
+}

package/src/plugins/page-visibility-tracker.ts

@@ -0,0 +1,104 @@
+import { GA4Plugin, SendFunction, PageVisibilityTrackerOptions } from '../types/plugins';
+import { isSessionExpired, updateSessionTimestamp } from '../helpers/session';
+
+/**
+ * Tracks how long a page is in the visible state vs. hidden (background tab).
+ *
+ * Sends a `page_visibility` event each time the visibility state changes,
+ * reporting how long the page was in the previous state.
+ * Optionally sends a new `page_view` when the page becomes visible
+ * again after the session timeout has elapsed.
+ */
+export class PageVisibilityTracker implements GA4Plugin {
+    private send: SendFunction;
+    private sendInitialPageview: boolean;
+    private sessionTimeout: number;
+    private eventName: string;
+    private hitFilter?: PageVisibilityTrackerOptions['hitFilter'];
+    private lastChangeTime: number;
+    private isVisible: boolean;
+    private boundVisibilityChange: () => void;
+    private boundBeforeUnload: () => void;
+
+    constructor(send: SendFunction, options?: PageVisibilityTrackerOptions) {
+        this.send = send;
+        this.sendInitialPageview = options?.sendInitialPageview ?? false;
+        this.sessionTimeout = options?.sessionTimeout ?? 30;
+        this.eventName = options?.eventName ?? 'page_visibility';
+        this.hitFilter = options?.hitFilter;
+
+        this.lastChangeTime = Date.now();
+        this.isVisible = document.visibilityState === 'visible';
+
+        this.boundVisibilityChange = this.onVisibilityChange.bind(this);
+        this.boundBeforeUnload = this.onBeforeUnload.bind(this);
+
+        document.addEventListener('visibilitychange', this.boundVisibilityChange);
+        window.addEventListener('beforeunload', this.boundBeforeUnload);
+
+        updateSessionTimestamp('pageVisibility');
+
+        if (this.sendInitialPageview && this.isVisible) {
+            this.send('page_view', {
+                page_path: location.pathname,
+                page_location: location.href,
+                page_title: document.title,
+            });
+        }
+    }
+
+    private onVisibilityChange(): void {
+        const now = Date.now();
+        const duration = now - this.lastChangeTime;
+        const previousState = this.isVisible ? 'visible' : 'hidden';
+
+        let params: Record<string, unknown> = {
+            visibility_state: previousState,
+            visibility_duration: duration,
+            page_path: location.pathname,
+        };
+
+        if (this.hitFilter) {
+            const filtered = this.hitFilter(params);
+            if (filtered === null) {
+                this.lastChangeTime = now;
+                this.isVisible = document.visibilityState === 'visible';
+                return;
+            }
+            params = filtered;
+        }
+
+        this.send(this.eventName, params);
+
+        // If page becomes visible again, check session expiry
+        if (document.visibilityState === 'visible' && !this.isVisible) {
+            if (isSessionExpired('pageVisibility', this.sessionTimeout)) {
+                this.send('page_view', {
+                    page_path: location.pathname,
+                    page_location: location.href,
+                    page_title: document.title,
+                });
+            }
+            updateSessionTimestamp('pageVisibility');
+        }
+
+        this.lastChangeTime = now;
+        this.isVisible = document.visibilityState === 'visible';
+    }
+
+    private onBeforeUnload(): void {
+        if (this.isVisible) {
+            const duration = Date.now() - this.lastChangeTime;
+            this.send(this.eventName, {
+                visibility_state: 'visible',
+                visibility_duration: duration,
+                page_path: location.pathname,
+            });
+        }
+    }
+
+    remove(): void {
+        document.removeEventListener('visibilitychange', this.boundVisibilityChange);
+        window.removeEventListener('beforeunload', this.boundBeforeUnload);
+    }
+}