matomo-tracker-for-react 1.0.0

package/src/MatomoTracker.ts

@@ -0,0 +1,415 @@
+import { TRACK_TYPES } from "./constants";
+import {
+  AddEcommerceItemParams,
+  RemoveEcommerceItemParams,
+  CustomDimension,
+  SetEcommerceViewParams,
+  TrackEcommerceOrderParams,
+  TrackEventParams,
+  TrackLinkParams,
+  TrackPageViewParams,
+  TrackParams,
+  TrackSiteSearchParams,
+  UserOptions,
+} from "./tracker-types";
+
+declare global {
+  interface Window {
+    _paq?: Array<any[]>;
+  }
+}
+
+class MatomoTracker {
+  private mutationObserver?: MutationObserver;
+  private isInitialized = false;
+
+  constructor(userOptions: UserOptions) {
+    if (typeof window === "undefined") {
+      // Don't run in SSR or non-browser environments
+      return;
+    }
+    if (!userOptions.urlBase) {
+      throw new Error("Matomo urlBase is required.");
+    }
+    if (userOptions.siteId === undefined || userOptions.siteId === null) {
+      throw new Error("Matomo siteId is required.");
+    }
+
+    this.initialize(userOptions);
+  }
+
+  private initialize({
+    urlBase,
+    siteId,
+    userId,
+    trackerUrl,
+    srcUrl,
+    disabled = false,
+    heartBeat,
+    linkTracking = true,
+    configurations = {},
+  }: UserOptions) {
+    if (disabled) {
+      // If disabled, make all tracking calls no-ops by not initializing _paq or the script
+      this.pushInstruction = (..._args: any[]): MatomoTracker => this; // No-op
+      // Make other methods no-op as well
+      const noOp = () => {};
+      this.trackEvent = noOp as any;
+      this.trackPageView = noOp as any;
+      this.trackSiteSearch = noOp as any;
+      this.trackLink = noOp as any;
+      // ... and so on for all public methods
+      return;
+    }
+
+    const normalizedUrlBase = urlBase.endsWith("/") ? urlBase : `${urlBase}/`;
+
+    window._paq = window._paq || [];
+
+    // Prevent re-initialization if _paq already has Matomo commands beyond simple presence
+    if (
+      this.isInitialized ||
+      (window._paq.length > 0 &&
+        window._paq.some((cmd) => cmd[0] === "setTrackerUrl"))
+    ) {
+      // If siteId or userId needs to be updated on an existing instance:
+      if (siteId) this.pushInstruction("setSiteId", siteId);
+      if (userId) this.pushInstruction("setUserId", userId);
+      // Potentially re-apply other configurations if needed, or assume they are sticky
+      this.isInitialized = true;
+      return;
+    }
+
+    this.pushInstruction(
+      "setTrackerUrl",
+      trackerUrl ?? `${normalizedUrlBase}matomo.php`
+    );
+    this.pushInstruction("setSiteId", siteId);
+
+    if (userId) {
+      this.pushInstruction("setUserId", userId);
+    }
+
+    Object.entries(configurations).forEach(([name, instructions]) => {
+      if (name === "disableCookies" && typeof instructions === "boolean") {
+        this.pushInstruction("disableCookies"); // Matomo's disableCookies takes no arguments if called this way
+      } else if (instructions instanceof Array) {
+        this.pushInstruction(name, ...instructions);
+      } else {
+        this.pushInstruction(name, instructions);
+      }
+    });
+
+    if (!heartBeat || (heartBeat && heartBeat.active)) {
+      this.enableHeartBeatTimer((heartBeat && heartBeat.seconds) ?? 15);
+    }
+
+    this.enableLinkTracking(linkTracking);
+
+    const doc = document;
+    const scriptElement = doc.createElement("script");
+    const scripts = doc.getElementsByTagName("script")[0];
+
+    scriptElement.type = "text/javascript";
+    scriptElement.async = true;
+    scriptElement.defer = true;
+    scriptElement.src = srcUrl || `${normalizedUrlBase}matomo.js`;
+
+    if (scripts && scripts.parentNode) {
+      scripts.parentNode.insertBefore(scriptElement, scripts);
+    }
+    this.isInitialized = true;
+  }
+
+  enableHeartBeatTimer(seconds: number): void {
+    this.pushInstruction("enableHeartBeatTimer", seconds);
+  }
+
+  enableLinkTracking(active: boolean): void {
+    this.pushInstruction("enableLinkTracking", active);
+  }
+
+  private trackEventsForElements(elements: HTMLElement[]) {
+    if (elements.length) {
+      elements.forEach((element) => {
+        element.addEventListener("click", () => {
+          const { matomoCategory, matomoAction, matomoName, matomoValue } =
+            element.dataset;
+          if (matomoCategory && matomoAction) {
+            this.trackEvent({
+              category: matomoCategory,
+              action: matomoAction,
+              name: matomoName,
+              value: matomoValue ? Number(matomoValue) : undefined,
+            });
+          } else {
+            throw new Error(
+              `Error: data-matomo-category and data-matomo-action are required.`
+            );
+          }
+        });
+      });
+    }
+  }
+
+  // Tracks events based on data attributes
+  trackEvents(): void {
+    if (typeof window === "undefined" || !document) return;
+
+    const matchString = '[data-matomo-event="click"]';
+    let firstTime = false;
+    if (!this.mutationObserver) {
+      firstTime = true;
+      this.mutationObserver = new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+          mutation.addedNodes.forEach((node) => {
+            // only track HTML elements
+            if (!(node instanceof HTMLElement)) return;
+
+            // check the inserted element for being a code snippet
+            if (node.matches(matchString)) {
+              this.trackEventsForElements([node]);
+            }
+
+            const elements = Array.from(
+              node.querySelectorAll<HTMLElement>(matchString)
+            );
+            this.trackEventsForElements(elements);
+          });
+        });
+      });
+    }
+    this.mutationObserver.observe(document, { childList: true, subtree: true });
+
+    // Now track all already existing elements
+    if (firstTime) {
+      const elements = Array.from(
+        document.querySelectorAll<HTMLElement>(matchString)
+      );
+      this.trackEventsForElements(elements);
+    }
+  }
+
+  stopObserving(): void {
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+    }
+  }
+
+  // Tracks events
+  // https://matomo.org/docs/event-tracking/#tracking-events
+  trackEvent({
+    category,
+    action,
+    name,
+    value,
+    ...otherParams
+  }: TrackEventParams): void {
+    if (category && action) {
+      this.track({
+        data: [TRACK_TYPES.TRACK_EVENT, category, action, name, value],
+        ...otherParams,
+      });
+    } else {
+      throw new Error(`Error: category and action are required.`);
+    }
+  }
+
+  // Tracks site search
+  // https://developer.matomo.org/guides/tracking-javascript-guide#internal-search-tracking
+  trackSiteSearch({
+    keyword,
+    category,
+    count,
+    ...otherParams
+  }: TrackSiteSearchParams): void {
+    if (keyword) {
+      this.track({
+        data: [TRACK_TYPES.TRACK_SEARCH, keyword, category, count],
+        ...otherParams,
+      });
+    } else {
+      throw new Error(`Error: keyword is required.`);
+    }
+  }
+
+  // Tracks outgoing links to other sites and downloads
+  // https://developer.matomo.org/guides/tracking-javascript-guide#enabling-download-outlink-tracking
+  trackLink({
+    href,
+    linkType = "link",
+    customDimensions,
+  }: TrackLinkParams): void {
+    if (
+      customDimensions &&
+      Array.isArray(customDimensions) &&
+      customDimensions.length
+    ) {
+      customDimensions.forEach((customDimension: CustomDimension) =>
+        this.pushInstruction(
+          "setCustomDimension",
+          customDimension.id,
+          customDimension.value
+        )
+      );
+    }
+    this.pushInstruction(TRACK_TYPES.TRACK_LINK, href, linkType);
+  }
+
+  // Tracks page views
+  // https://developer.matomo.org/guides/spa-tracking#tracking-a-new-page-view
+  trackPageView(params?: TrackPageViewParams): void {
+    this.track({ data: [TRACK_TYPES.TRACK_VIEW], ...params });
+  }
+
+  // Adds a product to an Ecommerce order to be tracked via trackEcommerceOrder.
+  // https://matomo.org/docs/ecommerce-analytics
+  // https://matomo.org/docs/ecommerce-analytics/#1-addecommerceitemproductsku-productname-productcategory-price-quantity
+  addEcommerceItem({
+    sku,
+    productName,
+    productCategory,
+    productPrice = 0.0,
+    productQuantity = 1,
+  }: AddEcommerceItemParams): void {
+    this.pushInstruction(
+      "addEcommerceItem",
+      sku,
+      productName,
+      productCategory,
+      productPrice,
+      productQuantity
+    );
+  }
+
+  // Removes a product from an Ecommerce order to be tracked via trackEcommerceOrder.
+  // https://matomo.org/docs/ecommerce-analytics
+  removeEcommerceItem({ sku }: RemoveEcommerceItemParams): void {
+    this.pushInstruction("removeEcommerceItem", sku);
+  }
+
+  // Removes all products from an Ecommerce order to be tracked via trackEcommerceOrder.
+  // https://matomo.org/docs/ecommerce-analytics
+  clearEcommerceCart(): void {
+    this.pushInstruction("clearEcommerceCart");
+  }
+
+  // Tracks an Ecommerce order containing items added via addEcommerceItem.
+  // https://matomo.org/docs/ecommerce-analytics/#2-trackecommerceorderorderid-revenue-subtotal-tax-shipping-discount
+  trackEcommerceOrder({
+    orderId,
+    orderRevenue,
+    orderSubTotal,
+    taxAmount,
+    shippingAmount,
+    discountOffered = false,
+  }: TrackEcommerceOrderParams): void {
+    this.track({
+      data: [
+        TRACK_TYPES.TRACK_ECOMMERCE_ORDER,
+        orderId,
+        orderRevenue,
+        orderSubTotal,
+        taxAmount,
+        shippingAmount,
+        discountOffered,
+      ],
+    });
+  }
+
+  // Tracks updates to an Ecommerce Cart before an actual purchase.
+  // This will replace currently tracked information of the cart. Always include all items of the updated cart!
+  // https://matomo.org/docs/ecommerce-analytics/#example-tracking-an-ecommerce-cart-update-containing-two-products
+  trackEcommerceCartUpdate(amount: number): void {
+    this.pushInstruction(TRACK_TYPES.TRACK_ECOMMERCE_CART_UPDATE, amount);
+  }
+
+  // Marks the next page view as an Ecommerce product page.
+  // https://matomo.org/docs/ecommerce-analytics/#example-tracking-a-product-page-view
+  setEcommerceView({
+    sku,
+    productName,
+    productCategory,
+    productPrice,
+  }: SetEcommerceViewParams): void {
+    this.pushInstruction(
+      "setEcommerceView",
+      sku,
+      productName,
+      productCategory,
+      productPrice
+    );
+  }
+
+  // Marks the next tracked page view as an Ecommerce category page.
+  // https://matomo.org/docs/ecommerce-analytics/#example-tracking-a-category-page-view
+  setEcommerceCategoryView(productCategory: string): void {
+    this.setEcommerceView({ productCategory, productName: false, sku: false });
+  }
+
+  // Sends the tracked page/view/search to Matomo
+  private track({
+    data = [],
+    documentTitle, // Changed: use passed documentTitle or fallback to window.document.title later
+    href,
+    customDimensions = false,
+  }: TrackParams): void {
+    if (typeof window === "undefined") return;
+
+    if (data.length) {
+      if (
+        customDimensions &&
+        Array.isArray(customDimensions) &&
+        customDimensions.length
+      ) {
+        customDimensions.forEach(
+          (
+            customDimension: CustomDimension // Corrected type
+          ) =>
+            this.pushInstruction(
+              "setCustomDimension",
+              customDimension.id,
+              customDimension.value
+            )
+        );
+      }
+
+      this.pushInstruction("setCustomUrl", href ?? window.location.href);
+      // Use provided documentTitle, fallback to actual document.title only if not provided
+      this.pushInstruction(
+        "setDocumentTitle",
+        documentTitle ?? window.document.title
+      );
+      this.pushInstruction(...(data as [string, ...any[]]));
+    }
+  }
+
+  /**
+   * Pushes an instruction to Matomo for execution, this is equivalent to pushing entries into the `_paq` array.
+   *
+   * For example:
+   *
+   * ```ts
+   * pushInstruction('setDocumentTitle', document.title)
+   * ```
+   * Is the equivalent of:
+   *
+   * ```ts
+   * _paq.push(['setDocumentTitle', document.title]);
+   * ```
+   *
+   * @param name The name of the instruction to be executed.
+   * @param args The arguments to pass along with the instruction.
+   */
+  pushInstruction(name: string, ...args: any[]): MatomoTracker {
+    if (typeof window !== "undefined" && window._paq) {
+      window._paq.push([name, ...args]);
+    } else if (typeof window !== "undefined" && name === "setTrackerUrl") {
+      // Allow setting up _paq if it's the first instruction (like setTrackerUrl)
+      window._paq = [[name, ...args]];
+    }
+    return this;
+  }
+}
+
+export default MatomoTracker;

