@ht-sdks/events-sdk-js-browser 1.5.7 → 1.5.8

package/src/browser/index.ts

@@ -31,6 +31,16 @@ import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
 import { attachInspector } from '../core/inspector'
 import { setGlobalAnalyticsKey } from '../lib/global-analytics-helper'
 import { createDestination } from '../plugins/destinations'
+import { createPlugin } from '../plugins'
+import {
+  BUILT_IN_PLUGINS,
+  type BuiltInPluginName,
+} from '../plugins/built-in-plugins'
+import {
+  dedupePluginFactories,
+  dedupePlugins,
+  dedupeStringPluginNames,
+} from './dedupe-plugin-likes'
 
 export interface LegacyIntegrationConfiguration {
   /* @deprecated - This does not indicate browser types anymore */
@@ -180,18 +190,36 @@ async function registerPlugins(
   analytics: Analytics,
   opts: InitOptions,
   options: InitOptions,
-  pluginLikes: (Plugin | PluginFactory)[] = [],
+  pluginLikes: (Plugin | PluginFactory | BuiltInPluginName)[] = [],
   legacyIntegrationSources: ClassicIntegrationSource[]
 ): Promise<Context> {
-  const plugins = pluginLikes?.filter(
-    (pluginLike) => typeof pluginLike === 'object'
-  ) as Plugin[]
-
-  const pluginSources = pluginLikes?.filter(
-    (pluginLike) =>
+  const stringPluginNames: BuiltInPluginName[] = []
+  const plugins: Plugin[] = []
+  const pluginSources: PluginFactory[] = []
+
+  for (const pluginLike of pluginLikes) {
+    if (typeof pluginLike === 'string') {
+      if (BUILT_IN_PLUGINS.includes(pluginLike)) {
+        stringPluginNames.push(pluginLike)
+      } else {
+        console.warn(`failed to load plugin: ${pluginLike}`)
+      }
+    } else if (typeof pluginLike === 'object' && pluginLike !== null) {
+      plugins.push(pluginLike)
+    } else if (
       typeof pluginLike === 'function' &&
       typeof pluginLike.pluginName === 'string'
-  ) as PluginFactory[]
+    ) {
+      pluginSources.push(pluginLike)
+    } else {
+      console.warn(`failed to load plugin: ${pluginLike}`)
+      continue
+    }
+  }
+
+  const uniqueStringPluginNames = dedupeStringPluginNames(stringPluginNames)
+  const uniquePlugins = dedupePlugins(plugins)
+  const uniquePluginSources = dedupePluginFactories(pluginSources)
 
   const tsubMiddleware = hasTsubMiddleware(legacySettings)
     ? await import(
@@ -242,13 +270,40 @@ async function registerPlugins(
     mergedSettings,
     options.obfuscate,
     tsubMiddleware,
-    pluginSources
+    uniquePluginSources
   ).catch(() => [])
 
+  // Load string-based plugins
+  const loadedStringPlugins = await Promise.allSettled(
+    uniqueStringPluginNames.map(async (name) => {
+      const plugin = await createPlugin(name)
+      if (plugin) {
+        return plugin
+      } else {
+        console.warn(`failed to load plugin: ${name}`)
+        return null
+      }
+    })
+  )
+
+  const resolvedStringPlugins = loadedStringPlugins
+    .map((result, index) => {
+      if (result.status === 'fulfilled') {
+        return result.value
+      }
+      console.error(
+        `failed to load plugin: ${uniqueStringPluginNames[index]}`,
+        result.reason
+      )
+      return null
+    })
+    .filter((plugin): plugin is Plugin => plugin !== null)
+
   const toRegister = [
     validation,
     envEnrichment,
-    ...plugins,
+    ...uniquePlugins,
+    ...resolvedStringPlugins,
     ...legacyDestinations,
     ...remotePlugins,
   ]
@@ -384,7 +439,11 @@ async function loadAnalytics(
 
   attachInspector(analytics)
 
-  const plugins = settings.plugins ?? []
+  // Merge plugins from both settings and options
+  // This allows plugins to be specified in either place:
+  // - settings.plugins (when using HtEventsBrowser.load({ writeKey, plugins: [...] }))
+  // - options.plugins (when using snippet pattern: htevents.load(writeKey, { plugins: [...] }))
+  const plugins = [...(settings.plugins ?? []), ...(options.plugins ?? [])]
 
   const classicIntegrations = settings.classicIntegrations ?? []
 

package/src/core/analytics/index.ts

@@ -60,6 +60,7 @@ import type {
   HTTPCookieServiceOptions,
 } from '../http-cookies'
 import type { DestinationSettings } from '../../plugins/destinations'
+import type { BuiltInPluginName } from '../../plugins/built-in-plugins'
 
 const deprecationWarning =
   'This is being deprecated and will be not be available in future releases of Analytics JS'
@@ -83,7 +84,7 @@ function createDefaultQueue(
 export interface AnalyticsSettings {
   writeKey: string
   timeout?: number
-  plugins?: (Plugin | PluginFactory)[]
+  plugins?: (Plugin | PluginFactory | BuiltInPluginName)[]
   classicIntegrations?: ClassicIntegrationSource[]
 }
 
@@ -139,6 +140,12 @@ export interface InitOptions {
    */
   destinations?: Record<string, DestinationSettings>
 
+  /**
+   * Array of plugins to load. Can be plugin instances, plugin factories, or built-in plugin names.
+   * Built-in names are resolved via createPlugin() for code-split loading.
+   */
+  plugins?: (Plugin | PluginFactory | BuiltInPluginName)[]
+
   /**
    * When setting httpCookieServiceOptions, an HTTPCookieService is automatically created
    */

package/src/generated/version.ts

@@ -1,2 +1,2 @@
 // This file is generated.
-export const version = '1.5.7'
+export const version = '1.5.8'

package/src/index.ts

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

package/src/plugins/built-in-plugins.ts

@@ -0,0 +1,3 @@
+export const BUILT_IN_PLUGINS = ['facebook-params'] as const
+
+export type BuiltInPluginName = (typeof BUILT_IN_PLUGINS)[number]

package/src/plugins/facebook-params/index.ts

@@ -0,0 +1,121 @@
+import type { Context } from '../../core/context'
+import type { Plugin } from '../../core/plugin'
+import { PluginType } from '@ht-sdks/events-sdk-js-core'
+import { Analytics } from '../../core/analytics'
+import { isServer } from '../../core/environment'
+import type { ClientParamBuilder } from 'meta-capi-param-builder-clientjs'
+
+const SDK_LOAD_TIMEOUT_MS = 2000
+const SDK_LOAD_TIMEOUT_MESSAGE = 'Facebook Parameter Builder SDK load timed out'
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>
+
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), ms)
+  })
+
+  return Promise.race([promise, timeout]).finally(() => {
+    clearTimeout(timer)
+  })
+}
+
+class FacebookParamsPlugin implements Plugin {
+  private clientParamBuilder: ClientParamBuilder | null = null
+  private sdkReady = false
+
+  name = 'Facebook Parameters'
+  type: PluginType = 'enrichment'
+  version = '0.1.0'
+
+  isLoaded = () => this.sdkReady
+
+  load = async (_ctx: Context, _instance: Analytics): Promise<void> => {
+    if (isServer()) {
+      // Server-side rendering - skip loading
+      return Promise.resolve()
+    }
+
+    // Runs to completion on its own, even if the race below gives up waiting
+    const init = (async () => {
+      const paramBuilderModule = await import(
+        /* webpackChunkName: "meta-param-builder" */ 'meta-capi-param-builder-clientjs'
+      )
+      const clientParamBuilder = (paramBuilderModule.default ??
+        paramBuilderModule) as ClientParamBuilder
+
+      if (
+        !clientParamBuilder ||
+        typeof clientParamBuilder.processAndCollectAllParams !== 'function' ||
+        typeof clientParamBuilder.getFbc !== 'function' ||
+        typeof clientParamBuilder.getFbp !== 'function'
+      ) {
+        console.warn(
+          'Facebook Parameter Builder SDK loaded but clientParamBuilder is not available or does not expose expected interface'
+        )
+        return
+      }
+
+      await clientParamBuilder.processAndCollectAllParams()
+      this.clientParamBuilder = clientParamBuilder
+      this.sdkReady = true
+    })().catch((error) => {
+      console.warn('Failed to load Facebook Parameter Builder SDK:', error)
+    })
+
+    // Timeout only bounds how long the event queue waits — it doesn't cancel init
+    await _instance.queue.criticalTasks.run(() =>
+      withTimeout(init, SDK_LOAD_TIMEOUT_MS, SDK_LOAD_TIMEOUT_MESSAGE).catch(
+        () => {}
+      )
+    )
+  }
+
+  private enrich = (ctx: Context): Context => {
+    if (!this.sdkReady || !this.clientParamBuilder) {
+      return ctx
+    }
+
+    try {
+      const evtCtx = ctx.event.context
+      if (!evtCtx) {
+        return ctx
+      }
+
+      // Get fbc and fbp from cookies (processAndCollectAllParams was called during load)
+      const fbc = this.clientParamBuilder.getFbc()
+      const fbp = this.clientParamBuilder.getFbp()
+
+      // Only add if not empty (getFbc/getFbp return empty string if cookie doesn't exist)
+      if (fbc) {
+        evtCtx.fbc = fbc
+      }
+
+      if (fbp) {
+        evtCtx.fbp = fbp
+      }
+    } catch (error) {
+      // Silently fail - don't break event processing if SDK has issues
+      console.warn('Error extracting Facebook parameters:', error)
+    }
+
+    return ctx
+  }
+
+  track = this.enrich
+  identify = this.enrich
+  page = this.enrich
+  group = this.enrich
+  alias = this.enrich
+  screen = this.enrich
+}
+
+/**
+ * Default plugin instance using Meta's official ParamBuilder SDK.
+ * Used when plugin is loaded via string name: plugins: ["facebook-params"]
+ */
+export const facebookParams = new FacebookParamsPlugin()

package/src/plugins/index.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from '../core/plugin'
+import type { BuiltInPluginName } from './built-in-plugins'
+
+/**
+ * Creates a plugin instance from a string name.
+ * This allows script tag users to specify plugins by name without importing them.
+ *
+ * @param name - The name of the plugin to load
+ * @returns A promise that resolves to the plugin instance, or undefined if not found
+ */
+export async function createPlugin(
+  name: BuiltInPluginName
+): Promise<Plugin | undefined> {
+  switch (name) {
+    case 'facebook-params':
+      return import(
+        /* webpackChunkName: "facebook-params" */ './facebook-params'
+      ).then((mod) => mod.facebookParams)
+    default:
+      return undefined
+  }
+}

package/src/types/meta-capi-param-builder-clientjs.d.ts

@@ -0,0 +1,32 @@
+declare module 'meta-capi-param-builder-clientjs' {
+  // Facebook Parameter Builder SDK types (clientParamBuilder)
+  // Based on Meta's official API: https://developers.facebook.com/docs/marketing-api/conversions-api/parameter-builder-feature-library/client-side-onboarding
+  export interface ClientParamBuilder {
+    /**
+     * Processes and collects all parameters (fbc, fbp, client_ip_address).
+     * Must be called before getFbc(), getFbp(), or getClientIpAddress().
+     * @param url - Optional. The full URL to collect clickID from. If not provided, uses window.location.href
+     * @param getIpFn - Optional. Function to retrieve client IPv6 address (fallback to IPv4 if unavailable)
+     * @returns Promise that resolves to updated cookie object with _fbc, _fbp, and _fbi keys
+     */
+    processAndCollectAllParams(
+      url?: string,
+      getIpFn?: () => Promise<string>
+    ): Promise<{ _fbc?: string; _fbp?: string; _fbi?: string }>
+    /**
+     * Returns the fbc value from cookie. Returns empty string if cookie does not exist.
+     */
+    getFbc(): string
+    /**
+     * Returns the fbp value from cookie. Returns empty string if cookie does not exist.
+     */
+    getFbp(): string
+    /**
+     * Returns the client_ip_address value from cookie. Returns empty string if cookie does not exist.
+     */
+    getClientIpAddress(): string
+  }
+
+  const clientParamBuilder: ClientParamBuilder
+  export default clientParamBuilder
+}