@grafana/faro-react-native 1.3.1 → 1.4.0

package/src/instrumentations/session/sessionManagerInstance.test.ts

@@ -0,0 +1,65 @@
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { initializeFaro } from '../../initialize';
+
+import { SessionInstrumentation } from './index';
+import { SessionActivityKind } from './sessionActivity';
+import { VolatileSessionsManager } from './sessionManager/VolatileSessionManager';
+
+describe('SessionInstrumentation session manager', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    jest.clearAllMocks();
+  });
+
+  it('constructs a single session manager', async () => {
+    // Constructing a manager subscribes to AppState and to metas, and only the
+    // instance held by the instrumentation can be unpatched. A second, discarded
+    // instance would leak both subscriptions for the lifetime of the app.
+    const initSpy = jest.spyOn(VolatileSessionsManager.prototype as never, 'init' as never);
+
+    await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [new MockTransport()],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    expect(initSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('refreshes activity only after returning from the background', async () => {
+    await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [new MockTransport()],
+        instrumentations: [],
+        sessionTracking: { enabled: true, persistent: false },
+      })
+    );
+    const manager = new VolatileSessionsManager();
+    const checkSessionSpy = jest.spyOn(manager, 'checkSession');
+    const handleAppStateChange = (
+      manager as unknown as { handleAppStateChange: (state: 'active' | 'background' | 'inactive') => void }
+    ).handleAppStateChange;
+
+    handleAppStateChange('active');
+    checkSessionSpy.mockClear();
+    handleAppStateChange('inactive');
+    handleAppStateChange('active');
+    expect(checkSessionSpy).not.toHaveBeenCalled();
+
+    handleAppStateChange('background');
+    handleAppStateChange('inactive');
+    handleAppStateChange('active');
+    expect(checkSessionSpy).toHaveBeenCalledTimes(1);
+    expect(checkSessionSpy).toHaveBeenCalledWith(SessionActivityKind.Meaningful);
+
+    manager.unpatch();
+  });
+});

package/src/instrumentations/session/sessionProcess.test.ts

