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

package/src/services/botDetectionRelay.test.ts

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import configService from '@/services/config';
+import botDetectionRelayService from './botDetectionRelay';
+
+vi.mock('@/services/config', () => ({
+  default: {
+    getCoreAPIConfig: vi.fn(),
+  },
+}));
+
+const payload = {
+  requestId: 'request-123',
+  visitorId: 'visitor-123',
+  distinctId: 'distinct-123',
+  eventName: 'Payment Attempt',
+};
+
+const coreApiConfig = {
+  baseUrl: 'https://data-lake.reservamossaas.com/api',
+  defaultHeaders: {
+    'Authorization': 'Bearer test-token',
+    'Origin': 'https://example.com',
+    'x-app-name': 'reservamos-web',
+  },
+};
+
+describe('botDetectionRelayService', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    vi.mocked(configService.getCoreAPIConfig).mockReturnValue(coreApiConfig);
+  });
+
+  it('enables only the SDK-owned Bot Detection events', () => {
+    expect(botDetectionRelayService.isEnabledFor('Search')).toBe(true);
+    expect(botDetectionRelayService.isEnabledFor('Payment Attempt')).toBe(true);
+    expect(botDetectionRelayService.isEnabledFor('Purchase Attempt')).toBe(
+      true,
+    );
+    expect(botDetectionRelayService.isEnabledFor('View Results')).toBe(false);
+    expect(
+      botDetectionRelayService.isEnabledFor('Purchase Confirmation Viewed'),
+    ).toBe(false);
+  });
+
+  it('posts the payload to the Core API fingerprint path with keepalive', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await botDetectionRelayService.relay(payload);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://data-lake.reservamossaas.com/api/v1/fingerprint/bot-detection',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-app-name': 'reservamos-web',
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+      },
+    );
+  });
+
+  it('omits x-app-name when it is not in the core API config', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+    vi.mocked(configService.getCoreAPIConfig).mockReturnValue({
+      baseUrl: 'https://datalake-api-dev.reservamossaas.com/api',
+      defaultHeaders: {
+        Authorization: 'Bearer test-token',
+        Origin: 'https://example.com',
+      },
+    });
+
+    await botDetectionRelayService.relay(payload);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://datalake-api-dev.reservamossaas.com/api/v1/fingerprint/bot-detection',
+      expect.objectContaining({
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      }),
+    );
+  });
+
+  it('contains rejected requests and reports the failure', async () => {
+    const error = new Error('Network unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(error));
+
+    await expect(
+      botDetectionRelayService.relay(payload),
+    ).resolves.toBeUndefined();
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error relaying Fingerprint identification:',
+      error,
+    );
+
+    consoleError.mockRestore();
+  });
+
+  it('contains non-success responses and reports their status', async () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({ ok: false, status: 503 }),
+    );
+
+    await expect(
+      botDetectionRelayService.relay(payload),
+    ).resolves.toBeUndefined();
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error relaying Fingerprint identification:',
+      expect.objectContaining({
+        message: 'Bot Detection relay failed with status 503',
+      }),
+    );
+
+    consoleError.mockRestore();
+  });
+});

package/src/services/botDetectionRelay.ts

