From b66221810eadb8d0b7661ed300f4cfdd8d112fd5 Mon Sep 17 00:00:00 2001 From: Corey Psoinos Date: Mon, 20 Jan 2025 07:06:15 -0500 Subject: [PATCH] [HEAP] update browser destination code to load heap js v5 script (#2665) * feat(heap): update browser destination code to load heap js v5 script * remove try/catch fallback for self-hosted * update tests * fix tests * apply deprecated trackingServer config value for backward compatibility * remove non-functional script loading mock * better backward compatibility with hjsv4 * assert heap.envId, not heap.appid --- .../heap/src/__tests__/index.test.ts | 53 +++++++++++--- .../destinations/heap/src/generated-types.ts | 12 ++-- .../src/identifyUser/__tests__/index.test.ts | 10 +-- .../destinations/heap/src/index.ts | 50 +++++++++----- .../destinations/heap/src/init-script.ts | 69 +++++++++++++++++++ .../destinations/heap/src/test-utilities.ts | 36 +++++++--- .../src/trackEvent/__tests__/index.test.ts | 8 +-- .../destinations/heap/src/types.ts | 34 ++++++++- 8 files changed, 213 insertions(+), 59 deletions(-) create mode 100644 packages/browser-destinations/destinations/heap/src/init-script.ts diff --git a/packages/browser-destinations/destinations/heap/src/__tests__/index.test.ts b/packages/browser-destinations/destinations/heap/src/__tests__/index.test.ts index 3153c7c418..3a19cbc640 100644 --- a/packages/browser-destinations/destinations/heap/src/__tests__/index.test.ts +++ b/packages/browser-destinations/destinations/heap/src/__tests__/index.test.ts @@ -1,6 +1,11 @@ import { Analytics, Context } from '@segment/analytics-next' import heapDestination, { destination } from '../index' -import { HEAP_TEST_ENV_ID, mockHeapJsHttpRequest } from '../test-utilities' +import { HEAP_TEST_ENV_ID } from '../test-utilities' +import { loadScript } from '@segment/browser-destination-runtime/load-script' +import { resolveWhen } from '@segment/browser-destination-runtime/resolve-when' + +jest.mock('@segment/browser-destination-runtime/load-script') +jest.mock('@segment/browser-destination-runtime/resolve-when') const subscriptions = [ { @@ -13,21 +18,35 @@ const subscriptions = [ ] describe('Heap', () => { + beforeAll(() => { + ;(loadScript as jest.Mock).mockResolvedValue(true) + ;(resolveWhen as jest.Mock).mockResolvedValue(true) + }) + + beforeEach(() => { + // Reset global state + // @ts-expect-error + delete window.heap + }) + + afterEach(async () => { + jest.clearAllMocks() + }) + test('loading', async () => { jest.spyOn(destination, 'initialize') - mockHeapJsHttpRequest() - const [event] = await heapDestination({ appId: HEAP_TEST_ENV_ID, subscriptions }) await event.load(Context.system(), {} as Analytics) + expect(destination.initialize).toHaveBeenCalled() - expect(window.heap.appid).toEqual(HEAP_TEST_ENV_ID) + expect(window.heap.envId).toEqual(HEAP_TEST_ENV_ID) + expect(loadScript).toHaveBeenCalledWith(`https://cdn.us.heap-api.com/config/${HEAP_TEST_ENV_ID}/heap_config.js`) }) - test('loading with cdn', async () => { - jest.spyOn(destination, 'initialize') - mockHeapJsHttpRequest() + test('loading classic SDK with custom hostname', async () => { + jest.spyOn(destination, 'initialize') const [event] = await heapDestination({ appId: HEAP_TEST_ENV_ID, @@ -37,7 +56,25 @@ describe('Heap', () => { }) await event.load(Context.system(), {} as Analytics) + + expect(destination.initialize).toHaveBeenCalled() + expect(window.heap.envId).toEqual(HEAP_TEST_ENV_ID) + expect(loadScript).toHaveBeenCalledWith(`https://cdn.heapanalytics.com/js/heap-${HEAP_TEST_ENV_ID}.js`) + }) + + test('loading latest SDK with custom hostname', async () => { + jest.spyOn(destination, 'initialize') + + const [event] = await heapDestination({ + appId: HEAP_TEST_ENV_ID, + subscriptions, + hostname: 'cdn.heapanalytics.com' + }) + + await event.load(Context.system(), {} as Analytics) + expect(destination.initialize).toHaveBeenCalled() - expect(window.heap.appid).toEqual(HEAP_TEST_ENV_ID) + expect(window.heap.envId).toEqual(HEAP_TEST_ENV_ID) + expect(loadScript).toHaveBeenCalledWith(`https://cdn.heapanalytics.com/config/${HEAP_TEST_ENV_ID}/heap_config.js`) }) }) diff --git a/packages/browser-destinations/destinations/heap/src/generated-types.ts b/packages/browser-destinations/destinations/heap/src/generated-types.ts index 70f8bdb0c5..25c4454185 100644 --- a/packages/browser-destinations/destinations/heap/src/generated-types.ts +++ b/packages/browser-destinations/destinations/heap/src/generated-types.ts @@ -6,19 +6,23 @@ export interface Settings { */ appId: string /** - * 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). */ disableTextCapture?: boolean /** - * 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). */ secureCookie?: boolean /** - * 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. */ trackingServer?: string /** - * 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. 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). + */ + ingestServer?: string + /** + * 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). */ hostname?: string /** diff --git a/packages/browser-destinations/destinations/heap/src/identifyUser/__tests__/index.test.ts b/packages/browser-destinations/destinations/heap/src/identifyUser/__tests__/index.test.ts index 5e23b8589f..be78d96e2e 100644 --- a/packages/browser-destinations/destinations/heap/src/identifyUser/__tests__/index.test.ts +++ b/packages/browser-destinations/destinations/heap/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] }) diff --git a/packages/browser-destinations/destinations/heap/src/index.ts b/packages/browser-destinations/destinations/heap/src/index.ts index 6f03e1f921..c81e39f749 100644 --- a/packages/browser-destinations/destinations/heap/src/index.ts +++ b/packages/browser-destinations/destinations/heap/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 = { 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 = { 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 }, diff --git a/packages/browser-destinations/destinations/heap/src/init-script.ts b/packages/browser-destinations/destinations/heap/src/init-script.ts new file mode 100644 index 0000000000..34f20b9b59 --- /dev/null +++ b/packages/browser-destinations/destinations/heap/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) +} diff --git a/packages/browser-destinations/destinations/heap/src/test-utilities.ts b/packages/browser-destinations/destinations/heap/src/test-utilities.ts index 1f9f03ae09..e7d5801201 100644 --- a/packages/browser-destinations/destinations/heap/src/test-utilities.ts +++ b/packages/browser-destinations/destinations/heap/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, {}) -} diff --git a/packages/browser-destinations/destinations/heap/src/trackEvent/__tests__/index.test.ts b/packages/browser-destinations/destinations/heap/src/trackEvent/__tests__/index.test.ts index d7ead7d208..f6f1a24fb1 100644 --- a/packages/browser-destinations/destinations/heap/src/trackEvent/__tests__/index.test.ts +++ b/packages/browser-destinations/destinations/heap/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 = ( diff --git a/packages/browser-destinations/destinations/heap/src/types.ts b/packages/browser-destinations/destinations/heap/src/types.ts index 05b9014b8a..92d2854095 100644 --- a/packages/browser-destinations/destinations/heap/src/types.ts +++ b/packages/browser-destinations/destinations/heap/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 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 & { 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'