@@ -0,0 +1,136 @@
+import { NativeModules } from 'react-native';
+
+import {
+  claimSessionPersistenceStorageId,
+  getSessionProcessInfo,
+  MAIN_PROCESS_SESSION_STORAGE_ID,
+  releaseSessionPersistenceOwnership,
+  resetSessionProcessForTests,
+} from './sessionProcess';
+
+const originalNativeModule = NativeModules.FaroReactNativeModule;
+
+function setNativeModule(overrides: Record<string, unknown> = {}): {
+  claimSessionPersistence: jest.Mock;
+  getSessionProcessIdentifier: jest.Mock;
+  isMainSessionProcess: jest.Mock;
+  releaseSessionPersistence: jest.Mock;
+} {
+  const nativeModule = {
+    claimSessionPersistence: jest.fn(() => true),
+    getSessionProcessIdentifier: jest.fn(() => 'com.example.myapp'),
+    isMainSessionProcess: jest.fn(() => true),
+    releaseSessionPersistence: jest.fn(() => true),
+    ...overrides,
+  };
+  NativeModules.FaroReactNativeModule = nativeModule;
+  return nativeModule;
+}
+
+describe('sessionProcess', () => {
+  beforeEach(() => {
+    resetSessionProcessForTests();
+    setNativeModule();
+  });
+
+  afterAll(() => {
+    NativeModules.FaroReactNativeModule = originalNativeModule;
+    resetSessionProcessForTests();
+  });
+
+  it('keeps the legacy MMKV id for the main process', () => {
+    const nativeModule = setNativeModule();
+
+    expect(claimSessionPersistenceStorageId()).toBe(MAIN_PROCESS_SESSION_STORAGE_ID);
+    expect(claimSessionPersistenceStorageId()).toBe(MAIN_PROCESS_SESSION_STORAGE_ID);
+    expect(nativeModule.claimSessionPersistence).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses a separate stable MMKV id for a secondary process', () => {
+    setNativeModule({
+      getSessionProcessIdentifier: jest.fn(() => 'com.example.myapp:sync worker'),
+      isMainSessionProcess: jest.fn(() => false),
+    });
+
+    expect(claimSessionPersistenceStorageId()).toBe(
+      `${MAIN_PROCESS_SESSION_STORAGE_ID}.com.example.myapp%3Async%20worker`
+    );
+    expect(getSessionProcessInfo()).toEqual({
+      identifier: 'com.example.myapp:sync worker',
+      isMain: false,
+    });
+  });
+
+  it('caches the native process identity for this JavaScript runtime', () => {
+    const nativeModule = setNativeModule();
+
+    expect(getSessionProcessInfo()).toEqual({ identifier: 'com.example.myapp', isMain: true });
+    expect(getSessionProcessInfo()).toEqual({ identifier: 'com.example.myapp', isMain: true });
+    expect(nativeModule.getSessionProcessIdentifier).toHaveBeenCalledTimes(1);
+    expect(nativeModule.isMainSessionProcess).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails closed when the native process bridge is unavailable', () => {
+    NativeModules.FaroReactNativeModule = undefined;
+    resetSessionProcessForTests();
+
+    expect(getSessionProcessInfo()).toBeNull();
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+  });
+
+  it.each([
+    ['empty identity', { getSessionProcessIdentifier: jest.fn(() => '  ') }],
+    ['invalid main-process result', { isMainSessionProcess: jest.fn(() => null) }],
+    [
+      'identity lookup failure',
+      {
+        getSessionProcessIdentifier: jest.fn(() => {
+          throw new Error('unavailable');
+        }),
+      },
+    ],
+  ])('fails closed for %s', (_name, overrides) => {
+    const nativeModule = setNativeModule(overrides);
+
+    expect(getSessionProcessInfo()).toBeNull();
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+    expect(nativeModule.claimSessionPersistence).not.toHaveBeenCalled();
+  });
+
+  it('falls back to in-memory sessions when another runtime owns persistence', () => {
+    const nativeModule = setNativeModule({ claimSessionPersistence: jest.fn(() => false) });
+
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+    expect(nativeModule.claimSessionPersistence).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases ownership so MMKV initialization can be retried safely', () => {
+    const nativeModule = setNativeModule();
+
+    expect(claimSessionPersistenceStorageId()).toBe(MAIN_PROCESS_SESSION_STORAGE_ID);
+    expect(releaseSessionPersistenceOwnership()).toBe(true);
+    expect(claimSessionPersistenceStorageId()).toBe(MAIN_PROCESS_SESSION_STORAGE_ID);
+
+    expect(nativeModule.claimSessionPersistence).toHaveBeenCalledTimes(2);
+    expect(nativeModule.releaseSessionPersistence).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not release persistence when this runtime never claimed it', () => {
+    const nativeModule = setNativeModule({ claimSessionPersistence: jest.fn(() => false) });
+
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+    expect(releaseSessionPersistenceOwnership()).toBe(false);
+    expect(nativeModule.releaseSessionPersistence).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when the persistence claim throws', () => {
+    setNativeModule({
+      claimSessionPersistence: jest.fn(() => {
+        throw new Error('native failure');
+      }),
+    });
+
+    expect(claimSessionPersistenceStorageId()).toBeNull();
+  });
+});

package/src/instrumentations/session/sessionProcess.ts

