✨ Add url option to startView API

packages/rum-core/src/boot/rumPublicApi.ts

@@ -388,7 +388,7 @@ export interface RumPublicApi extends PublicApi {
    *
    * Context - @category Data Collection
    *
-   * @param nameOrOptions - Name or options (name, service, version) for the view
+   * @param nameOrOptions - The view name, or a {@link ViewOptions} object to configure the view
    */
   startView(nameOrOptions?: string | ViewOptions): void
 

packages/rum-core/src/domain/contexts/urlContexts.spec.ts

@@ -49,6 +49,64 @@ describe('urlContexts', () => {
     expect(urlContext.referrer).toBe(document.referrer)
   })
 
+  it('should use the provided url override instead of location', () => {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+      startClocks: relativeToClocks(0 as RelativeTime),
+      url: 'https://example.com/overridden-path',
+    } as ViewCreatedEvent)
+
+    const urlContext = urlContexts.findUrl()!
+    expect(urlContext.url).toBe('https://example.com/overridden-path')
+    expect(urlContext.referrer).toBe(document.referrer)
+  })
+
+  it('should resolve a relative url override against the current location', () => {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+      startClocks: relativeToClocks(0 as RelativeTime),
+      url: '/dashboard',
+    } as ViewCreatedEvent)
+
+    const urlContext = urlContexts.findUrl()!
+    expect(urlContext.url).toBe('http://fake-url.com/dashboard')
+  })
+
+  it('should fall back to location.href when no url override is provided', () => {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+      startClocks: relativeToClocks(0 as RelativeTime),
+    } as ViewCreatedEvent)
+
+    const urlContext = urlContexts.findUrl()!
+    expect(urlContext.url).toBe('http://fake-url.com/')
+  })
+
+  it('should fall back to location.href when url override is explicitly undefined', () => {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+      startClocks: relativeToClocks(0 as RelativeTime),
+      url: undefined,
+    } as ViewCreatedEvent)
+
+    const urlContext = urlContexts.findUrl()!
+    expect(urlContext.url).toBe('http://fake-url.com/')
+  })
+
+  it('should use the provided url override for events starting before a location change', () => {
+    lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
+      startClocks: clocksNow(),
+      url: 'https://example.com/manual-url',
+    } as ViewCreatedEvent)
+
+    clock.tick(10)
+    const resourceStartTime = clock.relative(10)
+
+    clock.tick(10)
+    changeLocation('/new-path')
+
+    expect(urlContexts.findUrl(resourceStartTime)).toEqual({
+      url: 'https://example.com/manual-url',
+      referrer: document.referrer,
+    })
+  })
+
   it('should update url context on location change', () => {
     lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, {
       startClocks: relativeToClocks(0 as RelativeTime),

packages/rum-core/src/domain/contexts/urlContexts.ts

@@ -6,6 +6,7 @@ import {
   HookNames,
   DISCARDED,
   mockable,
+  buildUrl,
 } from '@datadog/browser-core'
 import type { LocationChange } from '../../browser/locationChangeObservable'
 import type { LifeCycle } from '../lifeCycle'
@@ -39,8 +40,9 @@ export function startUrlContexts(
 
   let previousViewUrl: string | undefined
 
-  lifeCycle.subscribe(LifeCycleEventType.BEFORE_VIEW_CREATED, ({ startClocks }) => {
-    const viewUrl = mockable(location).href
+  lifeCycle.subscribe(LifeCycleEventType.BEFORE_VIEW_CREATED, ({ startClocks, url }) => {
+    const mockedLocationHref = mockable(location).href
+    const viewUrl = url !== undefined ? buildUrl(url, mockedLocationHref).href : mockedLocationHref
     urlContextHistory.add(
       buildUrlContext({
         url: viewUrl,

packages/rum-core/src/domain/view/trackViews.ts

@@ -71,6 +71,7 @@ export interface ViewCreatedEvent {
   version?: string
   context?: Context
   startClocks: ClocksState
+  url?: string
 }
 
 export interface BeforeViewUpdateEvent {
@@ -102,6 +103,7 @@ export interface ViewOptions {
   version?: RumInitConfiguration['version']
   context?: Context
   handlingStack?: string
+  url?: string
 }
 
 export function trackViews(
@@ -241,6 +243,7 @@ function newView(
     service,
     version,
     context,
+    url: viewOptions?.url,
   }
   lifeCycle.notify(LifeCycleEventType.BEFORE_VIEW_CREATED, viewCreatedEvent)
   lifeCycle.notify(LifeCycleEventType.VIEW_CREATED, viewCreatedEvent)

test/e2e/scenario/rum/init.scenario.ts

@@ -119,6 +119,29 @@ test.describe('API calls and events around init', () => {
       )
     })
 
+  createTest('should use the provided url option instead of location')
+    .withRum()
+    .withRumSlim()
+    .withRumInit((configuration) => {
+      window.DD_RUM!.init(configuration)
+
+      setTimeout(
+        () =>
+          window.DD_RUM!.startView({
+            name: 'manual view',
+            url: 'https://example.com/overridden-path',
+          }),
+        10
+      )
+    })
+    .run(async ({ intakeRegistry, flushEvents }) => {
+      await flushEvents()
+
+      const manualView = intakeRegistry.rumViewEvents.find((event) => event.view.name === 'manual view')!
+      expect(manualView).toBeTruthy()
+      expect(manualView.view.url).toBe('https://example.com/overridden-path')
+    })
+
   createTest('should be able to set view context')
     .withRum()
     .withRumSlim()