feat: external session

packages/integration-tests/src/tests/native/native.ejs

@@ -4,9 +4,15 @@
        <meta charset="UTF-8">
        <title>Native</title>
        <script>
-               window.SplunkRumNative = {
-                       getNativeSessionId: function() {
-                               return '12341234123412341234123412341234';
+               window.SplunkRumExternal = {
+                       getSessionMetadata: function() {
+                               const now = Date.now();
+                               return {
+                                       anonymousUserId: 'external-anonymous-user-id',
+                                       sessionId: '12341234123412341234123412341234',
+                                       sessionLastActivity: now,
+                                       sessionStart: now - 1000
+                               };
                        }
                };
        </script>

packages/integration-tests/src/tests/native/native.spec.ts

@@ -19,8 +19,8 @@ import { expect } from '@playwright/test'
 
 import { test } from '../../utils/test'
 
-test.describe('native', () => {
-	test('native session id integration', async ({ recordPage }) => {
+test.describe('external', () => {
+	test('external session id integration', async ({ recordPage }) => {
 		await recordPage.goTo('/native/native.ejs')
 
 		await recordPage.waitForSpans((spans) => spans.some((s) => s.name === 'documentFetch'))

packages/session-recorder/src/index.ts

@@ -94,7 +94,7 @@ const createSessionReplaySpanIfAllowed = (spanName: SpanName, sessionId: string
 	// Check if session is managed by native SDK
 	const SplunkRum = getGlobal<SplunkOtelWebType>()
 	const sessionState = SplunkRum?.sessionManager?.getSessionState()
-	if (sessionState?.source === 'native') {
+	if (sessionState?.source === 'external') {
 		log.debug('Session replay span not created - recording is managed by native SDK', { sessionId, spanName })
 		return
 	}

packages/web/src/index.ts

@@ -85,6 +85,7 @@ export { SplunkZipkinExporter } from './exporters/zipkin'
 export * from './session-based-sampler'
 export * from './splunk-web-tracer-provider'
 import { PrivacyManager, SessionManager, SessionState, StorageManager, UserManager } from './managers'
+import { ExternalSessionMetadata, isValidExternalSessionMetadata } from './types/external-session-metadata'
 import { getElementXPath, getTextFromNode } from './utils/index'
 
 interface SplunkOtelWebConfigInternal extends SplunkOtelWebConfig {
@@ -121,6 +122,7 @@ const OPTIONS_DEFAULTS: SplunkOtelWebConfigInternal = {
 	instrumentations: {},
 	persistence: 'cookie',
 	rumAccessToken: undefined,
+	sessionMetadata: undefined,
 	spanProcessor: {
 		factory: (exporter, config) => new BatchSpanProcessor(exporter, config),
 	},
@@ -220,6 +222,8 @@ export interface SplunkOtelWebType extends SplunkOtelWebEventTarget {
 	 */
 	getSessionId: () => string | undefined
 
+	getSessionMetadata: () => ExternalSessionMetadata
+
 	getSessionState: () => SessionState | undefined
 
 	init: (options: SplunkOtelWebConfig) => void
@@ -330,6 +334,28 @@ export const SplunkRum: SplunkOtelWebType = {
 		}
 	},
 
+	getSessionMetadata(): ExternalSessionMetadata {
+		if (!inited || !this.sessionManager) {
+			return null
+		}
+
+		const session = this.sessionManager.getSessionMetadata()
+		if (!session) {
+			return null
+		}
+
+		const metadata: ExternalSessionMetadata = {
+			...session,
+		}
+
+		const anonymousUserId = this.getAnonymousId()
+		if (anonymousUserId) {
+			metadata.anonymousUserId = anonymousUserId
+		}
+
+		return metadata
+	},
+
 	getSessionState() {
 		if (!inited) {
 			return
@@ -514,10 +540,20 @@ export const SplunkRum: SplunkOtelWebType = {
 			})
 
 			this.resource = new Resource(resourceAttrs)
-			this.sessionManager = new SessionManager(storageManager)
-			this.userManager = new UserManager(userTrackingMode, storageManager)
+
+			let sessionMetadataFromOptions: NonNullable<ExternalSessionMetadata> | undefined
+			if (processedOptions.sessionMetadata && isValidExternalSessionMetadata(processedOptions.sessionMetadata)) {
+				sessionMetadataFromOptions = processedOptions.sessionMetadata
+			}
+
+			this.sessionManager = new SessionManager(storageManager, sessionMetadataFromOptions)
+			this.userManager = new UserManager(
+				userTrackingMode,
+				storageManager,
+				sessionMetadataFromOptions?.anonymousUserId,
+			)
 			_sessionStateUnsubscribe = this.sessionManager.subscribe(({ currentState, previousState }) => {
-				if (currentState.isNew && currentState.source !== 'native') {
+				if (currentState.isNew && currentState.source !== 'external') {
 					provider.getTracer('splunk-sessions').startSpan('session.start').end()
 				}
 

packages/web/src/managers/session-manager/session-manager.test.ts

@@ -19,6 +19,8 @@
 import { diag } from '@opentelemetry/api'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import type { ExternalSessionMetadata } from '../../types/external-session-metadata'
+
 import { StorageManager } from '../storage'
 import { SESSION_ID_LENGTH, SESSION_INACTIVITY_TIMEOUT_MS } from './constants'
 import { SessionManager } from './session-manager'
@@ -27,10 +29,24 @@ vi.mock('../../utils/is-trusted-event', () => ({
 	isTrustedEvent: vi.fn(() => true),
 }))
 
+function createExternalSessionMetadata(
+	overrides: Partial<NonNullable<ExternalSessionMetadata>> = {},
+): NonNullable<ExternalSessionMetadata> {
+	const now = Date.now()
+
+	return {
+		anonymousUserId: 'external-anonymous-id',
+		sessionId: 'external-session-id',
+		sessionLastActivity: now,
+		sessionStart: now - 1000,
+		...overrides,
+	}
+}
+
 declare global {
 	interface Window {
-		SplunkRumNative?: {
-			getNativeSessionId(): string
+		SplunkRumExternal?: {
+			getSessionMetadata(): NonNullable<ExternalSessionMetadata>
 		}
 	}
 }
@@ -40,7 +56,7 @@ describe('SessionManager', () => {
 	let storageManager: StorageManager
 
 	beforeEach(() => {
-		window.SplunkRumNative = undefined
+		window.SplunkRumExternal = undefined
 		storageManager = new StorageManager({
 			persistence: 'cookie',
 		})
@@ -103,9 +119,11 @@ describe('SessionManager', () => {
 			expect(sessionManager.getSessionId()).toHaveLength(SESSION_ID_LENGTH)
 		})
 
-		it('should use native session when available', () => {
-			window.SplunkRumNative = {
-				getNativeSessionId: vi.fn().mockReturnValue('native-session-id'),
+		it('should use external session when available', () => {
+			window.SplunkRumExternal = {
+				getSessionMetadata: vi
+					.fn()
+					.mockReturnValue(createExternalSessionMetadata({ sessionId: 'external-session-id' })),
 			}
 
 			const persistedSession = {
@@ -122,40 +140,42 @@ describe('SessionManager', () => {
 
 			sessionManager = new SessionManager(storageManager)
 
-			expect(sessionManager.getSessionId()).toBe('native-session-id')
+			expect(sessionManager.getSessionId()).toBe('external-session-id')
 		})
 	})
 
 	describe('Static Methods', () => {
-		describe('getNativeSessionId', () => {
-			it('should return null when SplunkRumNative is not available', () => {
-				window.SplunkRumNative = undefined
+		describe('getExternalSession', () => {
+			it('should return null when SplunkRumExternal is not available', () => {
+				window.SplunkRumExternal = undefined
 
-				expect(SessionManager.getNativeSessionId()).toBeNull()
+				expect(SessionManager.getExternalSession()).toBeNull()
 			})
 
-			it('should return native session ID when available', () => {
-				window.SplunkRumNative = {
-					getNativeSessionId: vi.fn().mockReturnValue('native-id'),
+			it('should return external session when available', () => {
+				window.SplunkRumExternal = {
+					getSessionMetadata: vi
+						.fn()
+						.mockReturnValue(createExternalSessionMetadata({ sessionId: 'external-id' })),
 				}
 
-				expect(SessionManager.getNativeSessionId()).toBe('native-id')
+				expect(SessionManager.getExternalSession()?.id).toBe('external-id')
 			})
 		})
 
-		describe('hasNativeSessionId', () => {
-			it('should return false when SplunkRumNative is not available', () => {
-				window.SplunkRumNative = undefined
+		describe('hasExternalSession', () => {
+			it('should return false when SplunkRumExternal is not available', () => {
+				window.SplunkRumExternal = undefined
 
-				expect(SessionManager.hasNativeSessionId()).toBe(false)
+				expect(SessionManager.hasExternalSession()).toBe(false)
 			})
 
-			it('should return true when SplunkRumNative is available', () => {
-				window.SplunkRumNative = {
-					getNativeSessionId: vi.fn(),
+			it('should return true when SplunkRumExternal is available', () => {
+				window.SplunkRumExternal = {
+					getSessionMetadata: vi.fn().mockReturnValue(createExternalSessionMetadata()),
 				}
 
-				expect(SessionManager.hasNativeSessionId()).toBe(true)
+				expect(SessionManager.hasExternalSession()).toBe(true)
 			})
 		})
 	})
@@ -427,13 +447,15 @@ describe('SessionManager', () => {
 			expect(sessionManager.getSessionId()).not.toBe('persisted-session-id')
 		})
 
-		it('should not extend session when native session is available', () => {
+		it('should not extend session when external session is available', () => {
 			const diagDebugSpy = vi.spyOn(diag, 'debug')
 
 			sessionManager.start()
 
-			window.SplunkRumNative = {
-				getNativeSessionId: vi.fn().mockReturnValue('native-id'),
+			window.SplunkRumExternal = {
+				getSessionMetadata: vi
+					.fn()
+					.mockReturnValue(createExternalSessionMetadata({ sessionId: 'external-id' })),
 			}
 
 			const keydownEvent = new KeyboardEvent('keydown', {