@@ -0,0 +1,114 @@
+import { NativeModules } from 'react-native';
+
+export const MAIN_PROCESS_SESSION_STORAGE_ID = 'grafana-faro-react-native-session';
+
+interface SessionProcessNativeModule {
+  claimSessionPersistence?: () => unknown;
+  getSessionProcessIdentifier?: () => unknown;
+  isMainSessionProcess?: () => unknown;
+  releaseSessionPersistence?: () => unknown;
+}
+
+export interface SessionProcessInfo {
+  identifier: string;
+  isMain: boolean;
+}
+
+let cachedProcessInfo: SessionProcessInfo | null | undefined;
+let cachedPersistenceOwnership: boolean | undefined;
+
+function getNativeModule(): SessionProcessNativeModule | undefined {
+  return NativeModules['FaroReactNativeModule'] as SessionProcessNativeModule | undefined;
+}
+
+/** Stable native process identity used to isolate session chains. */
+export function getSessionProcessInfo(): SessionProcessInfo | null {
+  if (cachedProcessInfo !== undefined) {
+    return cachedProcessInfo;
+  }
+
+  const nativeModule = getNativeModule();
+  if (
+    typeof nativeModule?.getSessionProcessIdentifier !== 'function' ||
+    typeof nativeModule.isMainSessionProcess !== 'function'
+  ) {
+    cachedProcessInfo = null;
+    return cachedProcessInfo;
+  }
+
+  try {
+    const identifier = nativeModule.getSessionProcessIdentifier();
+    const isMain = nativeModule.isMainSessionProcess();
+    if (typeof identifier !== 'string' || identifier.trim().length === 0 || typeof isMain !== 'boolean') {
+      cachedProcessInfo = null;
+      return cachedProcessInfo;
+    }
+
+    cachedProcessInfo = { identifier: identifier.trim(), isMain };
+  } catch {
+    cachedProcessInfo = null;
+  }
+
+  return cachedProcessInfo;
+}
+
+/**
+ * Returns the MMKV instance ID owned by this runtime, or null when exclusive
+ * ownership cannot be established. The main process retains the legacy ID so
+ * upgrades keep their existing previous-session link.
+ */
+export function claimSessionPersistenceStorageId(): string | null {
+  const processInfo = getSessionProcessInfo();
+  if (processInfo == null) {
+    return null;
+  }
+
+  if (cachedPersistenceOwnership === undefined) {
+    const nativeModule = getNativeModule();
+    if (typeof nativeModule?.claimSessionPersistence !== 'function') {
+      cachedPersistenceOwnership = false;
+    } else {
+      try {
+        cachedPersistenceOwnership = nativeModule.claimSessionPersistence() === true;
+      } catch {
+        cachedPersistenceOwnership = false;
+      }
+    }
+  }
+
+  if (!cachedPersistenceOwnership) {
+    return null;
+  }
+
+  return processInfo.isMain
+    ? MAIN_PROCESS_SESSION_STORAGE_ID
+    : `${MAIN_PROCESS_SESSION_STORAGE_ID}.${encodeURIComponent(processInfo.identifier)}`;
+}
+
+/** Releases storage ownership after MMKV initialization fails. */
+export function releaseSessionPersistenceOwnership(): boolean {
+  if (cachedPersistenceOwnership !== true) {
+    return false;
+  }
+
+  const nativeModule = getNativeModule();
+  if (typeof nativeModule?.releaseSessionPersistence !== 'function') {
+    return false;
+  }
+
+  try {
+    const released = nativeModule.releaseSessionPersistence() === true;
+    if (released) {
+      cachedPersistenceOwnership = undefined;
+    }
+    return released;
+  } catch {
+    return false;
+  }
+}
+
+/** @internal */
+export function resetSessionProcessForTests(): void {
+  cachedProcessInfo = undefined;
+  cachedPersistenceOwnership = undefined;
+}

package/src/instrumentations/session/startNewSession.test.ts

