@segment/analytics-browser-actions-heap 1.70.1 → 1.72.0

package/src/identifyUser/__tests__/index.test.ts

@@ -1,15 +1,9 @@
 import { Analytics, Context } from '@segment/analytics-next'
-import {
-  createMockedHeapJsSdk,
-  HEAP_TEST_ENV_ID,
-  identifyUserSubscription,
-  mockHeapJsHttpRequest
-} from '../../test-utilities'
+import { createMockedHeapJsSdk, HEAP_TEST_ENV_ID, identifyUserSubscription } from '../../test-utilities'
 import heapDestination from '../../index'
 
 describe('#identify', () => {
   it('should not call identify if user id is not provided and anonymous user id is provided', async () => {
-    mockHeapJsHttpRequest()
     window.heap = createMockedHeapJsSdk()
 
     const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })
@@ -31,7 +25,6 @@ describe('#identify', () => {
   })
 
   it('should call identify if user id is provided', async () => {
-    mockHeapJsHttpRequest()
     window.heap = createMockedHeapJsSdk()
 
     const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })
@@ -53,7 +46,6 @@ describe('#identify', () => {
   })
 
   it('should call addUserProprties if traits are provided', async () => {
-    mockHeapJsHttpRequest()
     window.heap = createMockedHeapJsSdk()
 
     const [identifyUser] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions: [identifyUserSubscription] })

package/src/index.ts

@@ -1,14 +1,16 @@
 import type { Settings } from './generated-types'
 import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
 import { browserDestination } from '@segment/browser-destination-runtime/shim'
-import { HeapApi, UserConfig } from './types'
+import type { HeapApi, HeapMethods, UserConfig } from './types'
 import { defaultValues } from '@segment/actions-core'
 import trackEvent from './trackEvent'
 import identifyUser from './identifyUser'
+import { initScript } from './init-script'
 import { isDefined } from './utils'
 
 declare global {
   interface Window {
+    heapReadyCb: Array<{ name: HeapMethods; fn: () => void }>
     heap: HeapApi
   }
 }
@@ -46,28 +48,35 @@ export const destination: BrowserDestinationDefinition<Settings, HeapApi> = {
     disableTextCapture: {
       label: 'Global data redaction via Disabling Text Capture',
       description:
-        'Setting to true will redact all target text on your website. For more information visit the heap [docs page](https://developers.heap.io/docs/web#global-data-redaction-via-disabling-text-capture).',
+        'Setting to true will redact all target text on your website. For more information visit the Heap [docs page](https://developers.heap.io/docs/web#global-data-redaction-via-disabling-text-capture).',
       type: 'boolean',
       required: false
     },
     secureCookie: {
       label: 'Secure Cookie',
       description:
-        'This option is turned off by default to accommodate websites not served over HTTPS. If your application uses HTTPS, we recommend enabling secure cookies to prevent Heap cookies from being observed by unauthorized parties. For more information visit the heap [docs page](https://developers.heap.io/docs/web#securecookie).',
+        'This option is turned off by default to accommodate websites not served over HTTPS. If your application uses HTTPS, we recommend enabling secure cookies to prevent Heap cookies from being observed by unauthorized parties. For more information visit the Heap [docs page](https://developers.heap.io/docs/web#securecookie).',
       type: 'boolean',
       required: false
     },
     trackingServer: {
-      label: 'Tracking Server',
+      label: 'Tracking Server (deprecated)',
       description:
-        'This is an optional setting. This is used to set up first-party data collection. For most cased this should not be set. For more information visit the heap [docs page](https://developers.heap.io/docs/set-up-first-party-data-collection-in-heap).',
+        'This is an optional setting. This is used to set up first-party data collection. For most cased this should not be set. For more information visit the Heap [docs page](https://developers.heap.io/docs/set-up-first-party-data-collection-in-heap). This field is deprecated in favor of `ingestServer`. If `trackingServer` is set and `ingestServer` is not set, then the Classic SDK will be loaded. If both are set, `ingestServer` will take precedence, and the latest stable version of the Heap SDK will be loaded.',
+      type: 'string',
+      required: false
+    },
+    ingestServer: {
+      label: 'Ingest Server',
+      description:
+        'This is an optional setting. This is used to set up first-party data collection. For most cased this should not be set. For more information visit the Heap [docs page](https://developers.heap.io/docs/web#ingestserver).',
       type: 'string',
       required: false
     },
     hostname: {
       label: 'Hostname',
       description:
-        'This is an optional setting used to set the host that loads heap-js. This setting is used when heapJS is self-hosted. In most cased this should be left unset. The hostname should not contain https or app id it will be populated like so: https://${hostname}/js/heap-${appId}.js. For more information visit the heap [docs page](https://developers.heap.io/docs/self-hosting-heapjs).',
+        'This is an optional setting used to set the host that loads the Heap SDK. This setting is used when the Heap SDK is self-hosted. In most cased this should be left unset. The hostname should not contain https or app id. When _both_ `hostname` and `trackingServer` are set, the Classic SDK will be loaded via: `https://${hostname}/js/heap-${appId}.js`. If `hostname` is set and `trackingServer` is not set, then the latest version of the Heap SDK will be loaded via: `https://${settings.hostname}/config/${settings.appId}/heap_config.js`. For more information visit the Heap [docs page](https://developers.heap.io/docs/self-hosting-heapjs).',
       type: 'string',
       required: false
     },
@@ -87,26 +96,29 @@ export const destination: BrowserDestinationDefinition<Settings, HeapApi> = {
 
     const config: UserConfig = {
       disableTextCapture: settings.disableTextCapture || false,
-      secureCookie: settings.secureCookie || false
+      secureCookie: settings.secureCookie || false,
+      ...(settings.ingestServer && { ingestServer: settings.ingestServer }),
+      // For backward compatibility. See https://developers.heap.io/docs/web#ingestserver
+      ...(settings.trackingServer && { trackingServer: settings.trackingServer })
     }
 
-    if (settings.trackingServer) {
-      config.trackingServer = settings.trackingServer
-    }
-
-    // heap.appid and heap.config must be set before loading heap.js.
-    window.heap = window.heap || []
-    window.heap.appid = settings.appId
-    window.heap.config = config
+    initScript(settings.appId, config)
 
-    if (isDefined(settings.hostname)) {
+    // if both hostname and trackingServer are set, load classic SDK from hostname
+    if (isDefined(settings.hostname) && isDefined(settings.trackingServer)) {
       await deps.loadScript(`https://${settings.hostname}/js/heap-${settings.appId}.js`)
-    } else {
-      await deps.loadScript(`https://cdn.heapanalytics.com/js/heap-${settings.appId}.js`)
+    }
+    // if only hostname is set, load latest version of SDK from hostname
+    else if (isDefined(settings.hostname) && !isDefined(settings.trackingServer)) {
+      await deps.loadScript(`https://${settings.hostname}/config/${settings.appId}/heap_config.js`)
+    }
+    // default to loading latest version of SDK from heap CDN
+    else {
+      await deps.loadScript(`https://cdn.us.heap-api.com/config/${settings.appId}/heap_config.js`)
     }
 
     // Explained here: https://stackoverflow.com/questions/14859058/why-does-the-segment-io-loader-script-push-method-names-args-onto-a-queue-which
-    await deps.resolveWhen(() => Object.prototype.hasOwnProperty.call(window, 'heap'), 100)
+    await deps.resolveWhen(() => window.heap.loaded === true, 300)
 
     return window.heap
   },

package/src/init-script.ts

@@ -0,0 +1,69 @@
+import type { HeapMethods, UserConfig } from './types'
+
+/**
+ * Initialize the Heap script with the provided environment ID and configuration.
+ */
+export const initScript = (envId: string, config: UserConfig) => {
+  // Ensure heapReadyCb exists on the window object
+  window.heapReadyCb = window.heapReadyCb || []
+
+  // Ensure heap exists on the window object
+  window.heap = window.heap || ({} as any)
+
+  window.heap.load = function (
+    envId: string,
+    clientConfig: UserConfig = { disableTextCapture: false, secureCookie: false }
+  ): void {
+    window.heap.envId = envId
+    window.heap.clientConfig = clientConfig
+    window.heap.clientConfig.shouldFetchServerConfig = false
+
+    // Define all Heap API methods and add them to the heap object
+    const methods: HeapMethods[] = [
+      'init',
+      'startTracking',
+      'stopTracking',
+      'track',
+      'resetIdentity',
+      'identify',
+      'identifyHashed',
+      'getSessionId',
+      'getUserId',
+      'getIdentity',
+      'addUserProperties',
+      'addEventProperties',
+      'removeEventProperty',
+      'clearEventProperties',
+      'addAccountProperties',
+      'addAdapter',
+      'addTransformer',
+      'addTransformerFn',
+      'onReady',
+      'addPageviewProperties',
+      'removePageviewProperty',
+      'clearPageviewProperties',
+      'trackPageview'
+    ]
+
+    const createMethodProxy = (methodName: HeapMethods) => {
+      return function (...args: any[]) {
+        // Push method calls to heapReadyCb until the script is fully loaded
+        window.heapReadyCb.push({
+          name: methodName,
+          fn: () => {
+            if (window.heap[methodName]) {
+              window.heap[methodName](...args)
+            }
+          }
+        })
+      }
+    }
+
+    // Proxy all methods to heap
+    for (const method of methods) {
+      window.heap[method] = createMethodProxy(method)
+    }
+  }
+
+  window.heap.load(envId, config)
+}

package/src/test-utilities.ts

@@ -1,12 +1,11 @@
-import { HeapApi } from './types'
-import { Subscription } from '@segment/browser-destination-runtime/types'
-import nock from 'nock'
+import type { HeapApi } from './types'
 
 export const HEAP_TEST_ENV_ID = '1'
 
 export const createMockedHeapJsSdk = (): HeapApi => {
   return {
     appid: HEAP_TEST_ENV_ID,
+    envId: HEAP_TEST_ENV_ID,
     config: {
       disableTextCapture: true,
       secureCookie: true
@@ -14,10 +13,31 @@ export const createMockedHeapJsSdk = (): HeapApi => {
     load: jest.fn(),
     track: jest.fn(),
     identify: jest.fn(),
-    addUserProperties: jest.fn()
+    addUserProperties: jest.fn(),
+    init: jest.fn(),
+    startTracking: jest.fn(),
+    stopTracking: jest.fn(),
+    resetIdentity: jest.fn(),
+    identifyHashed: jest.fn(),
+    getSessionId: jest.fn(),
+    getUserId: jest.fn(),
+    getIdentity: jest.fn(),
+    addEventProperties: jest.fn(),
+    removeEventProperty: jest.fn(),
+    clearEventProperties: jest.fn(),
+    addAccountProperties: jest.fn(),
+    addAdapter: jest.fn(),
+    addTransformer: jest.fn(),
+    addTransformerFn: jest.fn(),
+    onReady: jest.fn(),
+    addPageviewProperties: jest.fn(),
+    removePageviewProperty: jest.fn(),
+    clearPageviewProperties: jest.fn(),
+    trackPageview: jest.fn()
   }
 }
-export const trackEventSubscription: Subscription = {
+
+export const trackEventSubscription = {
   partnerAction: 'trackEvent',
   name: 'Track Event',
   enabled: true,
@@ -41,7 +61,7 @@ export const trackEventSubscription: Subscription = {
   }
 }
 
-export const identifyUserSubscription: Subscription = {
+export const identifyUserSubscription = {
   partnerAction: 'identifyUser',
   name: 'Identify User',
   enabled: true,
@@ -58,7 +78,3 @@ export const identifyUserSubscription: Subscription = {
     }
   }
 }
-
-export const mockHeapJsHttpRequest = (): void => {
-  nock('https://cdn.heapanalytics.com').get(`/js/heap-${HEAP_TEST_ENV_ID}.js`).reply(200, {})
-}

package/src/trackEvent/__tests__/index.test.ts

@@ -1,11 +1,6 @@
 import { Analytics, Context, Plugin } from '@segment/analytics-next'
 import heapDestination from '../../index'
-import {
-  createMockedHeapJsSdk,
-  HEAP_TEST_ENV_ID,
-  mockHeapJsHttpRequest,
-  trackEventSubscription
-} from '../../test-utilities'
+import { createMockedHeapJsSdk, HEAP_TEST_ENV_ID, trackEventSubscription } from '../../test-utilities'
 import { HEAP_SEGMENT_BROWSER_LIBRARY_NAME } from '../../constants'
 
 describe('#trackEvent', () => {
@@ -16,7 +11,6 @@ describe('#trackEvent', () => {
   let identifySpy: jest.SpyInstance
 
   beforeAll(async () => {
-    mockHeapJsHttpRequest()
     window.heap = createMockedHeapJsSdk()
 
     eventWithUnrolling = (

package/src/types.ts

@@ -1,5 +1,6 @@
 export type UserConfig = {
   trackingServer?: string
+  ingestServer?: string
   disableTextCapture: boolean
   secureCookie: boolean
 }
@@ -12,11 +13,40 @@ type EventProperties = {
   [key: string]: unknown
 }
 
-export type HeapApi = {
+export type HeapApi = Record<HeapMethods, (...args: any[]) => void> & {
   appid: string
+  envId: string
   track: (eventName: string, eventProperties: EventProperties, library?: string) => void
-  load: () => void
+  load: (envId: string, clientConfig?: UserConfig) => void
+  loaded?: boolean
   config: UserConfig
+  clientConfig?: Partial<UserConfig> & { shouldFetchServerConfig?: boolean }
   identify: (identity: string) => void
   addUserProperties: (properties: UserProperties) => void
 }
+
+// Define types for Heap methods
+export type HeapMethods =
+  | 'init'
+  | 'startTracking'
+  | 'stopTracking'
+  | 'track'
+  | 'resetIdentity'
+  | 'identify'
+  | 'identifyHashed'
+  | 'getSessionId'
+  | 'getUserId'
+  | 'getIdentity'
+  | 'addUserProperties'
+  | 'addEventProperties'
+  | 'removeEventProperty'
+  | 'clearEventProperties'
+  | 'addAccountProperties'
+  | 'addAdapter'
+  | 'addTransformer'
+  | 'addTransformerFn'
+  | 'onReady'
+  | 'addPageviewProperties'
+  | 'removePageviewProperty'
+  | 'clearPageviewProperties'
+  | 'trackPageview'