Integrate @github/hydro-analytics-client for cross-subdomain tracking (#59364)

Author: heiskr

package-lock.json

@@ -157,6 +157,7 @@
   "dependencies": {
     "@elastic/elasticsearch": "8.19.1",
     "@github/failbot": "0.8.3",
+    "@github/hydro-analytics-client": "^2.3.3",
     "@gr2m/gray-matter": "4.0.3-with-pr-137",
     "@horizon-rs/language-guesser": "0.1.1",
     "@octokit/graphql": "9.0.1",

package.json

@@ -6,6 +6,7 @@ import { isLoggedIn } from '@/frame/components/hooks/useHasAccount'
 import { getExperimentVariationForContext } from './experiments/experiment'
 import { EventType, EventPropsByType } from '../types'
 import { isHeadless } from './is-headless'
+import { sendHydroAnalyticsEvent, getOctoClientId } from './hydro-analytics'
 
 const COOKIE_NAME = '_docs-events'
 
@@ -114,6 +115,7 @@ export function sendEvent<T extends EventType>({
       content_type: getMetaContent('page-content-type'),
       status: Number(getMetaContent('status') || 0),
       is_logged_in: isLoggedIn(),
+      octo_client_id: getOctoClientId(),
 
       // Device information
       // os, os_version, browser, browser_version:
@@ -152,6 +154,9 @@ export function sendEvent<T extends EventType>({
 
   queueEvent(body)
 
+  // Send events to hydro-analytics-client for cross-subdomain tracking
+  sendHydroAnalyticsEvent(body)
+
   if (type === EventType.exit) {
     flushQueue()
   }

src/events/components/events.ts

@@ -0,0 +1,98 @@
+/**
+ * Integration with @github/hydro-analytics-client for cross-subdomain tracking.
+ *
+ * This sends events to collector.githubapp.com alongside our existing analytics.
+ * The client auto-collects: page, title, client_id, referrer, user_agent,
+ * screen_resolution, browser_resolution, browser_languages, pixel_ratio, timestamp, tz_seconds
+ *
+ * We send all other docs-specific context fields, including:
+ * - path_language, path_version, path_product, path_article
+ * - page_document_type, page_type, content_type
+ * - color_mode_preference, is_logged_in, experiment_variation, is_headless
+ * - event_id, page_event_id, octo_client_id
+ * - Plus any event-specific properties (exit metrics, link_url, etc.)
+ *
+ * All functions are wrapped in try/catch to ensure that issues with the
+ * hydro-analytics-client or collector don't affect our primary analytics.
+ */
+
+import {
+  AnalyticsClient,
+  getOrCreateClientId as hydroGetOrCreateClientId,
+} from '@github/hydro-analytics-client'
+import { EventType } from '../types'
+
+/**
+ * Safe wrapper around hydro-analytics-client's getOrCreateClientId.
+ * Returns undefined if the client fails for any reason.
+ */
+export function getOctoClientId(): string | undefined {
+  try {
+    return hydroGetOrCreateClientId()
+  } catch (error) {
+    console.log('hydro-analytics-client getOctoClientId error:', error)
+    return undefined
+  }
+}
+
+const hydroClient = new AnalyticsClient({
+  collectorUrl: 'https://collector.githubapp.com/docs/collect',
+  clientId: getOctoClientId(),
+})
+
+// Fields that hydro-analytics-client already collects automatically
+const AUTO_COLLECTED_FIELDS = new Set([
+  'referrer',
+  'user_agent',
+  'viewport_width',
+  'viewport_height',
+  'screen_width',
+  'screen_height',
+  'pixel_ratio',
+  'timezone',
+  'user_language',
+  'href',
+  'title',
+])
+
+/**
+ * Flatten a nested event body into a single-level context object,
+ * excluding fields that hydro-analytics-client already auto-collects.
+ */
+export function prepareData(body: Record<string, unknown>): {
+  type: string
+  context: Record<string, string>
+} {
+  const { context: nestedContext, type, ...rest } = body
+  const flattened = {
+    ...((nestedContext as Record<string, unknown>) || {}),
+    ...rest,
+  }
+  const context = Object.fromEntries(
+    Object.entries(flattened)
+      .filter(([, value]) => value != null)
+      .filter(([key]) => !AUTO_COLLECTED_FIELDS.has(key))
+      .map(([key, value]) => [key, String(value)]),
+  )
+  return { type: typeof type === 'string' ? type : 'unknown', context }
+}
+
+/**
+ * Send an event to hydro-analytics-client.
+ * For page events, sends as a page view. For all other events, sends as a custom event.
+ *
+ * This is wrapped in try/catch to ensure that if the hydro collector is down
+ * or errors, it doesn't affect our primary analytics pipeline.
+ */
+export function sendHydroAnalyticsEvent(body: Record<string, unknown>): void {
+  try {
+    const { type, context } = prepareData(body)
+    if (type === EventType.page) {
+      hydroClient.sendPageView(context)
+    } else {
+      hydroClient.sendEvent(type, context)
+    }
+  } catch (error) {
+    console.log('hydro-analytics-client error:', error)
+  }
+}

src/events/components/hydro-analytics.ts

@@ -124,6 +124,11 @@ const context = {
       type: 'boolean',
       description: 'The cookie value of staffonly',
     },
+    octo_client_id: {
+      type: 'string',
+      description:
+        'The _octo cookie client ID for cross-subdomain tracking with github.com analytics.',
+    },
 
     // Device information
     os: {

src/events/lib/schema.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'vitest'
+import { prepareData } from '../components/hydro-analytics'
+
+describe('prepareData', () => {
+  test('flattens nested context into top level', () => {
+    const body = {
+      type: 'page',
+      context: {
+        event_id: '123',
+        path_language: 'en',
+      },
+    }
+    const result = prepareData(body)
+    expect(result.type).toBe('page')
+    expect(result.context.event_id).toBe('123')
+    expect(result.context.path_language).toBe('en')
+  })
+
+  test('includes top-level props alongside context', () => {
+    const body = {
+      type: 'exit',
+      context: { event_id: '123' },
+      exit_scroll_length: 0.75,
+    }
+    const result = prepareData(body)
+    expect(result.type).toBe('exit')
+    expect(result.context.event_id).toBe('123')
+    expect(result.context.exit_scroll_length).toBe('0.75')
+  })
+
+  test('filters out auto-collected fields', () => {
+    const body = {
+      type: 'page',
+      context: {
+        event_id: '123',
+        referrer: 'https://google.com',
+        user_agent: 'Mozilla/5.0',
+        viewport_width: 1024,
+        title: 'Test Page',
+        path_language: 'en',
+      },
+    }
+    const result = prepareData(body)
+    expect(result.context.event_id).toBe('123')
+    expect(result.context.path_language).toBe('en')
+    expect(result.context.referrer).toBeUndefined()
+    expect(result.context.user_agent).toBeUndefined()
+    expect(result.context.viewport_width).toBeUndefined()
+    expect(result.context.title).toBeUndefined()
+  })
+
+  test('filters out null and undefined values', () => {
+    const body = {
+      type: 'page',
+      context: {
+        event_id: '123',
+        path_language: null,
+        path_version: undefined,
+        path_product: 'actions',
+      },
+    }
+    const result = prepareData(body)
+    expect(result.context.event_id).toBe('123')
+    expect(result.context.path_product).toBe('actions')
+    expect(result.context.path_language).toBeUndefined()
+    expect(result.context.path_version).toBeUndefined()
+  })
+
+  test('converts all values to strings', () => {
+    const body = {
+      type: 'exit',
+      context: {
+        status: 200,
+        is_logged_in: true,
+        is_headless: false,
+      },
+    }
+    const result = prepareData(body)
+    expect(result.context.status).toBe('200')
+    expect(result.context.is_logged_in).toBe('true')
+    expect(result.context.is_headless).toBe('false')
+  })
+
+  test('defaults type to unknown if not a string', () => {
+    const body = {
+      type: 123,
+      context: { event_id: '123' },
+    }
+    const result = prepareData(body)
+    expect(result.type).toBe('unknown')
+  })
+
+  test('handles missing context gracefully', () => {
+    const body = {
+      type: 'page',
+      exit_scroll_length: 0.5,
+    }
+    const result = prepareData(body)
+    expect(result.type).toBe('page')
+    expect(result.context.exit_scroll_length).toBe('0.5')
+  })
+})

src/events/tests/hydro-analytics.ts

@@ -41,6 +41,7 @@ export type EventProps = {
     is_logged_in: boolean
     dotcom_user: string
     is_staff: boolean
+    octo_client_id?: string
     os: string
     os_version: string
     browser: string

src/events/types.ts

@@ -28,7 +28,9 @@ const DEFAULT_OPTIONS = {
       prefetchSrc: ["'self'"],
       // When doing local dev, especially in Safari, you need to add `ws:`
       // which NextJS uses for the hot module reloading.
-      connectSrc: ["'self'", isDev && 'ws:'].filter(Boolean) as string[],
+      connectSrc: ["'self'", 'https://collector.githubapp.com', isDev && 'ws:'].filter(
+        Boolean,
+      ) as string[],
       fontSrc: ["'self'", 'data:'],
       imgSrc: [...GITHUB_DOMAINS, 'data:', 'placehold.it'],
       objectSrc: ["'self'"],