@@ -0,0 +1,64 @@
+import type { BotDetectionRelayPayload } from '@/types/botDetection';
+import configService from '@/services/config';
+
+const BOT_DETECTION_RELAY_PATH = '/v1/fingerprint/bot-detection';
+
+/**
+ * Events that require a fresh Fingerprint identification and Core API relay.
+ * Owned by the SDK so consumers do not choose which events participate.
+ */
+const BOT_DETECTION_EVENTS = [
+  'Search',
+  'Payment Attempt',
+  'Purchase Attempt',
+] as const;
+
+/**
+ * Checks whether an event is eligible for Bot Detection.
+ * @param {string} eventName - Mixpanel event name.
+ * @returns {boolean} Whether the event should obtain and relay a fresh identification.
+ */
+function isEnabledFor(eventName: string): boolean {
+  return (BOT_DETECTION_EVENTS as readonly string[]).includes(eventName);
+}
+
+/**
+ * Relays Fingerprint identification context to Core API.
+ * Failures are contained so they cannot affect an event already submitted to Mixpanel.
+ * @param {BotDetectionRelayPayload} payload - Request correlation data.
+ * @returns {Promise<void>} Resolves after the relay attempt completes.
+ */
+async function relay(payload: BotDetectionRelayPayload): Promise<void> {
+  try {
+    const coreApiConfig = configService.getCoreAPIConfig();
+    const response = await fetch(
+      `${coreApiConfig.baseUrl}${BOT_DETECTION_RELAY_PATH}`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(coreApiConfig.defaultHeaders?.['x-app-name']
+            ? { 'x-app-name': coreApiConfig.defaultHeaders['x-app-name'] }
+            : {}),
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(
+        `Bot Detection relay failed with status ${response.status}`,
+      );
+    }
+  } catch (error) {
+    console.error('Error relaying Fingerprint identification:', error);
+  }
+}
+
+const botDetectionRelayService = {
+  isEnabledFor,
+  relay,
+};
+
+export default botDetectionRelayService;

package/src/services/fingerprint.test.ts

@@ -1,66 +1,279 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import fingerprintService from './fingerprint';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fingerprintService, { getFingerprintForIdentify } from './fingerprint';
 
-const { initMock, getVisitorDataMock } = vi.hoisted(() => ({
-  initMock: vi.fn(),
-  getVisitorDataMock: vi.fn(),
-}));
+const visitorData = {
+  visitorId: 'visitor-123',
+  requestId: 'request-123',
+  visitorFound: true,
+  confidence: { score: 0.99 },
+  cacheHit: false,
+};
+
+const { getVisitorDataMock, initMock, setPeoplePropertiesMock, clientMock } =
+  vi.hoisted(() => ({
+    clientMock: vi.fn(),
+    getVisitorDataMock: vi.fn(),
+    initMock: vi.fn(),
+    setPeoplePropertiesMock: vi.fn(),
+  }));
 
 vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
   FingerprintJSPro: {
     defaultEndpoint: 'https://fpjscdn.net',
     defaultScriptUrlPattern: 'https://fpjscdn.net/agent',
   },
-  FpjsClient: vi.fn().mockImplementation(() => ({
-    init: initMock,
-    getVisitorData: getVisitorDataMock,
-  })),
+  FpjsClient: clientMock,
 }));
 
