Skip to content

Commit

Permalink
[HEAP] update browser destination code to load heap js v5 script (#2665)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
cpsoinos authored Jan 20, 2025
1 parent b12df36 commit b662218
Show file tree
Hide file tree
Showing 8 changed files with 213 additions and 59 deletions.
Original file line number Diff line number Diff line change
@@ -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 = [
{
Expand All @@ -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,
Expand All @@ -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`)
})
})

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
@@ -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] })
Expand All @@ -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] })
Expand All @@ -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] })
Expand Down
50 changes: 31 additions & 19 deletions packages/browser-destinations/destinations/heap/src/index.ts
Original file line number Diff line number Diff line change
@@ -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
}
}
Expand Down Expand Up @@ -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
},
Expand All @@ -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
},
Expand Down
69 changes: 69 additions & 0 deletions packages/browser-destinations/destinations/heap/src/init-script.ts
Original file line number Diff line number Diff line change
@@ -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)
}
Original file line number Diff line number Diff line change
@@ -1,23 +1,43 @@
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
},
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,
Expand All @@ -41,7 +61,7 @@ export const trackEventSubscription: Subscription = {
}
}

export const identifyUserSubscription: Subscription = {
export const identifyUserSubscription = {
partnerAction: 'identifyUser',
name: 'Identify User',
enabled: true,
Expand All @@ -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, {})
}
Loading

0 comments on commit b662218

Please sign in to comment.