package/src/constants.ts

@@ -0,0 +1,12 @@
+// eslint-disable-next-line import/prefer-default-export
+export const TRACK_TYPES = {
+  TRACK_EVENT: "trackEvent",
+  TRACK_LINK: "trackLink",
+  TRACK_SEARCH: "trackSiteSearch",
+  TRACK_VIEW: "trackPageView",
+  TRACK_ECOMMERCE_ORDER: "trackEcommerceOrder",
+  TRACK_ECOMMERCE_CART_UPDATE: "trackEcommerceCartUpdate",
+  // Add other Matomo instructions if needed, e.g., for goals
+  TRACK_GOAL: "trackGoal",
+  SET_USER_ID: "setUserId",
+};

package/src/index.ts

@@ -0,0 +1,20 @@
+export { default as MatomoProvider } from "./MatomoProvider";
+export { default as useMatomo } from "./useMatomo";
+export { default as MatomoContext } from "./MatomoContext"; // Optional: if users need direct context access
+
+// Export types for consumers
+export * from "./types"; // Exports React-specific types and re-exports tracker-types
+// Explicitly export core tracker types if not fully covered by ./types
+export type {
+  CustomDimension,
+  UserOptions, // This is the core UserOptions, MatomoProviderProps is different
+  TrackPageViewParams, // Core type
+  TrackEventParams, // Core type
+  TrackLinkParams, // Core type
+  TrackSiteSearchParams, // Core type, though not directly used by simplified hook
+  TrackEcommerceOrderParams, // Core type
+  AddEcommerceItemParams, // Core type
+  RemoveEcommerceItemParams, // Core type
+  SetEcommerceViewParams, // Core type
+  TrackGoalParams, // Core type
+} from "./tracker-types";

