@reservamos/browser-analytics 1.1.7 → 1.1.8-alpha.0

package/src/track.test.ts

@@ -1,8 +1,9 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import botDetectionRelayService from '@/services/botDetectionRelay';
 import fingerprintService from '@/services/fingerprint';
 import mixpanelService from '@/services/mixpanel';
-import { trackEvent } from './track';
+import validator from '@/services/validator';
+import { trackEvent, trackEventError, tryTrackEvent } from './track';
 
 vi.mock('@/services/botDetectionRelay', () => ({
   default: {
@@ -14,6 +15,7 @@ vi.mock('@/services/botDetectionRelay', () => ({
 vi.mock('@/services/fingerprint', () => ({
   default: {
     getFingerprint: vi.fn(),
+    getCachedFingerprint: vi.fn(),
     identifyVisitor: vi.fn(),
     isFingerprintReady: vi.fn(),
   },
@@ -42,115 +44,357 @@ vi.mock('@/services/validator', () => ({
 
 describe('trackEvent Bot Detection relay', () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    vi.resetAllMocks();
     vi.mocked(mixpanelService.isReady).mockReturnValue(true);
     vi.mocked(mixpanelService.getMixpanelDistinctId).mockReturnValue(
       'distinct-123',
     );
-    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(true);
-  });
-
-  it('uses a fresh identification and relays a configured event', async () => {
     vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
+    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(true);
+    vi.mocked(fingerprintService.getCachedFingerprint).mockReturnValue(
+      'cached-visitor',
+    );
     vi.mocked(fingerprintService.identifyVisitor).mockResolvedValue({
-      visitorId: 'visitor-123',
-      requestId: 'request-123',
-      visitorFound: true,
+      visitorId: 'fresh-visitor',
+      requestId: 'fresh-request',
       confidenceScore: 0.99,
       cacheHit: false,
     });
+    vi.mocked(botDetectionRelayService.relay).mockResolvedValue(undefined);
+  });
 
-    await trackEvent('Payment Attempt', { 'Payment Type': 'credit_card' });
+  describe.each(['Search', 'Payment Attempt', 'Purchase Attempt'])(
+    '%s',
+    (eventName) => {
+      it.each(['cached-visitor', null])(
+        'submits with cached identity %s before starting identification',
+        async (cachedVisitor) => {
+          vi.mocked(fingerprintService.getCachedFingerprint).mockReturnValue(
+            cachedVisitor,
+          );
+          vi.mocked(fingerprintService.identifyVisitor).mockImplementation(
+            () => {
+              expect(mixpanelService.track).toHaveBeenCalledWith(eventName, {
+                'User Fingerprint': cachedVisitor ?? '',
+                'Payment Type': 'credit_card',
+                'Checkout Source': 'web',
+              });
+              return Promise.resolve({
+                visitorId: 'fresh-visitor',
+                requestId: 'fresh-request',
+                confidenceScore: 0.99,
+                cacheHit: false,
+              });
+            },
+          );
 
-    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
-    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
-    expect(mixpanelService.track).toHaveBeenCalledWith('Payment Attempt', {
-      'User Fingerprint': 'visitor-123',
-      'Payment Type': 'credit_card',
-    });
-    expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
-      requestId: 'request-123',
-      visitorId: 'visitor-123',
-      distinctId: 'distinct-123',
-      eventName: 'Payment Attempt',
+          const completion = trackEvent(
+            eventName,
+            { 'Payment Type': 'credit_card' },
+            { 'Checkout Source': 'web' },
+          );
+
+          expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+          await completion;
+          expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
+          expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
+          await vi.waitFor(() =>
+            expect(botDetectionRelayService.relay).toHaveBeenCalledOnce(),
+          );
+          expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+            requestId: 'fresh-request',
+            visitorId: 'fresh-visitor',
+            distinctId: 'distinct-123',
+            eventName,
+          });
+        },
+      );
+
+      it('completes tracking while fresh identification is still pending', async () => {
+        let resolveIdentification!: (
+          value: Awaited<ReturnType<typeof fingerprintService.identifyVisitor>>,
+        ) => void;
+        vi.mocked(fingerprintService.identifyVisitor).mockReturnValue(
+          new Promise((resolve) => {
+            resolveIdentification = resolve;
+          }),
+        );
+        const onComplete = vi.fn();
+        const completion = trackEvent(eventName, {}).then(onComplete);
+        // A pending remote operation must not delay submission or completion.
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(mixpanelService.track).toHaveBeenCalledWith(eventName, {
+          'User Fingerprint': 'cached-visitor',
+        });
+        expect(onComplete).toHaveBeenCalledOnce();
+        expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+        resolveIdentification({
+          visitorId: 'late-visitor',
+          requestId: 'late-request',
+          confidenceScore: 0.99,
+          cacheHit: false,
+        });
+        await completion;
+        await vi.waitFor(() =>
+          expect(botDetectionRelayService.relay).toHaveBeenCalledOnce(),
+        );
+        expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+          requestId: 'late-request',
+          visitorId: 'late-visitor',
+          distinctId: 'distinct-123',
+          eventName,
+        });
+        expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+      });
+
+      it('preserves the original event when identification rejects', async () => {
+        vi.mocked(fingerprintService.identifyVisitor).mockRejectedValue(
+          new Error('Identification failed'),
+        );
+        await trackEvent(eventName, {});
+        expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+        expect(mixpanelService.track).toHaveBeenCalledWith(eventName, {
+          'User Fingerprint': 'cached-visitor',
+        });
+        expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+      });
+
+      it('submits without identity if reading the cache throws', async () => {
+        vi.mocked(fingerprintService.getCachedFingerprint).mockImplementation(
+          () => {
+            throw new Error('Cache unavailable');
+          },
+        );
+        await trackEvent(eventName, {});
+        expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+        expect(mixpanelService.track).toHaveBeenCalledWith(eventName, {
+          'User Fingerprint': '',
+        });
+      });
+
+      it('submits without starting identification when the agent is unavailable', async () => {
+        vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(false);
+        await trackEvent(eventName, {});
+        expect(mixpanelService.track).toHaveBeenCalledWith(eventName, {
+          'User Fingerprint': 'cached-visitor',
+        });
+        expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
+        expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+      });
+    },
+  );
+
+  it('relays the original distinct ID even if identity changes while identification is pending', async () => {
+    let resolveIdentification!: (
+      value: Awaited<ReturnType<typeof fingerprintService.identifyVisitor>>,
+    ) => void;
+    vi.mocked(fingerprintService.identifyVisitor).mockReturnValue(
+      new Promise((resolve) => {
+        resolveIdentification = resolve;
+      }),
+    );
+    await trackEvent('Payment Attempt', {});
+    vi.mocked(mixpanelService.getMixpanelDistinctId).mockReturnValue(
+      'new-distinct-id',
+    );
+    resolveIdentification({
+      visitorId: 'fresh-visitor',
+      requestId: 'fresh-request',
+      confidenceScore: 0.99,
+      cacheHit: false,
     });
+    await vi.waitFor(() =>
+      expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+        requestId: 'fresh-request',
+        visitorId: 'fresh-visitor',
+        distinctId: 'distinct-123',
+        eventName: 'Payment Attempt',
+      }),
+    );
   });
 
-  it('reports a failed fresh identification without tracking or relaying the configured event', async () => {
-    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
-    vi.mocked(fingerprintService.identifyVisitor).mockRejectedValue(
-      new Error('Fingerprint identification failed'),
+  it('contains an unexpected background relay rejection', async () => {
+    vi.mocked(botDetectionRelayService.relay).mockRejectedValue(
+      new Error('Relay failed'),
     );
-    const eventProperties = { 'Payment Type': 'credit_card' };
+    await trackEvent('Payment Attempt', {});
+    await Promise.resolve();
+    expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+    expect(mixpanelService.track).toHaveBeenCalledWith('Payment Attempt', {
+      'User Fingerprint': 'cached-visitor',
+    });
+  });
 
-    await trackEvent('Payment Attempt', eventProperties);
+  it('retains tracking error behavior for invalid event properties', async () => {
+    vi.mocked(validator.parseEventProps).mockImplementationOnce(() => {
+      throw new Error('Invalid event properties');
+    });
+    await trackEvent('Payment Attempt', {});
+    expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
+    expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+    expect(mixpanelService.track).toHaveBeenCalledWith(
+      'Track Event Error',
+      expect.objectContaining({ 'Failed Event Name': 'Payment Attempt' }),
+    );
+  });
 
-    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
-    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
+  it('does not start bot detection when submitting the original event throws', async () => {
+    vi.mocked(mixpanelService.track).mockImplementationOnce(() => {
+      throw new Error('Tracking failed');
+    });
+    await trackEvent('Payment Attempt', {});
+    expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
     expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  });
+
+  it('submits View Results with an empty fingerprint if identification rejects', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+    vi.mocked(fingerprintService.getFingerprint).mockRejectedValue(
+      new Error('Fingerprint failed'),
+    );
+    await trackEvent('View Results', { 'Results Count': 2 }, { source: 'web' });
+    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(false);
     expect(mixpanelService.track).toHaveBeenCalledTimes(1);
-    expect(mixpanelService.track).toHaveBeenCalledWith('Track Event Error', {
-      'Failed Event Name': 'Payment Attempt',
-      'Error Message': 'Fingerprint identification failed',
-      'Validation Errors': [],
-      'Event Payload': eventProperties,
+    expect(mixpanelService.track).toHaveBeenCalledWith('View Results', {
+      'User Fingerprint': '',
+      'Results Count': 2,
+      'source': 'web',
     });
   });
 
-  it('preserves existing fingerprint behavior for an unconfigured event', async () => {
+  it('preserves existing fingerprint behavior for events outside bot detection', async () => {
     vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
     vi.mocked(fingerprintService.getFingerprint).mockResolvedValue(
       'cached-visitor',
     );
-
-    await trackEvent('Payment Attempt', { 'Payment Type': 'credit_card' });
-
+    await trackEvent('Seat Change', {});
     expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(true);
+    expect(fingerprintService.getCachedFingerprint).not.toHaveBeenCalled();
     expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
-    expect(mixpanelService.track).toHaveBeenCalledWith('Payment Attempt', {
+    expect(mixpanelService.track).toHaveBeenCalledWith('Seat Change', {
       'User Fingerprint': 'cached-visitor',
-      'Payment Type': 'credit_card',
     });
     expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
   });
+});
 
-  it('uses a fresh identification and relays Search', async () => {
-    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
-    vi.mocked(fingerprintService.identifyVisitor).mockResolvedValue({
-      visitorId: 'visitor-123',
-      requestId: 'search-request-123',
-      visitorFound: true,
-      confidenceScore: 0.99,
-      cacheHit: false,
-    });
+describe('bounded tracking readiness', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.resetAllMocks();
+    vi.mocked(mixpanelService.isReady).mockReturnValue(false);
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+    vi.mocked(fingerprintService.getFingerprint).mockResolvedValue('');
+    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(false);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('submits at the deadline if Mixpanel loaded without a Tracker Ready signal', async () => {
+    const pending = trackEvent('Payment Attempt', { source: 'checkout' });
+    await vi.advanceTimersByTimeAsync(1000);
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    await vi.advanceTimersByTimeAsync(4000);
+    await pending;
+    expect(mixpanelService.track).toHaveBeenCalledWith(
+      'Payment Attempt',
+      expect.objectContaining({ source: 'checkout' }),
+    );
+    expect(console.error).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
 
-    await trackEvent('Search', {});
+  it('holds multiple events until readiness and submits each once', async () => {
+    const remove = vi.spyOn(window, 'removeEventListener');
+    const first = trackEvent('Payment Attempt', { source: 'first' });
+    const second = trackEvent('Purchase Attempt', { source: 'second' });
+    void first.catch(() => undefined);
+    void second.catch(() => undefined);
+    expect(mixpanelService.track).not.toHaveBeenCalled();
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      undefined,
+      undefined,
+    ]);
+    expect(mixpanelService.track).toHaveBeenCalledTimes(2);
+    expect(mixpanelService.track).toHaveBeenCalledWith(
+      'Payment Attempt',
+      expect.objectContaining({ source: 'first' }),
+    );
+    expect(mixpanelService.track).toHaveBeenCalledWith(
+      'Purchase Attempt',
+      expect.objectContaining({ source: 'second' }),
+    );
+    expect(remove).toHaveBeenCalledWith('Tracker Ready', expect.any(Function));
+    expect(vi.getTimerCount()).toBe(0);
+  });
 
-    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
-    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
-    expect(mixpanelService.track).toHaveBeenCalledWith('Search', {
-      'User Fingerprint': 'visitor-123',
+  it('expires cleanly, reports a controlled diagnostic, and ignores late readiness', async () => {
+    const remove = vi.spyOn(window, 'removeEventListener');
+    const pending = trackEvent('Payment Attempt', {
+      secret: 'private-payload',
     });
-    expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
-      requestId: 'search-request-123',
-      visitorId: 'visitor-123',
-      distinctId: 'distinct-123',
-      eventName: 'Search',
+    void pending.catch(() => undefined);
+    await vi.advanceTimersByTimeAsync(5000);
+    await expect(pending).resolves.toBeUndefined();
+    expect(console.error).toHaveBeenCalledWith('Tracking diagnostic', {
+      eventName: 'Payment Attempt',
+      stage: 'readiness',
+      reason: 'timeout',
     });
+    expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+      'private-payload',
+    );
+    expect(remove).toHaveBeenCalledWith('Tracker Ready', expect.any(Function));
+    expect(vi.getTimerCount()).toBe(0);
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await Promise.resolve();
+    expect(mixpanelService.track).not.toHaveBeenCalled();
   });
 
-  it('tracks Search without a relay when Fingerprint is not ready', async () => {
-    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
-    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(false);
-    vi.mocked(fingerprintService.getFingerprint).mockResolvedValue('');
+  it('does not execute when a readiness signal arrives before Mixpanel is ready', async () => {
+    const callback = vi.fn().mockResolvedValue(undefined);
+    const pending = tryTrackEvent(callback);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await Promise.resolve();
+    expect(callback).not.toHaveBeenCalled();
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await pending;
+    expect(callback).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
 
-    await trackEvent('Search', {});
+  it('consumes callback rejection after readiness', async () => {
+    const callback = vi
+      .fn()
+      .mockRejectedValue(new Error('private-callback-error'));
+    const pending = tryTrackEvent(callback);
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await expect(pending).resolves.toBeUndefined();
+    expect(callback).toHaveBeenCalledOnce();
+    expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+      'private-callback-error',
+    );
+    expect(vi.getTimerCount()).toBe(0);
+  });
 
-    expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
-    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(false);
-    expect(mixpanelService.track).toHaveBeenCalledWith('Search', {
-      'User Fingerprint': '',
-    });
-    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  it('expires a queued tracking diagnostic without creating another listener', async () => {
+    const add = vi.spyOn(window, 'addEventListener');
+    trackEventError('Payment Attempt', new Error('failed'), {});
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(
+      add.mock.calls.filter(([name]) => name === 'Tracker Ready'),
+    ).toHaveLength(1);
+    expect(vi.getTimerCount()).toBe(0);
   });
 });

package/src/track.ts

@@ -89,12 +89,42 @@ export function trackEventError(
   });
 }
 
-export async function tryTrackEvent(trackEventCallback: () => Promise<void>) {
-  if (mixpanelService.isReady()) {
+/** Waits for one bounded attempt, then consumes callback failures. */
+export async function tryTrackEvent(
+  trackEventCallback: () => Promise<void>,
+  eventName = 'Track Event Error',
+): Promise<void> {
+  if (!mixpanelService.isReady()) {
+    const ready = await new Promise<boolean>((resolve) => {
+      const finish = (isReady: boolean) => {
+        clearTimeout(timer);
+        window.removeEventListener('Tracker Ready', onReady);
+        resolve(isReady);
+      };
+      const onReady = () => {
+        if (mixpanelService.isReady()) finish(true);
+      };
+      const timer = setTimeout(() => finish(mixpanelService.isReady()), 5000);
+      window.addEventListener('Tracker Ready', onReady);
+      onReady();
+    });
+    if (!ready) {
+      console.error('Tracking diagnostic', {
+        eventName,
+        stage: 'readiness',
+        reason: 'timeout',
+      });
+      return;
+    }
+  }
+
+  try {
     await trackEventCallback();
-  } else {
-    window.addEventListener('Tracker Ready', async () => {
-      await trackEventCallback();
+  } catch {
+    console.error('Tracking diagnostic', {
+      eventName,
+      stage: 'submission',
+      reason: 'failed',
     });
   }
 }
@@ -105,33 +135,50 @@ export async function tryTrackEvent(trackEventCallback: () => Promise<void>) {
  * @param {string} eventName - The name of the event to track.
  * @param {object} eventProperties - The properties of the event to track.
  * @param {EventMetadata} meta - Additional metadata to include in the event.
- * @throws {Error} Throws an error if Mixpanel or Fingerprint is not ready.
+ * Waits up to five seconds for Mixpanel readiness before event submission.
+ * Optional fingerprint failure does not discard an otherwise valid event.
  */
-export async function trackEvent(
+export function trackEvent(
   eventName: string,
   eventProperties: object,
   meta: EventMetadata = {},
 ): Promise<void> {
-  if (!mixpanelService.isReady()) {
-    throw new Error('Mixpanel is not initialized.');
-  }
+  return tryTrackEvent(
+    () => submitEvent(eventName, eventProperties, meta),
+    eventName,
+  );
+}
 
+async function submitEvent(
+  eventName: string,
+  eventProperties: object,
+  meta: EventMetadata,
+): Promise<void> {
   try {
     validator.parseEventProps(eventName, eventProperties);
     // Call the Mixpanel service to store the distinct ID in the cache
     const distinctId = mixpanelService.getMixpanelDistinctId();
     const botDetectionEnabled =
       botDetectionRelayService.isEnabledFor(eventName);
-    let fingerprint: string;
-    let fingerprintRequestId: string | undefined;
+    let fingerprint = '';
 
-    if (botDetectionEnabled && fingerprintService.isFingerprintReady()) {
-      const identification = await fingerprintService.identifyVisitor(true);
-      fingerprint = identification.visitorId;
-      fingerprintRequestId = identification.requestId;
+    if (botDetectionEnabled) {
+      try {
+        fingerprint = fingerprintService.getCachedFingerprint() ?? '';
+      } catch (error) {
+        console.error('Error reading cached fingerprint:', error);
+      }
     } else {
       const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
-      fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+      try {
+        fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+      } catch {
+        console.error('Tracking diagnostic', {
+          eventName,
+          stage: 'fingerprint',
+          reason: 'failed',
+        });
+      }
     }
     const defaultCoordinates: Record<string, string | number> = {};
     const coordinates = geolocationService.getCoordinates();
@@ -159,13 +206,8 @@ export async function trackEvent(
 
     mixpanelService.track(eventName, properties);
 
-    if (fingerprintRequestId) {
-      void botDetectionRelayService.relay({
-        requestId: fingerprintRequestId,
-        visitorId: fingerprint,
-        ...(distinctId && { distinctId }),
-        eventName,
-      });
+    if (botDetectionEnabled) {
+      void identifyAndRelayFingerprint(eventName, distinctId);
     }
   } catch (error) {
     console.error(`Error tracking event '${eventName}':`, error);
@@ -173,6 +215,28 @@ export async function trackEvent(
   }
 }
 
+/** Identifies and relays only after the original event has been submitted. */
+async function identifyAndRelayFingerprint(
+  eventName: string,
+  distinctId: string | null,
+): Promise<void> {
+  try {
+    if (!fingerprintService.isFingerprintReady()) return;
+
+    const identification = await fingerprintService.identifyVisitor(true);
+    if (!identification.requestId) return;
+
+    await botDetectionRelayService.relay({
+      requestId: identification.requestId,
+      visitorId: identification.visitorId,
+      ...(distinctId && { distinctId }),
+      eventName,
+    });
+  } catch (error) {
+    console.error(`Error running Bot Detection for '${eventName}':`, error);
+  }
+}
+
 /**
  * Extracts UTM and other tracking parameters from the current URL that match predefined fields.
  * @returns {Record<string, string>} An object containing matched tracking parameters.