@ht-sdks/events-sdk-js-browser 1.2.0 → 1.3.0

package/src/index.ts

@@ -9,5 +9,6 @@ export * from './core/user'
 
 export type { HtEventsSnippet } from './browser/standalone-interface'
 export type { MiddlewareFunction } from './plugins/middleware'
+export { Destination } from './plugins/destinations'
 export { getGlobalAnalytics } from './lib/global-analytics-helper'
 export { UniversalStorage, Store, StorageObject } from './core/storage'

package/src/plugins/destinations/destination.ts

@@ -0,0 +1,85 @@
+import type { DestinationPlugin, Plugin } from '../../core/plugin'
+import { Context, ContextCancelation } from '../../core/context'
+import {
+  applyDestinationMiddleware,
+  DestinationMiddlewareFunction,
+} from '../middleware'
+
+// removes the return type from a function
+type NoReturn<T> = T extends (...args: any[]) => any
+  ? (...args: Parameters<T>) => void | Promise<void>
+  : T
+
+type PluginActions = Pick<
+  Plugin,
+  'alias' | 'group' | 'identify' | 'page' | 'screen' | 'track'
+>
+
+type DestinationActions = {
+  [K in keyof PluginActions]: NoReturn<PluginActions[K]>
+}
+
+/**
+ * Convenience class for writing 3rd party destination plugins
+ */
+export class Destination implements DestinationPlugin {
+  readonly type = 'destination'
+  readonly middleware: DestinationMiddlewareFunction[] = []
+
+  constructor(
+    readonly name: string,
+    readonly version: string,
+    readonly actions: DestinationActions
+  ) {}
+
+  isLoaded() {
+    return true
+  }
+
+  load() {
+    console.debug(`loaded destination plugin: ${this.name} v${this.version}`)
+    return Promise.resolve()
+  }
+
+  addMiddleware(...fn: DestinationMiddlewareFunction[]) {
+    this.middleware.push(...fn)
+  }
+
+  alias = this._createMethod('alias')
+  group = this._createMethod('group')
+  identify = this._createMethod('identify')
+  page = this._createMethod('page')
+  screen = this._createMethod('screen')
+  track = this._createMethod('track')
+
+  private async transform(ctx: Context): Promise<Context> {
+    const modifiedEvent = await applyDestinationMiddleware(
+      this.name,
+      ctx.event,
+      this.middleware
+    )
+
+    if (modifiedEvent == null) {
+      ctx.cancel(
+        new ContextCancelation({
+          retry: false,
+          reason: 'dropped by destination middleware',
+        })
+      )
+    }
+
+    return new Context(modifiedEvent)
+  }
+
+  private _createMethod(action: keyof DestinationActions) {
+    return async (ctx: Context): Promise<Context> => {
+      if (!this.actions[action]) return ctx
+
+      const transformedCtx = await this.transform(ctx)
+
+      await this.actions[action]!(transformedCtx)
+
+      return ctx
+    }
+  }
+}

package/src/plugins/destinations/google-tag-manager.ts

@@ -0,0 +1,96 @@
+import type { Context } from '../../core/context'
+import type { DestinationFactory } from './types'
+import { Destination } from './destination'
+
+declare global {
+  interface Window {
+    gtag: Function
+  }
+}
+
+type GoogleTagManagerSettings = {
+  /**
+   * The Google measurement ID(s) to send events to (GA4, Ads)
+   */
+  measurementId?: string | string[]
+
+  /**
+   * If a `Viewed Page` event should be sent for all `htevents.page` calls
+   */
+  trackAllPages?: boolean
+
+  /**
+   * If a `Viewed <name> Page` event should be sent for `htevents.page('Name')` calls
+   */
+  trackNamedPages?: boolean
+
+  /**
+   * If a `Viewed <category> <name> Page` event should be sent for `htevents.page('Category', 'Name')` calls
+   */
+  trackCategorizedPages?: boolean
+}
+
+/**
+ * https://github.com/segmentio/analytics.js-integrations/blob/master/integrations/google-tag-manager/lib/index.js
+ */
+const googleTagManager: DestinationFactory<GoogleTagManagerSettings> = ({
+  measurementId = [],
+  trackAllPages = false,
+  trackNamedPages = true,
+  trackCategorizedPages = true,
+}) => {
+  const measurementIds = (
+    Array.isArray(measurementId) ? measurementId : [measurementId]
+  ).filter(Boolean)
+
+  const baseEvent = ({ event }: Context) => {
+    return {
+      ...(event.userId && {
+        user_id: event.userId,
+      }),
+      ...(event.anonymousId && {
+        hightouch_anonymous_id: event.anonymousId,
+      }),
+      ...(measurementIds.length > 0 && {
+        send_to: measurementIds,
+      }),
+      ...event.properties,
+    }
+  }
+
+  return new Destination('Google Tag Manager', '0.0.1', {
+    identify: (ctx) => {
+      if (ctx.event.userId) {
+        measurementIds.forEach((measurementId) => {
+          window.gtag('config', measurementId, {
+            user_id: ctx.event.userId,
+          })
+        })
+      }
+    },
+
+    page: (ctx) => {
+      if (
+        trackAllPages ||
+        (trackNamedPages && ctx.event.name) ||
+        (trackCategorizedPages && ctx.event.category)
+      ) {
+        const eventName = ['Viewed', ctx.event.category, ctx.event.name, 'Page']
+          .filter(Boolean)
+          .join(' ')
+
+        window.gtag('event', eventName, {
+          ...baseEvent(ctx),
+        })
+      }
+    },
+
+    track: (ctx) => {
+      window.gtag('event', ctx.event.event, {
+        ...baseEvent(ctx),
+      })
+    },
+  })
+}
+
+export default googleTagManager

package/src/plugins/destinations/index.ts

@@ -0,0 +1,19 @@
+import type { DestinationSettings } from './types'
+import { Destination } from './destination'
+
+export { Destination }
+export type { DestinationSettings }
+
+export async function createDestination(
+  name: string,
+  settings: DestinationSettings
+): Promise<Destination | undefined> {
+  switch (name) {
+    case 'Google Tag Manager':
+      return import(
+        /* webpackChunkName: "google-tag-manager" */ './google-tag-manager'
+      ).then((mod) => mod.default(settings as any))
+    default:
+      return undefined
+  }
+}

package/src/plugins/destinations/types.ts

@@ -0,0 +1,8 @@
+import type { JSONObject } from '@ht-sdks/events-sdk-js-core'
+import type { Destination } from './destination'
+
+export type DestinationSettings = JSONObject
+
+export type DestinationFactory<TSettings extends DestinationSettings> = (
+  settings: TSettings
+) => Destination