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

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/test-helpers/fixtures/classic-destination.ts

@@ -1,25 +1,40 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
 /**
- * This is a classic destination, such as:
+ * Local stand-in for a classic analytics.js destination, such as:
  * https://github.com/segmentio/analytics.js-integrations/blob/master/integrations/appcues/lib/index.js
  */
 
-const integration = require('@segment/analytics.js-integration')
+import { ClassicIntegrationBuilder } from '../../plugins/ajs-destination/types'
 
 export const mockIntegrationName = 'Fake'
-export const Fake = integration(mockIntegrationName)
 
-Fake.prototype.initialize = function () {
+function FakeIntegration(this: FakeIntegration, _options?: object) {
+  // classic integration constructor
+}
+
+interface FakeIntegration {
+  name: string
+  initialize: () => void
+  loaded: () => boolean
+  track: () => void
+  load: (callback: Function) => void
+  ready?: () => void
+}
+
+FakeIntegration.prototype.name = mockIntegrationName
+
+FakeIntegration.prototype.initialize = function () {
   this.load(this.ready)
 }
 
-Fake.prototype.loaded = function () {
+FakeIntegration.prototype.loaded = function () {
   return true
 }
 
-Fake.prototype.track = function () {}
+FakeIntegration.prototype.track = function () {}
 
-Fake.prototype.load = function (callback: Function) {
+FakeIntegration.prototype.load = function (callback: Function) {
   // this callback is important to actually initialize.
   callback()
 }
+
+export const Fake = FakeIntegration as unknown as ClassicIntegrationBuilder

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
+}