-describe('fingerprintService readiness', () => {
-  beforeEach(() => {
-    localStorage.clear();
-    initMock.mockReset();
+vi.mock('@/services/mixpanel', () => ({
+  default: { setPeopleProperties: setPeoplePropertiesMock },
+}));
+
+describe('fingerprintService', () => {
+  let storage: Record<string, string>;
+
+  beforeEach(async () => {
+    clientMock.mockImplementation(() => ({
+      init: initMock,
+      getVisitorData: getVisitorDataMock,
+    }));
+    storage = {};
+    vi.stubGlobal('localStorage', {
+      getItem: (key: string) => storage[key] ?? null,
+      setItem: (key: string, value: string) => {
+        storage[key] = value;
+      },
+      removeItem: (key: string) => {
+        storage = Object.fromEntries(
+          Object.entries(storage).filter(([entryKey]) => entryKey !== key),
+        );
+      },
+      clear: () => {
+        storage = {};
+      },
+    });
     getVisitorDataMock.mockReset();
+    initMock.mockReset();
+    setPeoplePropertiesMock.mockReset();
+    getVisitorDataMock.mockResolvedValue(visitorData);
+    initMock.mockResolvedValue(undefined);
+    await fingerprintService.initFingerprint('test-api-key');
   });
 
-  it('does not identify with a client whose agent failed to load', async () => {
-    const initError = new Error('Agent script blocked');
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('omits unavailable Visitor Found metadata without blocking identification', async () => {
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorFound: undefined,
+    });
+    const result = await fingerprintService.identifyVisitor();
+    expect(result.visitorId).toBe('visitor-123');
+    expect(result.requestId).toBe('request-123');
+    expect(result).not.toHaveProperty('visitorFound');
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+  });
+
+  it('suppresses identify-specific cache and profile effects after its scope closes', async () => {
+    let finish: (value: typeof visitorData) => void = () => undefined;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    let active = true;
+    const pending = getFingerprintForIdentify({
+      isActive: () => active,
+      report: vi.fn(),
+    });
+    active = false;
+    finish(visitorData);
+    await pending;
+    expect(fingerprintService.getCachedFingerprint()).toBeNull();
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+  });
+
+  it('continues the identify path when fingerprint cache writes fail', async () => {
+    vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
+      throw new Error('private-id');
+    });
+    const report = vi.fn();
+    await expect(
+      getFingerprintForIdentify({ isActive: () => true, report }),
+    ).resolves.toBe('visitor-123');
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': true,
+    });
+  });
+
+  it('sanitizes errors only on the identify-specific fingerprint path', async () => {
+    const error = new Error('private-id');
+    getVisitorDataMock.mockRejectedValue(error);
     const consoleError = vi
       .spyOn(console, 'error')
       .mockImplementation(() => undefined);
-    initMock.mockRejectedValue(initError);
-    getVisitorDataMock.mockRejectedValue(
-      new Error(
-        "FPJSAgent hasn't loaded yet. Make sure to call the init() method first.",
-      ),
+    await expect(
+      getFingerprintForIdentify({ isActive: () => true, report: vi.fn() }),
+    ).rejects.toBe(error);
+    expect(consoleError).not.toHaveBeenCalled();
+  });
+
+  it('returns request-scoped identification data and bypasses the SPA cache', async () => {
+    await expect(fingerprintService.identifyVisitor(true)).resolves.toEqual({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+
+    expect(getVisitorDataMock).toHaveBeenCalledWith({}, true);
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': true,
+    });
+  });
+
+  it('writes a false visitor match to the Mixpanel profile', async () => {
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorFound: false,
+    });
+
+    await expect(
+      fingerprintService.identifyVisitor(true),
+    ).resolves.toMatchObject({ visitorFound: false });
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': false,
+    });
+    expect(setPeoplePropertiesMock).toHaveBeenCalledTimes(1);
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps identification data when the Mixpanel profile update fails', async () => {
+    const error = new Error('Mixpanel unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    setPeoplePropertiesMock.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(fingerprintService.identifyVisitor(true)).resolves.toEqual({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+    expect(fingerprintService.getCachedFingerprint()).toBe('visitor-123');
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error updating Mixpanel visitor profile:',
+      error,
+    );
+
+    consoleError.mockRestore();
+  });
+
+  it('preserves the visitor-only SDK cache contract', async () => {
+    await fingerprintService.identifyVisitor(true);
+
+    expect(fingerprintService.getCachedFingerprint()).toBe('visitor-123');
+    await expect(fingerprintService.getFingerprint(true)).resolves.toBe(
+      'visitor-123',
     );
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(setPeoplePropertiesMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not reuse a legacy cached visitor ID as a request-scoped result', async () => {
+    localStorage.setItem(
+      'default_fingerprint_cache',
+      JSON.stringify({
+        fingerprint: 'legacy-visitor',
+        expiresAt: Date.now() + 60_000,
+      }),
+    );
+
+    await expect(
+      fingerprintService.identifyVisitor(true),
+    ).resolves.toMatchObject({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+    });
+    expect(getVisitorDataMock).toHaveBeenCalledWith({}, true);
+  });
+
+  it('reports and rethrows identification errors', async () => {
+    const error = new Error('Fingerprint unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    getVisitorDataMock.mockRejectedValue(error);
+
+    await expect(fingerprintService.identifyVisitor(true)).rejects.toThrow(
+      'Fingerprint unavailable',
+    );
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error retrieving fingerprint:',
+      error,
+    );
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
+  });
+
+  it('does not treat a constructed client as ready until the agent loads', async () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    const initError = new Error('Agent script blocked');
+    initMock.mockRejectedValue(initError);
 
     await expect(
-      fingerprintService.initFingerprint('test-key'),
+      fingerprintService.initFingerprint('test-api-key'),
     ).rejects.toThrow('Agent script blocked');
     expect(fingerprintService.isFingerprintReady()).toBe(false);
-    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
-    expect(getVisitorDataMock).not.toHaveBeenCalled();
     expect(consoleError).toHaveBeenCalledWith(
       'Error initializing identification service:',
       initError,
     );
 
+    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
+    await expect(fingerprintService.identifyVisitor(true)).rejects.toThrow(
+      'Identification service is not initialized.',
+    );
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
     consoleError.mockRestore();
   });
 