package/src/tracker-types.ts

@@ -0,0 +1,89 @@
+export interface CustomDimension {
+  id: number;
+  value: string;
+}
+
+export interface UserOptions {
+  urlBase: string;
+  siteId: number; // Matomo site ID is typically a number
+  userId?: string;
+  trackerUrl?: string;
+  srcUrl?: string;
+  disabled?: boolean;
+  heartBeat?: {
+    active: boolean;
+    seconds?: number;
+  };
+  linkTracking?: boolean;
+  configurations?: {
+    [key: string]: any;
+  };
+}
+
+export interface TrackPageViewParams {
+  documentTitle?: string;
+  href?: string | Location;
+  customDimensions?: boolean | CustomDimension[];
+}
+
+export interface TrackParams extends TrackPageViewParams {
+  data: any[];
+}
+
+export interface TrackEventParams {
+  category: string;
+  action: string;
+  name?: string;
+  value?: number;
+  // Allow other params to be passed through for flexibility with customDimensions, etc.
+  documentTitle?: string;
+  href?: string | Location;
+  customDimensions?: boolean | CustomDimension[];
+}
+
+export interface TrackLinkParams {
+  href: string;
+  linkType?: "download" | "link";
+  // Allow other params
+  customDimensions?: boolean | CustomDimension[];
+}
+
+export interface TrackSiteSearchParams extends TrackPageViewParams {
+  keyword: string;
+  category?: string;
+  count?: number;
+}
+
+export interface TrackEcommerceOrderParams {
+  orderId: string;
+  orderRevenue: number;
+  orderSubTotal?: number;
+  taxAmount?: number;
+  shippingAmount?: number;
+  discountOffered?: boolean;
+}
+
+export interface AddEcommerceItemParams {
+  sku: string;
+  productName?: string;
+  productCategory?: string;
+  productPrice?: number;
+  productQuantity?: number;
+}
+
+export interface RemoveEcommerceItemParams {
+  sku: string;
+}
+
+export interface SetEcommerceViewParams {
+  sku: string | boolean;
+  productName?: string | boolean;
+  productCategory?: string;
+  productPrice?: number;
+}
+
+// Added for useMatomo hook
+export interface TrackGoalParams {
+  goalId: number | string;
+  revenue?: number;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import React from "react";
+
+// Re-export tracker types for convenience if needed by consumers of the React package
+export * from "./tracker-types";
+
+export interface MatomoProviderProps {
+  children: React.ReactNode;
+  urlBase: string;
+  siteId: string | number;
+  trackCookies?: boolean;
+  disabled?: boolean;
+}
+
+export interface MatomoInstance {
+  trackEvent: (
+    category: string,
+    action: string,
+    name?: string,
+    value?: number
+  ) => void;
+  trackPageView: (customTitle?: string) => void;
+  trackGoal: (goalId: number | string, revenue?: number) => void;
+  setUserId: (userId: string) => void;
+  trackLink: (url: string, linkType: "link" | "download") => void;
+  pushInstruction: (instruction: any[]) => void;
+}
+
+// For useMatomo hook return type
+export type UseMatomo = MatomoInstance;

package/src/useMatomo.ts

@@ -0,0 +1,55 @@
+import { useContext, useCallback } from "react";
+import MatomoContext from "./MatomoContext";
+import { UseMatomo } from "./types";
+
+function useMatomo(): UseMatomo {
+  const context = useContext(MatomoContext);
+
+  if (context === null) {
+    throw new Error("useMatomo must be used within a MatomoProvider");
+  }
+
+  const trackPageView = useCallback(
+    (customTitle?: string) => context.trackPageView(customTitle),
+    [context]
+  );
+
+  const trackEvent = useCallback(
+    (category: string, action: string, name?: string, value?: number) =>
+      context.trackEvent(category, action, name, value),
+    [context]
+  );
+
+  const trackGoal = useCallback(
+    (goalId: number | string, revenue?: number) =>
+      context.trackGoal(goalId, revenue),
+    [context]
+  );
+
+  const setUserId = useCallback(
+    (userId: string) => context.setUserId(userId),
+    [context]
+  );
+
+  const trackLink = useCallback(
+    (url: string, linkType: "link" | "download") =>
+      context.trackLink(url, linkType),
+    [context]
+  );
+
+  const pushInstruction = useCallback(
+    (instruction: any[]) => context.pushInstruction(instruction),
+    [context]
+  );
+
+  return {
+    trackEvent,
+    trackPageView,
+    trackGoal,
+    setUserId,
+    trackLink,
+    pushInstruction,
+  };
+}
+
+export default useMatomo;