Add page data to web signals (#1238)

Author: silesky

.changeset/pink-ladybugs-impress.md

@@ -0,0 +1,6 @@
+---
+'@segment/analytics-signals': minor
+'@segment/analytics-signals-runtime': minor
+---
+
+Add page data to web signals

packages/signals/signals-integration-tests/src/helpers/fixtures.ts

@@ -0,0 +1,15 @@
+import { PageData } from '@segment/analytics-signals-runtime'
+
+const pageData: PageData = {
+  hash: '',
+  hostname: 'localhost',
+  path: '/src/tests/signals-vanilla/index.html',
+  referrer: '',
+  search: '',
+  title: '',
+  url: 'http://localhost:5432/src/tests/signals-vanilla/index.html',
+}
+
+export const commonSignalData = {
+  page: pageData,
+}

packages/signals/signals-integration-tests/src/tests/signals-vanilla/basic.test.ts

@@ -1,4 +1,5 @@
 import { test, expect } from '@playwright/test'
+import { commonSignalData } from '../../helpers/fixtures'
 import { IndexPage } from './index-page'
 
 const basicEdgeFn = `
@@ -57,6 +58,7 @@ test('network signals xhr', async () => {
   )
   expect(responses).toHaveLength(1)
   expect(responses[0].properties!.data.data).toEqual({ someResponse: 'yep' })
+  expect(responses[0].properties!.data.page).toEqual(commonSignalData.page)
 })
 
 test('instrumentation signals', async () => {
@@ -113,6 +115,7 @@ test('interaction signals', async () => {
       type: 'submit',
       value: '',
     },
+    page: commonSignalData.page,
   }
 
   expect(interactionSignals[0]).toMatchObject({
@@ -182,6 +185,7 @@ test('navigation signals', async ({ page }) => {
         hash: '#foo',
         search: '',
         title: '',
+        page: expect.any(Object),
       },
     })
   }

packages/signals/signals-integration-tests/src/tests/signals-vanilla/index-page.ts

@@ -27,11 +27,8 @@ export class IndexPage extends BasePage {
     return this.page.evaluate(
       (args) => {
         window.signalsPlugin.addSignal({
-          type: 'userDefined',
-          data: {
-            foo: 'bar',
-            ...args.data,
-          },
+          foo: 'bar',
+          ...args.data,
         })
       },
       { data }

packages/signals/signals-integration-tests/src/tests/signals-vanilla/network-signals-fetch.test.ts

@@ -1,4 +1,5 @@
 import { test, expect } from '@playwright/test'
+import { commonSignalData } from '../../helpers/fixtures'
 import { IndexPage } from './index-page'
 
 const basicEdgeFn = `const processSignal = (signal) => {}`
@@ -32,6 +33,7 @@ test.describe('network signals - fetch', () => {
       data: null,
       method: 'POST',
       url: 'http://localhost/upload',
+      ...commonSignalData,
     })
   })
 
@@ -61,6 +63,7 @@ test.describe('network signals - fetch', () => {
       action: 'request',
       url: 'http://localhost/test',
       data: { key: 'value' },
+      ...commonSignalData,
     })
   })
 
@@ -90,6 +93,7 @@ test.describe('network signals - fetch', () => {
       action: 'request',
       url: 'http://localhost/test',
       data: 'hello world',
+      ...commonSignalData,
     })
   })
 
@@ -104,6 +108,7 @@ test.describe('network signals - fetch', () => {
         method: 'POST',
         body: JSON.stringify({ key: 'value' }),
         contentType: 'application/json',
+        ...commonSignalData,
       }
     )
 
@@ -124,6 +129,7 @@ test.describe('network signals - fetch', () => {
       url: 'http://localhost/test',
       method: 'POST',
       data: { key: 'value' },
+      ...commonSignalData,
     })
 
     const responses = networkEvents.filter(
@@ -137,6 +143,7 @@ test.describe('network signals - fetch', () => {
       data: { foo: 'test' },
       status: 200,
       ok: true,
+      ...commonSignalData,
     })
   })
 
@@ -165,6 +172,7 @@ test.describe('network signals - fetch', () => {
       action: 'request',
       url: `${indexPage.origin()}/test`,
       data: { key: 'value' },
+      ...commonSignalData,
     })
 
     const responses = networkEvents.filter(
@@ -175,6 +183,7 @@ test.describe('network signals - fetch', () => {
       action: 'response',
       url: `${indexPage.origin()}/test`,
       data: { foo: 'test' },
+      ...commonSignalData,
     })
   })
 
@@ -214,6 +223,7 @@ test.describe('network signals - fetch', () => {
         data: { errorMsg: 'foo' },
         status: 400,
         ok: false,
+        page: expect.any(Object),
       })
       expect(responses).toHaveLength(1)
     })
@@ -253,6 +263,7 @@ test.describe('network signals - fetch', () => {
         data: 'foo',
         status: 400,
         ok: false,
+        ...commonSignalData,
       })
       expect(responses).toHaveLength(1)
     })

packages/signals/signals-runtime/src/__tests__/signals-runtime.test.ts

@@ -2,6 +2,7 @@ import { InstrumentationSignal, InteractionSignal, Signal } from '../index'
 import {
   mockInstrumentationSignal,
   mockInteractionSignal,
+  mockPageData,
 } from '../test-helpers/mocks/mock-signal-types-web'
 
 import { WebSignalsRuntime } from '../web/web-signals-runtime'
@@ -17,6 +18,7 @@ describe(WebSignalsRuntime, () => {
     signal3 = {
       ...mockInteractionSignal,
       data: {
+        page: mockPageData,
         eventType: 'change',
         target: {} as any,
         change: {},

packages/signals/signals-runtime/src/test-helpers/mocks/mock-signal-types-web.ts

@@ -4,11 +4,24 @@ import {
   InstrumentationSignal,
   UserDefinedSignal,
   NetworkSignal,
+  PageData,
 } from '../../web/web-signals-types'
 // Mock data for testing
+
+export const mockPageData: PageData = {
+  url: 'https://www.segment.com/docs/connections/sources/catalog/libraries/website/javascript/',
+  path: '/docs/connections/sources/catalog/libraries/website/javascript/',
+  search: '',
+  hostname: 'www.segment.com',
+  hash: '',
+  referrer: '',
+  title: 'Segment - Documentation',
+}
+
 export const mockInteractionSignal: InteractionSignal = {
   type: 'interaction',
   data: {
+    page: mockPageData,
     eventType: 'click',
     target: {
       id: 'button1',
@@ -22,6 +35,7 @@ export const mockInteractionSignal: InteractionSignal = {
 export const mockNavigationSignal: NavigationSignal = {
   type: 'navigation',
   data: {
+    page: mockPageData,
     action: 'urlChange',
     url: 'https://example.com',
     hash: '#section1',
@@ -33,6 +47,7 @@ export const mockNavigationSignal: NavigationSignal = {
 export const mockInstrumentationSignal: InstrumentationSignal = {
   type: 'instrumentation',
   data: {
+    page: mockPageData,
     rawEvent: { type: 'customEvent', detail: 'example' },
   },
   metadata: { timestamp: Date.now() },
@@ -41,6 +56,7 @@ export const mockInstrumentationSignal: InstrumentationSignal = {
 export const mockNetworkSignal: NetworkSignal = {
   type: 'network',
   data: {
+    page: mockPageData,
     action: 'request',
     contentType: 'application/json',
     url: 'https://api.example.com/data',
@@ -53,6 +69,7 @@ export const mockNetworkSignal: NetworkSignal = {
 export const mockUserDefinedSignal: UserDefinedSignal = {
   type: 'userDefined',
   data: {
+    page: mockPageData,
     customField: 'customValue',
   },
   metadata: { timestamp: Date.now() },

packages/signals/signals-runtime/src/web/web-signals-types.ts

@@ -2,9 +2,55 @@ import { BaseSignal, JSONValue } from '../shared/shared-types'
 
 export type SignalTypes = Signal['type']
 
+export interface PageData {
+  /**
+   * The full URL of the page
+   * If there is a canonical URL, this should be the canonical URL
+   * @example https://www.segment.com/docs/connections/sources/catalog/libraries/website/javascript/
+   */
+  url: string
+  /**
+   * The path of the page
+   * @example /docs/connections/sources/catalog/libraries/website/javascript/
+   */
+  path: string
+  /**
+   * The search parameters of the page
+   * @example ?utm_source=google
+   */
+  search: string
+  /**
+   * The hostname of the page
+   * @example www.segment.com
+   */
+  hostname: string
+  /**
+   * The hash of the page
+   * @example #hash
+   */
+  hash: string
+  /**
+   * The referrer of the page
+   * @example https://www.google.com/
+   */
+  referrer: string
+  /**
+   * The title of the page
+   * @example Segment - Documentation
+   */
+  title: string
+}
+
+/**
+ * The base data that all web signal data must have
+ */
+export interface BaseWebData {
+  page: PageData
+}
+
 export interface RawSignal<T extends SignalTypes, Data> extends BaseSignal {
   type: T
-  data: Data
+  data: BaseWebData & Data
   metadata?: Record<string, any>
 }
 export type InteractionData = ClickData | SubmitData | ChangeData

packages/signals/signals/README.md

@@ -59,10 +59,13 @@ analytics.load({
 ```ts
 import { signalsPlugin } from './analytics' // assuming you exported your plugin instance.
 
-signalsPlugin.addSignal({
-  type: 'userDefined',
-  data: { foo: 'bar' }
-})
+signalsPlugin.addSignal({ someData: 'foo' }) 
+
+// emits a signal with the following shape
+{ 
+  type: 'userDefined' 
+  data: { someData: 'foo', ...  }
+}
 ```
 
 ### Debugging

packages/signals/signals/src/core/analytics-service/__tests__/analytics-service.test.ts

@@ -38,20 +38,20 @@ describe(AnalyticsService, () => {
       middleware({ payload: { obj: mockEvent }, next: jest.fn() })
 
       expect(mockSignalEmitter.emit).toHaveBeenCalledTimes(1)
-      expect(mockSignalEmitter.emit.mock.calls[0]).toMatchInlineSnapshot(`
-        [
-          {
-            "data": {
-              "rawEvent": {
-                "context": {
-                  "foo": 123,
-                },
-                "type": "track",
+      const call = mockSignalEmitter.emit.mock.calls[0][0]
+      delete call.data.page
+      expect(call).toMatchInlineSnapshot(`
+        {
+          "data": {
+            "rawEvent": {
+              "context": {
+                "foo": 123,
               },
+              "type": "track",
             },
-            "type": "instrumentation",
           },
-        ]
+          "type": "instrumentation",
+        }
       `)
     })
     it('should not emit signals if the event is a Signal event', async () => {