-  it('identifies after the agent loads successfully', async () => {
-    initMock.mockResolvedValue(undefined);
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'visitor-123' });
-
-    await fingerprintService.initFingerprint('test-key');
+  it('returns a cached visitor ID when the agent failed to load', async () => {
+    localStorage.setItem(
+      'default_fingerprint_cache',
+      JSON.stringify({
+        fingerprint: 'cached-visitor',
+        expiresAt: Date.now() + 60_000,
+      }),
+    );
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    initMock.mockRejectedValue(new Error('Agent script blocked'));
 
-    expect(fingerprintService.isFingerprintReady()).toBe(true);
+    await expect(
+      fingerprintService.initFingerprint('test-api-key'),
+    ).rejects.toThrow('Agent script blocked');
     await expect(fingerprintService.getFingerprint()).resolves.toBe(
-      'visitor-123',
+      'cached-visitor',
     );
-    expect(getVisitorDataMock).toHaveBeenCalledOnce();
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
   });
 
   it('waits for the agent to load before identifying', async () => {
@@ -71,9 +284,8 @@ describe('fingerprintService readiness', () => {
           finishInit = resolve;
         }),
     );
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'visitor-123' });
 
-    const init = fingerprintService.initFingerprint('test-key');
+    const init = fingerprintService.initFingerprint('test-api-key');
 
     expect(fingerprintService.isFingerprintReady()).toBe(false);
     await expect(fingerprintService.getFingerprint()).resolves.toBe('');
@@ -127,7 +339,10 @@ describe('fingerprintService readiness', () => {
           }),
       )
       .mockResolvedValueOnce(undefined);
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'new-visitor' });
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorId: 'new-visitor',
+    });
     const consoleError = vi
       .spyOn(console, 'error')
       .mockImplementation(() => undefined);

package/src/services/fingerprint.ts

@@ -1,7 +1,10 @@
+import type { FingerprintIdentification } from '@/types/botDetection';
+import type { IdentifyStageContext } from '@/util/identifyAttempt';
 import {
   FingerprintJSPro,
   FpjsClient,
 } from '@fingerprintjs/fingerprintjs-pro-spa';
+import mixpanelService from '@/services/mixpanel';
 
 declare global {
   interface Window {
@@ -18,6 +21,12 @@ const DEFAULT_CACHE_NAME = 'default_fingerprint_cache';
 const DEFAULT_CACHE_TIME_IN_DAYS = 7;
 const PROXY_QUERY_PARAM =
   'apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>';
+
+/**
+ * True only after `fpClient.init()` succeeds. `window.fpClient` exists as soon as
+ * the client is constructed, but that instance still uses a stub agent that throws
+ * "FPJSAgent hasn't loaded yet" until init completes.
+ */
 let fingerprintAgentReady = false;
 
 /**
@@ -38,6 +47,10 @@ const getExpirationDate = (cacheTimeInDays: number): number => {
  * @returns {string | null} - The cached fingerprint or null if it is expired or not found.
  */
 const getCachedFingerprint = (): string | null => {
+  return readCachedFingerprint();
+};
+
+function readCachedFingerprint(context?: IdentifyStageContext): string | null {
   const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig;
 
   try {
@@ -48,9 +61,10 @@ const getCachedFingerprint = (): string | null => {
     localStorage.removeItem(cacheName);
     return null;
   } catch {
+    context?.report('cache', 'unavailable');
     return null;
   }
-};
+}
 
 /**
  * Sets the cached fingerprint in local storage.
@@ -130,11 +144,26 @@ async function initFingerprint(
 
 /**
  * Retrieves the fingerprint, first checking the cache and then querying the identification service if not found.
+ * Returns an empty string when the Fingerprint agent has not loaded, so callers like identify() can continue.
  * @param {boolean} cacheOnly - Optional flag to retrieve the fingerprint only from the cache.
- * @returns {Promise<string>} A promise that resolves with the fingerprint, or an empty string when the agent is unavailable.
+ * @returns {Promise<string>} A promise that resolves with the fingerprint, or an empty string when unavailable.
  * @throws {Error} Throws an error if retrieval fails after the agent has loaded.
  */
 async function getFingerprint(cacheOnly = false): Promise<string> {
+  return readFingerprint(cacheOnly);
+}
+
+/** Internal identify path with late-effect suppression and sanitized diagnostics. */
+export function getFingerprintForIdentify(
+  context: IdentifyStageContext,
+): Promise<string> {
+  return readFingerprint(false, context);
+}
+
+async function readFingerprint(
+  cacheOnly: boolean,
+  context?: IdentifyStageContext,
+): Promise<string> {
   if (!window.fingerprintConfig) {
     if (cacheOnly) {
       return '';
@@ -143,7 +172,7 @@ async function getFingerprint(cacheOnly = false): Promise<string> {
     throw new Error('Fingerprint configuration is not initialized.');
   }
 
-  const cachedFingerprint = getCachedFingerprint();
+  const cachedFingerprint = readCachedFingerprint(context);
   if (cachedFingerprint) {
     return cachedFingerprint;
   }
@@ -152,22 +181,69 @@ async function getFingerprint(cacheOnly = false): Promise<string> {
     return '';
   }
 
+  const { visitorId } = await requestIdentification(false, context);
+  return visitorId;
+}
+
+/**
+ * Requests detailed visitor identification data from Fingerprint.
+ * @param {boolean} ignoreCache - Whether the Fingerprint SPA cache must be bypassed.
+ * @returns {Promise<FingerprintIdentification>} Request-scoped identification data.
+ * @throws {Error} If the identification service is not ready or retrieval fails.
+ */
+async function identifyVisitor(
+  ignoreCache = false,
+): Promise<FingerprintIdentification> {
+  return requestIdentification(ignoreCache);
+}
+
+async function requestIdentification(
+  ignoreCache: boolean,
+  context?: IdentifyStageContext,
+): Promise<FingerprintIdentification> {
+  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;
+    const result = await window.fpClient.getVisitorData({}, ignoreCache);
+    if (!context || context.isActive()) {
+      try {
+        setCachedFingerprint(result.visitorId);
+      } catch (error) {
+        if (!context) throw error;
+        context.report('cache', 'unavailable');
+      }
+      if (typeof result.visitorFound === 'boolean') {
+        try {
+          mixpanelService.setPeopleProperties({
+            'Visitor Found': result.visitorFound,
+          });
+        } catch (error) {
+          if (context) context.report('fingerprint', 'failed');
+          else console.error('Error updating Mixpanel visitor profile:', error);
+        }
+      }
+    }
+
+    return {
+      visitorId: result.visitorId,
+      requestId: result.requestId,
+      ...(typeof result.visitorFound === 'boolean'
+        ? { visitorFound: result.visitorFound }
+        : {}),
+      confidenceScore: result.confidence.score,
+      cacheHit: result.cacheHit,
+    };
   } catch (error) {
-    console.error('Error retrieving fingerprint:', error);
+    if (!context) console.error('Error retrieving fingerprint:', error);
     throw error;
   }
 }
 
 /**
- * Checks if the identification service is ready.
- *
- * This function verifies that the Fingerprint agent loaded successfully.
- * @returns {boolean} Returns true only after the agent has loaded.
+ * Checks if the Fingerprint agent finished loading and can identify visitors.
+ * @returns {boolean} True only after `initFingerprint()` has successfully loaded the agent.
  */
 function isFingerprintReady(): boolean {
   return window.fpClient !== undefined && fingerprintAgentReady;
@@ -176,6 +252,7 @@ function isFingerprintReady(): boolean {
 const fingerprintService = {
   initFingerprint,
   getFingerprint,
+  identifyVisitor,
   isFingerprintReady,
   getCachedFingerprint,
 };