feat: support custom global analytics key (#928)

Author: oscb

.changeset/mean-apricots-hammer.md

@@ -0,0 +1,6 @@
+---
+'@segment/analytics-next': minor
+'@segment/analytics-core': minor
+---
+
+Adds `globalAnalyticsKey` option for setting custom global window buffers

examples/with-next-js/pages/partytown/index.tsx

@@ -44,7 +44,7 @@ const WebWorker: React.FC = () => {
           }}
           value="Track!"
           onClick={() => {
-            void window.analytics.track(
+            void (window as any).analytics.track(
               'Party Town Click',
               { myProp: 'hello' },
               { traits: { age: 8 } }

packages/browser/src/browser/__tests__/analytics-pre-init.integration.test.ts

@@ -278,6 +278,31 @@ describe('Pre-initialization', () => {
       expect(onTrackCb).toBeCalledWith('foo', {}, undefined)
       expect(onTrackCb).toBeCalledWith('bar', {}, undefined)
     })
+    test('events can be buffered under a custom window key', async () => {
+      const onTrackCb = jest.fn()
+      const onTrack = ['on', 'track', onTrackCb]
+      const track = ['track', 'foo']
+      const track2 = ['track', 'bar']
+      const identify = ['identify']
+
+      ;(window as any).segment = [onTrack, track, track2, identify]
+
+      await AnalyticsBrowser.standalone(writeKey, {
+        globalAnalyticsKey: 'segment',
+      })
+
+      await sleep(100) // the snippet does not return a promise (pre-initialization) ... it sometimes has a callback as the third argument.
+      expect(trackSpy).toBeCalledWith('foo')
+      expect(trackSpy).toBeCalledWith('bar')
+      expect(trackSpy).toBeCalledTimes(2)
+
+      expect(identifySpy).toBeCalledTimes(1)
+
+      expect(getOnSpyCalls('track').length).toBe(1)
+      expect(onTrackCb).toBeCalledTimes(2) // gets called once for each track event
+      expect(onTrackCb).toBeCalledWith('foo', {}, undefined)
+      expect(onTrackCb).toBeCalledWith('bar', {}, undefined)
+    })
   })
 
   describe('Emitter methods', () => {

packages/browser/src/browser/__tests__/cdn.test.ts

@@ -1,4 +1,4 @@
-import { AnalyticsBrowser } from '../..'
+import { AnalyticsBrowser, getGlobalAnalytics } from '../..'
 import unfetch from 'unfetch'
 import { createSuccess } from '../../test-helpers/factories'
 import { setGlobalCDNUrl } from '../../lib/parse-cdn'
@@ -45,5 +45,5 @@ it('if CDN is overridden, sets the overridden CDN global variable', async () =>
     writeKey,
     cdnURL: mockCdn,
   })
-  expect(window.analytics._cdn).toBe(mockCdn)
+  expect(getGlobalAnalytics()?._cdn).toBe(mockCdn)
 })

packages/browser/src/browser/__tests__/integration.test.ts

@@ -23,6 +23,7 @@ import {
   highEntropyTestData,
   lowEntropyTestData,
 } from '../../test-helpers/fixtures/client-hints'
+import { getGlobalAnalytics } from '../..'
 
 let fetchCalls: ReturnType<typeof parseFetchCall>[] = []
 
@@ -200,7 +201,7 @@ describe('Initialization', () => {
           {
             ...xt,
             load: async () => {
-              expect(window.analytics).toBeUndefined()
+              expect(getGlobalAnalytics()).toBeUndefined()
               expect(getCDN()).toContain(overriddenCDNUrl)
             },
           },
@@ -212,6 +213,57 @@ describe('Initialization', () => {
     })
   })
 
+  describe('globalAnalyticsKey', () => {
+    const overrideKey = 'myKey'
+    const buffer = {
+      foo: 'bar',
+    }
+
+    beforeEach(() => {
+      ;(window as any)[overrideKey] = buffer
+    })
+    afterEach(() => {
+      delete (window as any)[overrideKey]
+    })
+    it('should default to window.analytics', async () => {
+      const defaultObj = { original: 'default' }
+      ;(window as any)['analytics'] = defaultObj
+
+      await AnalyticsBrowser.load({
+        writeKey,
+        plugins: [
+          {
+            ...xt,
+            load: async () => {
+              expect(getGlobalAnalytics()).toBe(defaultObj)
+            },
+          },
+        ],
+      })
+      expect.assertions(1)
+    })
+
+    it('should set the global window key for the analytics buffer with the setting option', async () => {
+      await AnalyticsBrowser.load(
+        {
+          writeKey,
+          plugins: [
+            {
+              ...xt,
+              load: async () => {
+                expect(getGlobalAnalytics()).toBe(buffer)
+              },
+            },
+          ],
+        },
+        {
+          globalAnalyticsKey: overrideKey,
+        }
+      )
+      expect.assertions(1)
+    })
+  })
+
   describe('Load options', () => {
     it('gets high entropy client hints if set', async () => {
       ;(window.navigator as any).userAgentData = {

packages/browser/src/browser/__tests__/standalone-analytics.test.ts

@@ -1,13 +1,14 @@
 import jsdom, { JSDOM } from 'jsdom'
-import { InitOptions } from '../../'
+import { InitOptions, getGlobalAnalytics } from '../../'
 import { AnalyticsBrowser, loadLegacySettings } from '../../browser'
 import { snippet } from '../../tester/__fixtures__/segment-snippet'
-import { install, AnalyticsStandalone } from '../standalone-analytics'
+import { install } from '../standalone-analytics'
 import unfetch from 'unfetch'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
 import { sleep } from '../../lib/sleep'
 import * as Factory from '../../test-helpers/factories'
 import { EventQueue } from '../../core/queue/event-queue'
+import { AnalyticsStandalone } from '../standalone-interface'
 
 const track = jest.fn()
 const identify = jest.fn()
@@ -142,7 +143,7 @@ describe('standalone bundle', () => {
       .mockImplementation((): Promise<Response> => fetchSettings)
     const mockCdn = 'http://my-overridden-cdn.com'
 
-    window.analytics._cdn = mockCdn
+    getGlobalAnalytics()!._cdn = mockCdn
     await loadLegacySettings(segmentDotCom)
 
     expect(unfetch).toHaveBeenCalledWith(expect.stringContaining(mockCdn))
@@ -262,7 +263,7 @@ describe('standalone bundle', () => {
 
     // register is called after flushPreBuffer in `loadAnalytics`
     register.mockImplementationOnce(() =>
-      window.analytics.track('race conditions', { foo: 'bar' })
+      getGlobalAnalytics()?.track('race conditions', { foo: 'bar' })
     )
 
     await install()

packages/browser/src/browser/__tests__/standalone.test.ts

@@ -4,6 +4,7 @@ import { LegacySettings } from '..'
 import { pWhile } from '../../lib/p-while'
 import { snippet } from '../../tester/__fixtures__/segment-snippet'
 import * as Factory from '../../test-helpers/factories'
+import { getGlobalAnalytics } from '../..'
 
 const cdnResponse: LegacySettings = {
   integrations: {
@@ -86,11 +87,11 @@ describe('standalone bundle', () => {
     await import('../standalone')
 
     await pWhile(
-      () => window.analytics?.initialized !== true,
+      () => getGlobalAnalytics()?.initialized !== true,
       () => {}
     )
 
-    expect(window.analytics).not.toBeUndefined()
-    expect(window.analytics.initialized).toBe(true)
+    expect(getGlobalAnalytics()).not.toBeUndefined()
+    expect(getGlobalAnalytics()?.initialized).toBe(true)
   })
 })

packages/browser/src/browser/index.ts

@@ -30,6 +30,7 @@ import { popSnippetWindowBuffer } from '../core/buffer/snippet'
 import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
 import { attachInspector } from '../core/inspector'
 import { Stats } from '../core/stats'
+import { setGlobalAnalyticsKey } from '../lib/global-analytics-helper'
 
 export interface LegacyIntegrationConfiguration {
   /* @deprecated - This does not indicate browser types anymore */
@@ -303,6 +304,8 @@ async function loadAnalytics(
   options: InitOptions = {},
   preInitBuffer: PreInitMethodCallBuffer
 ): Promise<[Analytics, Context]> {
+  if (options.globalAnalyticsKey)
+    setGlobalAnalyticsKey(options.globalAnalyticsKey)
   // this is an ugly side-effect, but it's for the benefits of the plugins that get their cdn via getCDN()
   if (settings.cdnURL) setGlobalCDNUrl(settings.cdnURL)
 

packages/browser/src/browser/standalone-analytics.ts

@@ -1,30 +1,19 @@
-import { Analytics, InitOptions } from '../core/analytics'
 import { AnalyticsBrowser } from '.'
 import { embeddedWriteKey } from '../lib/embedded-write-key'
-
-export interface AnalyticsSnippet extends AnalyticsStandalone {
-  load: (writeKey: string, options?: InitOptions) => void
-}
-
-export interface AnalyticsStandalone extends Analytics {
-  _loadOptions?: InitOptions
-  _writeKey?: string
-  _cdn?: string
-}
-
-declare global {
-  interface Window {
-    analytics: AnalyticsSnippet
-  }
-}
+import { AnalyticsSnippet } from './standalone-interface'
+import {
+  getGlobalAnalytics,
+  setGlobalAnalytics,
+} from '../lib/global-analytics-helper'
 
 function getWriteKey(): string | undefined {
   if (embeddedWriteKey()) {
     return embeddedWriteKey()
   }
 
-  if (window.analytics._writeKey) {
-    return window.analytics._writeKey
+  const analytics = getGlobalAnalytics()
+  if (analytics?._writeKey) {
+    return analytics._writeKey
   }
 
   const regex = /http.*\/analytics\.js\/v1\/([^/]*)(\/platform)?\/analytics.*/
@@ -59,16 +48,15 @@ function getWriteKey(): string | undefined {
 
 export async function install(): Promise<void> {
   const writeKey = getWriteKey()
-  const options = window.analytics?._loadOptions ?? {}
+  const options = getGlobalAnalytics()?._loadOptions ?? {}
   if (!writeKey) {
     console.error(
       'Failed to load Write Key. Make sure to use the latest version of the Segment snippet, which can be found in your source settings.'
     )
     return
   }
 
-  window.analytics = (await AnalyticsBrowser.standalone(
-    writeKey,
-    options
-  )) as AnalyticsSnippet
+  setGlobalAnalytics(
+    (await AnalyticsBrowser.standalone(writeKey, options)) as AnalyticsSnippet
+  )
 }

packages/browser/src/browser/standalone-interface.ts

@@ -0,0 +1,11 @@
+import { Analytics, InitOptions } from '../core/analytics'
+
+export interface AnalyticsSnippet extends AnalyticsStandalone {
+  load: (writeKey: string, options?: InitOptions) => void
+}
+
+export interface AnalyticsStandalone extends Analytics {
+  _loadOptions?: InitOptions
+  _writeKey?: string
+  _cdn?: string
+}