@@ -0,0 +1,337 @@
+import { NativeModules } from 'react-native';
+
+import { BaseInstrumentation, EVENT_SESSION_START, initializeFaro, VERSION } from '@grafana/faro-core';
+import type { Faro } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { SamplingFunction } from '../../config/sampling';
+import { EVENT_NAVIGATION } from '../../navigation/utils';
+
+import { SessionInstrumentation, startNewSession } from './index';
+import {
+  MmkvPersistentSessionsManager,
+  resetMmkvSingletonForTests,
+} from './sessionManager/MmkvPersistentSessionsManager';
+import { STORAGE_KEY } from './sessionManager/sessionConstants';
+import { VolatileSessionsManager } from './sessionManager/VolatileSessionManager';
+import { resetSessionProcessForTests } from './sessionProcess';
+
+const mockMmkvValues = new Map<string, string>();
+const mockMmkv = {
+  getString: jest.fn((key: string) => mockMmkvValues.get(key)),
+  set: jest.fn((key: string, value: string) => mockMmkvValues.set(key, value)),
+  remove: jest.fn((key: string) => mockMmkvValues.delete(key)),
+};
+const originalNativeModule = NativeModules.FaroReactNativeModule;
+
+jest.mock('react-native-mmkv', () => ({
+  createMMKV: jest.fn(() => mockMmkv),
+}));
+
+const initialTime = new Date('2026-08-20T12:00:00.000Z').getTime();
+
+type InitializeSessionOptions = {
+  maxSessionPersistenceTime?: number;
+  persistent: boolean;
+  sessionIds?: string[];
+  samplingRates?: number[];
+  onSessionChange?: jest.Mock;
+};
+
+function initializeSession({
+  maxSessionPersistenceTime,
+  persistent,
+  sessionIds = ['session-1', 'session-2', 'session-3'],
+  samplingRates = [1, 1, 1],
+  onSessionChange = jest.fn(),
+}: InitializeSessionOptions) {
+  const remainingSessionIds = [...sessionIds];
+  const generateSessionId = jest.fn(() => remainingSessionIds.shift() ?? 'fallback-session');
+  const resolveSampling = jest.fn(() => samplingRates.shift() ?? 1);
+  const transport = new MockTransport();
+  const instrumentation = new SessionInstrumentation();
+  const faro = initializeFaro(
+    mockConfig({
+      transports: [transport],
+      instrumentations: [instrumentation],
+      sessionTracking: {
+        enabled: true,
+        maxSessionPersistenceTime,
+        persistent,
+        generateSessionId,
+        onSessionChange,
+        sampling: new SamplingFunction(resolveSampling),
+      },
+    })
+  );
+
+  return { faro, generateSessionId, instrumentation, onSessionChange, resolveSampling, transport };
+}
+
+class CompatibleSessionInstrumentation extends BaseInstrumentation {
+  readonly name = '@grafana/faro-react-native:instrumentation-session';
+  readonly version = VERSION;
+  readonly startNewSession = jest.fn();
+
+  initialize(): void {}
+}
+
+function sessionStartItems(transport: MockTransport) {
+  return transport.items.filter(
+    (item) => item.type === 'event' && 'name' in item.payload && item.payload.name === EVENT_SESSION_START
+  );
+}
+
+describe('startNewSession', () => {
+  const initializedFaros: Faro[] = [];
+
+  beforeAll(() => {
+    jest.useFakeTimers();
+  });
+
+  beforeEach(() => {
+    NativeModules.FaroReactNativeModule = {
+      claimSessionPersistence: () => true,
+      getSessionProcessIdentifier: () => 'com.example.myapp',
+      isMainSessionProcess: () => true,
+      releaseSessionPersistence: () => true,
+    };
+    jest.setSystemTime(initialTime);
+    jest.clearAllMocks();
+    mockMmkvValues.clear();
+    resetMmkvSingletonForTests();
+    resetSessionProcessForTests();
+    VolatileSessionsManager.removeUserSession();
+  });
+
+  afterEach(() => {
+    for (const faro of initializedFaros.splice(0)) {
+      for (const instrumentation of faro.instrumentations.instrumentations) {
+        instrumentation.unpatch?.();
+      }
+    }
+    delete (globalThis as Record<string, unknown>)['faro'];
+    jest.restoreAllMocks();
+  });
+
+  afterAll(() => {
+    NativeModules.FaroReactNativeModule = originalNativeModule;
+    resetSessionProcessForTests();
+    jest.useRealTimers();
+  });
+
+  it.each([
+    ['volatile', false],
+    ['persistent', true],
+  ])('starts and links a new %s session on every reset', (_mode, persistent) => {
+    const setup = initializeSession({ persistent });
+    initializedFaros.push(setup.faro);
+    const initialSession = setup.faro.api.getSession();
+    const sessionsAtActionEnd: Array<string | undefined> = [];
+    const activeAction = {
+      end: jest.fn(() => sessionsAtActionEnd.push(setup.faro.api.getSession()?.id)),
+    };
+    jest.spyOn(setup.faro.api, 'getActiveUserAction').mockReturnValue(activeAction as never);
+
+    jest.setSystemTime(initialTime + 60_000);
+    startNewSession();
+    const secondSession = setup.faro.api.getSession();
+    const secondStoredSession = persistent
+      ? MmkvPersistentSessionsManager.fetchUserSession()
+      : VolatileSessionsManager.fetchUserSession();
+
+    jest.setSystemTime(initialTime + 120_000);
+    startNewSession();
+    const thirdSession = setup.faro.api.getSession();
+    const thirdStoredSession = persistent
+      ? MmkvPersistentSessionsManager.fetchUserSession()
+      : VolatileSessionsManager.fetchUserSession();
+
+    expect(initialSession?.id).toBe('session-1');
+    expect(secondSession).toMatchObject({
+      id: 'session-2',
+      attributes: { previousSession: 'session-1' },
+    });
+    expect(secondStoredSession).toMatchObject({
+      sessionId: 'session-2',
+      started: initialTime + 60_000,
+      lastActivity: initialTime + 60_000,
+    });
+    expect(thirdSession).toMatchObject({
+      id: 'session-3',
+      attributes: { previousSession: 'session-2' },
+    });
+    expect(thirdStoredSession).toMatchObject({
+      sessionId: 'session-3',
+      started: initialTime + 120_000,
+      lastActivity: initialTime + 120_000,
+    });
+    expect(sessionStartItems(setup.transport).map((item) => item.meta.session?.id)).toStrictEqual([
+      'session-1',
+      'session-2',
+      'session-3',
+    ]);
+    expect(setup.onSessionChange).toHaveBeenNthCalledWith(1, initialSession, secondSession);
+    expect(setup.onSessionChange).toHaveBeenNthCalledWith(2, secondSession, thirdSession);
+    expect(activeAction.end).toHaveBeenCalledTimes(2);
+    expect(sessionsAtActionEnd).toStrictEqual(['session-1', 'session-2']);
+
+    if (persistent) {
+      expect(JSON.parse(mockMmkvValues.get(STORAGE_KEY) ?? '')).toMatchObject({
+        currentSessionId: 'session-3',
+        previousSessionId: 'session-2',
+        startedAt: initialTime + 120_000,
+        lastActivityAt: initialTime + 120_000,
+      });
+    }
+  });
+
+  it('makes a fresh sampling decision for every reset', () => {
+    const setup = initializeSession({ persistent: false, samplingRates: [1, 0, 1] });
+    initializedFaros.push(setup.faro);
+
+    expect(VolatileSessionsManager.fetchUserSession()?.isSampled).toBe(true);
+    startNewSession();
+    expect(VolatileSessionsManager.fetchUserSession()?.isSampled).toBe(false);
+    startNewSession();
+    expect(VolatileSessionsManager.fetchUserSession()?.isSampled).toBe(true);
+    expect(setup.resolveSampling).toHaveBeenCalledTimes(3);
+    expect(sessionStartItems(setup.transport).map((item) => item.meta.session?.id)).toStrictEqual([
+      'session-1',
+      'session-3',
+    ]);
+  });
+
+  it('uses compact fallback IDs when a custom generator repeats the current ID', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation();
+    const setup = initializeSession({
+      persistent: false,
+      sessionIds: ['same-session', 'same-session', 'same-session', 'same-session'],
+    });
+    initializedFaros.push(setup.faro);
+
+    startNewSession();
+    const secondSessionId = setup.faro.api.getSession()?.id;
+    startNewSession();
+    const thirdSessionId = setup.faro.api.getSession()?.id;
+    startNewSession();
+    const fourthSessionId = setup.faro.api.getSession()?.id;
+
+    expect(secondSessionId).not.toBe('same-session');
+    expect(secondSessionId).not.toMatch(/^same-session-/);
+    expect(thirdSessionId).toBe('same-session');
+    expect(fourthSessionId).not.toBe('same-session');
+    expect(fourthSessionId).not.toMatch(/^same-session-/);
+    expect(setup.faro.api.getSession()?.attributes?.['previousSession']).toBe('same-session');
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(warn).toHaveBeenNthCalledWith(
+      1,
+      'The session ID generator returned the current session ID; using a generated fallback for the new session.'
+    );
+  });
+
+  it('keeps an active action with the previous session when an explicit reset happens after expiry', () => {
+    const setup = initializeSession({
+      maxSessionPersistenceTime: 15 * 60 * 1000,
+      persistent: false,
+    });
+    initializedFaros.push(setup.faro);
+    const activeAction = {
+      end: jest.fn(() => setup.faro.api.pushEvent('active_action_flushed')),
+    };
+    jest.spyOn(setup.faro.api, 'getActiveUserAction').mockReturnValue(activeAction as never);
+
+    jest.setSystemTime(initialTime + 15 * 60 * 1000);
+    startNewSession();
+
+    const flushedAction = setup.transport.items.find(
+      (item) => item.type === 'event' && 'name' in item.payload && item.payload.name === 'active_action_flushed'
+    );
+    expect(flushedAction?.meta.session?.id).toBe('session-1');
+    expect(setup.faro.api.getSession()).toMatchObject({
+      id: 'session-2',
+      attributes: { previousSession: 'session-1' },
+    });
+    expect(sessionStartItems(setup.transport).map((item) => item.meta.session?.id)).toStrictEqual([
+      'session-1',
+      'session-2',
+    ]);
+    expect(setup.generateSessionId).toHaveBeenCalledTimes(2);
+    expect(setup.onSessionChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears a pending persistent activity write before storing the reset session', () => {
+    const setup = initializeSession({ persistent: true });
+    initializedFaros.push(setup.faro);
+
+    jest.advanceTimersByTime(1);
+    setup.faro.api.pushEvent(EVENT_NAVIGATION, { screen: 'cart' });
+    jest.advanceTimersByTime(1);
+    setup.faro.api.pushEvent(EVENT_NAVIGATION, { screen: 'checkout' });
+    const writesBeforeReset = mockMmkv.set.mock.calls.length;
+
+    jest.advanceTimersByTime(1);
+    startNewSession();
+    const writesAfterReset = mockMmkv.set.mock.calls.length;
+
+    expect(writesAfterReset).toBe(writesBeforeReset + 1);
+    expect(MmkvPersistentSessionsManager.fetchUserSession()?.sessionId).toBe('session-2');
+    jest.advanceTimersByTime(1000);
+    expect(mockMmkv.set).toHaveBeenCalledTimes(writesAfterReset);
+  });
+
+  it('uses a compatible session instrumentation from another module copy', () => {
+    const instrumentation = new CompatibleSessionInstrumentation();
+    const faro = initializeFaro(
+      mockConfig({
+        instrumentations: [instrumentation],
+      })
+    );
+    initializedFaros.push(faro);
+
+    startNewSession();
+
+    expect(instrumentation.startNewSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores a reset triggered re-entrantly by onSessionChange', () => {
+    const onSessionChange = jest.fn(() => startNewSession());
+    const setup = initializeSession({ persistent: false, onSessionChange });
+    initializedFaros.push(setup.faro);
+
+    startNewSession();
+
+    expect(setup.faro.api.getSession()?.id).toBe('session-2');
+    expect(setup.generateSessionId).toHaveBeenCalledTimes(2);
+    expect(onSessionChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('does nothing when session tracking is disabled', () => {
+    const instrumentation = new SessionInstrumentation();
+    const transport = new MockTransport();
+    const faro = initializeFaro(
+      mockConfig({
+        transports: [transport],
+        instrumentations: [instrumentation],
+        sessionTracking: { enabled: false },
+      })
+    );
+    initializedFaros.push(faro);
+
+    startNewSession();
+
+    expect(faro.api.getSession()).toBeUndefined();
+    expect(sessionStartItems(transport)).toHaveLength(0);
+  });
+
+  it('does nothing after the session instrumentation is unpatched', () => {
+    const setup = initializeSession({ persistent: false });
+    initializedFaros.push(setup.faro);
+    setup.instrumentation.unpatch();
+
+    startNewSession();
+
+    expect(setup.faro.api.getSession()?.id).toBe('session-1');
+    expect(setup.generateSessionId).toHaveBeenCalledTimes(1);
+  });
+});

package/src/instrumentations/startup/index.ts

@@ -13,15 +13,12 @@ const { FaroReactNativeModule } = NativeModules;
  * - iOS: sysctl() to query kernel for process start time
  * - Android: Process.getStartElapsedRealtime() from Android OS (API 24+)
  *
- * Implementation aligned with Faro Flutter SDK:
- * https://github.com/grafana/faro-flutter-sdk
- *
  * **Key Features**:
  * - ✅ NO AppDelegate/MainActivity setup required - OS tracks process start automatically!
  * - ✅ Cold start: appStartDuration from native, coldStart: 1
  * - ✅ Warm start: appStartDuration (time to first frame after resume), coldStart: 0
  *
- * **Metrics Captured** (matches Flutter SDK format):
+ * **Metrics Captured**:
  * - Cold start: `appStartDuration`, `coldStart: 1`
  * - Warm start: `appStartDuration`, `coldStart: 0`
  *
@@ -63,7 +60,7 @@ export class StartupInstrumentation extends BaseInstrumentation {
 
   /**
    * Captures cold start duration from native (process start to Faro init).
-   * Matches Flutter SDK: appStartDuration + coldStart: 1
+   * Sends appStartDuration with coldStart: 1.
    */
   private captureColdStartMetrics(): void {
     try {
@@ -102,7 +99,6 @@ export class StartupInstrumentation extends BaseInstrumentation {
 
   /**
    * Tracks warm start: when app resumes from background, measures time to first frame.
-   * Matches Flutter SDK: setWarmStart on resume, getWarmStart after postFrameCallback.
    */
   private setupWarmStartTracking(): void {
     this.appStateSubscription = AppState.addEventListener('change', (nextAppState) => {