@reservamos/browser-analytics 0.1.0

package/src/fingerprint.ts

@@ -0,0 +1,131 @@
+import { FpjsClient } from '@fingerprintjs/fingerprintjs-pro-spa';
+
+declare global {
+  interface Window {
+    fpClient: FpjsClient;
+    fingerprintConfig: {
+      cacheName?: string;
+      cacheTimeInDays?: number;
+    };
+  }
+}
+
+const DEFAULT_CACHE_NAME = 'default_fingerprint_cache';
+const DEFAULT_CACHE_TIME_IN_DAYS = 7;
+
+/**
+ * Calculates the expiration date based on the cache time.
+ * @param {number} cacheTimeInDays - The cache time in days.
+ * @returns {number} - The expiration date in milliseconds since the epoch.
+ */
+const getExpirationDate = (cacheTimeInDays: number): number => {
+  const currentDate = new Date();
+  const futureDate = new Date(
+    currentDate.getTime() + cacheTimeInDays * 24 * 60 * 60 * 1000,
+  );
+  return futureDate.getTime();
+};
+
+/**
+ * Retrieves the cached fingerprint from local storage.
+ * @returns {string | null} - The cached fingerprint or null if it is expired or not found.
+ */
+const getCachedFingerprint = (): string | null => {
+  const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig;
+
+  try {
+    const cachedData = JSON.parse(localStorage.getItem(cacheName) || 'null');
+    if (cachedData && cachedData.expiresAt > Date.now()) {
+      return cachedData.fingerprint;
+    }
+    localStorage.removeItem(cacheName);
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Sets the cached fingerprint in local storage.
+ * @param {string} fingerprint - The fingerprint to be cached.
+ */
+const setCachedFingerprint = (fingerprint: string): void => {
+  const {
+    cacheName = DEFAULT_CACHE_NAME,
+    cacheTimeInDays = DEFAULT_CACHE_TIME_IN_DAYS,
+  } = window.fingerprintConfig;
+
+  const cacheData = {
+    fingerprint,
+    expiresAt: getExpirationDate(cacheTimeInDays),
+  };
+  localStorage.setItem(cacheName, JSON.stringify(cacheData));
+};
+
+/**
+ * Initializes identification service with the provided API key and stores the instance in the window object.
+ * @param {string} apiKey - The API key for Fingerprint.js.
+ * @returns {Promise<void>} A promise that resolves when initialization is complete.
+ * @throws {Error} Throws an error if initialization fails.
+ */
+export async function initFingerprint(apiKey: string): Promise<void> {
+  window.fingerprintConfig = {};
+  window.fpClient = new FpjsClient({
+    loadOptions: {
+      apiKey,
+    },
+  });
+
+  try {
+    await window.fpClient.init();
+  } catch (error) {
+    console.error('Error initializing identification service:', error);
+    throw error;
+  }
+}
+
+/**
+ * Retrieves the fingerprint, first checking the cache and then querying the identification service if not found.
+ * @param {boolean} cacheOnly - Optional flag to retrieve the fingerprint only from the cache.
+ * @returns {Promise<string>} A promise that resolves with the fingerprint.
+ * @throws {Error} Throws an error if retrieval fails.
+ */
+export async function getFingerprint(cacheOnly = false): Promise<string> {
+  if (!window.fingerprintConfig) {
+    throw new Error('Fingerprint configuration is not initialized.');
+  }
+
+  const cachedFingerprint = getCachedFingerprint();
+  if (cachedFingerprint) {
+    return cachedFingerprint;
+  }
+
+  if (cacheOnly) {
+    return '';
+  }
+
+  if (!isFingerprintReady()) {
+    throw new Error('Identification service is not initialized.');
+  }
+
+  try {
+    const fpClient = window.fpClient;
+    const { visitorId: fingerprint } = await fpClient.getVisitorData();
+    setCachedFingerprint(fingerprint);
+    return fingerprint;
+  } catch (error) {
+    console.error('Error retrieving fingerprint:', error);
+    throw error;
+  }
+}
+
+/**
+ * Checks if the identification service is ready.
+ *
+ * This function verifies whether the identification service has been initialized
+ * and is ready to use by checking if the `fpClient` instance exists on the window object.
+ * @returns {boolean} Returns true if the identification service is ready, otherwise false.
+ */
+export function isFingerprintReady(): boolean {
+  return window.fpClient !== undefined;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+import { trackTest } from './events/trackTest';
+import { init } from './init';
+
+export { init } from './init';
+export { trackTest } from './events/trackTest';
+
+const tracker = {
+  init,
+  trackTest,
+};
+
+export default tracker;

package/src/init.ts

@@ -0,0 +1,68 @@
+import { initFingerprint } from './fingerprint'; // Import the new fingerprint initialization function
+import { initMixpanel, isMixpanelReady } from './mixpanel'; // Import Mixpanel functions
+
+import { validateConfig } from './utils/validateConfig';
+
+/**
+ * Configuration object for initializing the tracking library.
+ */
+export interface InitConfig {
+  /**
+   * The Mixpanel token used for authenticating API requests.
+   */
+  mixpanelToken: string;
+
+  /**
+   * Optional flag to enable or disable debug mode.
+   * When set to true, additional debug information will be logged.
+   */
+  debug?: boolean;
+
+  /**
+   * Key for tracking user identities.
+   */
+  identificationKey: string; // Change this line
+}
+
+/**
+ * Dispatches a 'Tracker Ready' event to the window object.
+ *
+ * This function creates and dispatches a custom event named 'Tracker Ready'
+ * to signal that the tracking library has been successfully initialized and is ready to use.
+ */
+function onLoaded() {
+  window.dispatchEvent(new CustomEvent('Tracker Ready'));
+}
+
+/**
+ * Initializes the tracking library with the provided configuration.
+ * @param {InitConfig} config - The configuration object for initialization.
+ * @throws {Error} Throws an error if the configuration is invalid.
+ */
+export async function init(config: InitConfig) {
+  validateConfig(config);
+
+  const { mixpanelToken, debug = false, identificationKey } = config;
+
+  await initMixpanel(mixpanelToken, debug);
+
+  // Only mixpanel is required to be ready to dispatch the 'Tracker Ready' event
+  try {
+    await initFingerprint(identificationKey);
+  } catch (error) {
+    console.error('Error initializing identification service:', error);
+  }
+
+  // Dispatch the 'Tracker Ready' event
+  onLoaded();
+}
+
+/**
+ * Checks if the tracker is ready.
+ *
+ * This function verifies whether the Mixpanel tracker has been initialized and is ready to use.
+ * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
+ */
+export function isTrackerReady(): boolean {
+  return isMixpanelReady();
+}

package/src/mixpanel.ts

@@ -0,0 +1,36 @@
+import mixpanel from 'mixpanel-browser';
+
+declare global {
+  interface Window {
+    mixpanel: typeof mixpanel;
+  }
+}
+
+/**
+ * Initializes Mixpanel with the provided token and debug flag.
+ * @param {string} mixpanelToken - The Mixpanel token used for authenticating API requests.
+ * @param {boolean} debug - Optional flag to enable or disable debug mode.
+ * @returns {Promise<void>} A promise that resolves when Mixpanel is initialized.
+ */
+export function initMixpanel(
+  mixpanelToken: string,
+  debug = false,
+): Promise<void> {
+  return new Promise<void>((resolve) => {
+    mixpanel.init(mixpanelToken, {
+      debug,
+      loaded: () => {
+        window.mixpanel = mixpanel;
+        resolve();
+      },
+    });
+  });
+}
+
+/**
+ * Checks if the Mixpanel tracker is ready.
+ * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
+ */
+export function isMixpanelReady(): boolean {
+  return window.mixpanel !== undefined;
+}

package/src/track.ts

@@ -0,0 +1,43 @@
+import mixpanel from 'mixpanel-browser';
+import { getFingerprint } from './fingerprint';
+import { isMixpanelReady } from './mixpanel';
+
+/**
+ * List of events that trigger the fingerprint to be sent with the event. other eventes will only fetch the cached fingerprint.
+ */
+const FP_TRIGGER_EVENTS = ['Track Test'];
+
+/**
+ * Base function to track events with Mixpanel.
+ * This function adds default properties like User Fingerprint.
+ * @param {string} eventName - The name of the event to track.
+ * @param {object} eventProperties - The properties of the event to track.
+ * @throws {Error} Throws an error if Mixpanel or Fingerprint is not ready.
+ */
+export async function trackEvent(
+  eventName: string,
+  eventProperties: object,
+): Promise<void> {
+  if (!isMixpanelReady()) {
+    throw new Error('Mixpanel is not initialized.');
+  }
+
+  try {
+    const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
+
+    const fingerprint = await getFingerprint(cacheOnly);
+    const defaultProperties = {
+      'User Fingerprint': fingerprint,
+    };
+
+    const properties = {
+      ...defaultProperties,
+      ...eventProperties,
+    };
+
+    mixpanel.track(eventName, properties);
+  } catch (error) {
+    console.error('Error tracking event:', error);
+    throw error;
+  }
+}

package/src/utils/validateConfig.ts

@@ -0,0 +1,16 @@
+import { InitConfig } from '../init';
+
+/**
+ * Validates the initialization configuration for the init function.
+ *
+ * @param {InitConfig} config - The configuration object to validate.
+ * @throws {Error} Throws an error if the configuration is invalid.
+ */
+export function validateConfig(config: InitConfig) {
+  if (!config.mixpanelToken) {
+    throw new Error('mixpanelToken is required');
+  }
+  if (!config.identificationKey) {
+    throw new Error('identificationKey is required'); // Change this line
+  }
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />