@funnelsgrove/analytics 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './services/runtime-api.config.js';
 export * from './services/sdk-user-id.storage.js';
 export * from './services/bootstrap-public-analytics-user.js';
+export * from './services/meta-pixel.service.js';
 export * from './services/public-analytics-sdk.service.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './services/runtime-api.config.js';
 export * from './services/sdk-user-id.storage.js';
 export * from './services/bootstrap-public-analytics-user.js';
+export * from './services/meta-pixel.service.js';
 export * from './services/public-analytics-sdk.service.js';

package/dist/services/meta-pixel.service.d.ts

@@ -0,0 +1,26 @@
+type MetaPixelEventName = 'AddPaymentInfo' | 'InitiateCheckout' | 'Lead' | 'ViewContent';
+export type MetaPixelTrackInput = {
+    eventName: MetaPixelEventName;
+    eventId: string;
+    customData?: Record<string, unknown>;
+};
+export type AnalyticsEventForMetaPixel = {
+    eventType: string;
+    eventId: string;
+    metadata?: Record<string, unknown>;
+};
+declare global {
+    interface Window {
+        fbq?: (...args: unknown[]) => void;
+    }
+}
+export declare const mapAnalyticsEventToMetaPixelEvent: (event: AnalyticsEventForMetaPixel) => MetaPixelTrackInput | null;
+export declare class MetaPixelService {
+    private initialized;
+    track(input: MetaPixelTrackInput): void;
+    private isConfigured;
+    private ensureInitialized;
+    private installScript;
+}
+export declare const metaPixelService: MetaPixelService;
+export {};

package/dist/services/meta-pixel.service.js

@@ -0,0 +1,100 @@
+import { META_PIXEL_ENABLED, META_PIXEL_ID } from './runtime-api.config.js';
+const toNumber = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return value;
+};
+const toCurrency = (value) => {
+    return typeof value === 'string' && value.trim() ? value.trim().toUpperCase() : undefined;
+};
+const buildCommerceCustomData = (metadata = {}) => {
+    var _a;
+    const amountCents = toNumber(metadata.amountCents);
+    const value = (_a = toNumber(metadata.value)) !== null && _a !== void 0 ? _a : (amountCents === null ? null : amountCents / 100);
+    const currency = toCurrency(metadata.currency);
+    const customData = {};
+    if (currency) {
+        customData.currency = currency;
+    }
+    if (value !== null) {
+        customData.value = value;
+    }
+    return customData;
+};
+export const mapAnalyticsEventToMetaPixelEvent = (event) => {
+    switch (event.eventType) {
+        case 'first_step_viewed':
+        case 'first_step_clicked':
+            return {
+                eventName: 'ViewContent',
+                eventId: event.eventId,
+                customData: {},
+            };
+        case 'email_captured':
+        case 'lead':
+            return {
+                eventName: 'Lead',
+                eventId: event.eventId,
+                customData: {},
+            };
+        case 'checkout_started':
+            return {
+                eventName: 'InitiateCheckout',
+                eventId: event.eventId,
+                customData: buildCommerceCustomData(event.metadata),
+            };
+        case 'checkout_completed':
+        case 'payment_checkout_succeeded':
+            return {
+                eventName: 'AddPaymentInfo',
+                eventId: event.eventId,
+                customData: buildCommerceCustomData(event.metadata),
+            };
+        default:
+            return null;
+    }
+};
+export class MetaPixelService {
+    constructor() {
+        this.initialized = false;
+    }
+    track(input) {
+        var _a, _b;
+        if (!this.isConfigured()) {
+            return;
+        }
+        this.ensureInitialized();
+        (_a = window.fbq) === null || _a === void 0 ? void 0 : _a.call(window, 'track', input.eventName, (_b = input.customData) !== null && _b !== void 0 ? _b : {}, {
+            eventID: input.eventId,
+        });
+    }
+    isConfigured() {
+        return Boolean(META_PIXEL_ENABLED && META_PIXEL_ID && typeof window !== 'undefined');
+    }
+    ensureInitialized() {
+        var _a, _b;
+        if (this.initialized) {
+            return;
+        }
+        this.initialized = true;
+        this.installScript();
+        (_a = window.fbq) === null || _a === void 0 ? void 0 : _a.call(window, 'init', META_PIXEL_ID);
+        (_b = window.fbq) === null || _b === void 0 ? void 0 : _b.call(window, 'track', 'PageView');
+    }
+    installScript() {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        const firstScript = document.getElementsByTagName('script')[0];
+        const parent = firstScript === null || firstScript === void 0 ? void 0 : firstScript.parentNode;
+        if (!parent) {
+            return;
+        }
+        const script = document.createElement('script');
+        script.async = true;
+        script.src = 'https://connect.facebook.net/en_US/fbevents.js';
+        parent.insertBefore(script, firstScript);
+    }
+}
+export const metaPixelService = new MetaPixelService();

package/dist/services/public-analytics-sdk.service.d.ts

@@ -26,6 +26,23 @@ export type PublicSdkStepEndInput = {
     selected?: Record<string, unknown>;
     featureFlags?: Record<string, string | null | undefined>;
 };
+export type PublicSdkStepEngagedInput = {
+    stepId: string;
+    stepName: string;
+    startedAt: string;
+    engagedAt: string;
+    durationMs: number;
+    engagementThresholdMs: number;
+    featureFlags?: Record<string, string | null | undefined>;
+};
+export type PublicSdkConversionCallbackInput = {
+    eventId?: string;
+    occurredAt?: string;
+    stepId?: string;
+    stepName?: string;
+    metadata?: Record<string, unknown>;
+    featureFlags?: Record<string, string | null | undefined>;
+};
 export type PublicSdkIdentifyInput = {
     user_id?: string;
     email?: string;
@@ -56,6 +73,12 @@ export declare class PublicAnalyticsSdkService {
     track(event: PublicSdkTrackEventInput): string | null;
     trackStepStarted(input: PublicSdkStepStartInput): string | null;
     trackStepCompleted(input: PublicSdkStepEndInput): string | null;
+    trackStepEngaged(input: PublicSdkStepEngagedInput): string | null;
+    trackFirstStepClicked(input: PublicSdkConversionCallbackInput): string | null;
+    trackFirstStepViewed(input: PublicSdkConversionCallbackInput): string | null;
+    trackLead(input: PublicSdkConversionCallbackInput): string | null;
+    trackCheckoutStarted(input: PublicSdkConversionCallbackInput): string | null;
+    trackCheckoutCompleted(input: PublicSdkConversionCallbackInput): string | null;
     flush(): Promise<number>;
     private ensureUserId;
     private resolveBootstrapUserId;

package/dist/services/public-analytics-sdk.service.js

@@ -1,5 +1,6 @@
 import { buildMainApiUrl, buildSdkHeaders, FUNNEL_ID, FUNNEL_VERSION_ID, getFunnelSdkPublishableKey, hasPostHogRuntimeConfig, POSTHOG_API_HOST, POSTHOG_PROJECT_API_KEY, PROJECT_ID, } from './runtime-api.config.js';
 import { canUseDom, getOrCreateUserId, persistUserId, readStoredUserId, } from './sdk-user-id.storage.js';
+import { mapAnalyticsEventToMetaPixelEvent, metaPixelService, } from './meta-pixel.service.js';
 const DEFAULT_OPTIONS = {
     batchSize: 20,
     flushIntervalMs: 1500,
@@ -27,6 +28,23 @@ const toIsoOrNow = (value) => {
     }
     return new Date().toISOString();
 };
+const toFiniteNumber = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return value;
+};
+const toDurationMs = (startedAt, endedAt) => {
+    if (!startedAt || !endedAt) {
+        return null;
+    }
+    const startedMs = new Date(startedAt).getTime();
+    const endedMs = new Date(endedAt).getTime();
+    if (!Number.isFinite(startedMs) || !Number.isFinite(endedMs) || endedMs < startedMs) {
+        return null;
+    }
+    return endedMs - startedMs;
+};
 const buildEventId = () => {
     var _a;
     if (canUseDom() && typeof ((_a = window.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === 'function') {
@@ -144,21 +162,33 @@ export class PublicAnalyticsSdkService {
         }
     }
     track(event) {
+        var _a, _b, _c, _d;
         const eventType = asString(event.eventType);
         if (!eventType) {
             return null;
         }
+        const eventId = asString(event.eventId) || buildEventId();
+        const metaPixelEvent = mapAnalyticsEventToMetaPixelEvent({
+            eventType,
+            eventId,
+            metadata: asRecord(event.metadata),
+        });
+        if (metaPixelEvent) {
+            metaPixelService.track(metaPixelEvent);
+        }
         if (!getFunnelSdkPublishableKey()) {
-            return asString(event.eventId) || buildEventId();
+            return eventId;
         }
         const envelope = {
             eventType,
-            eventId: asString(event.eventId) || buildEventId(),
+            eventId,
             occurredAt: toIsoOrNow(event.occurredAt),
             stepId: asString(event.stepId),
             stepName: asString(event.stepName),
             startedAt: asString(event.startedAt),
             endedAt: asString(event.endedAt),
+            durationMs: (_b = toFiniteNumber((_a = event.metadata) === null || _a === void 0 ? void 0 : _a.durationMs)) !== null && _b !== void 0 ? _b : null,
+            engagementThresholdMs: (_d = toFiniteNumber((_c = event.metadata) === null || _c === void 0 ? void 0 : _c.engagementThresholdMs)) !== null && _d !== void 0 ? _d : null,
             selected: asRecord(event.selected),
             payload: asRecord(event.payload),
             context: asRecord(event.context),
@@ -184,14 +214,90 @@ export class PublicAnalyticsSdkService {
         });
     }
     trackStepCompleted(input) {
+        var _a;
+        const startedAt = asString(input.startedAt);
+        const endedAt = asString(input.endedAt);
         return this.track({
             eventType: 'step_end',
             stepId: input.stepId,
             stepName: input.stepName,
-            startedAt: input.startedAt,
-            endedAt: input.endedAt,
+            startedAt: startedAt || input.startedAt,
+            endedAt: endedAt || input.endedAt,
             occurredAt: input.endedAt,
             selected: asRecord(input.selected),
+            metadata: {
+                durationMs: (_a = toDurationMs(startedAt, endedAt)) !== null && _a !== void 0 ? _a : undefined,
+            },
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackStepEngaged(input) {
+        return this.track({
+            eventType: 'step_engaged',
+            stepId: input.stepId,
+            stepName: input.stepName,
+            startedAt: input.startedAt,
+            endedAt: input.engagedAt,
+            occurredAt: input.engagedAt,
+            metadata: {
+                durationMs: input.durationMs,
+                engagementThresholdMs: input.engagementThresholdMs,
+            },
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackFirstStepClicked(input) {
+        return this.track({
+            eventType: 'first_step_clicked',
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: input.metadata,
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackFirstStepViewed(input) {
+        return this.track({
+            eventType: 'first_step_viewed',
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: input.metadata,
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackLead(input) {
+        return this.track({
+            eventType: 'email_captured',
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: input.metadata,
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackCheckoutStarted(input) {
+        return this.track({
+            eventType: 'checkout_started',
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: input.metadata,
+            featureFlags: input.featureFlags,
+        });
+    }
+    trackCheckoutCompleted(input) {
+        return this.track({
+            eventType: 'checkout_completed',
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: input.metadata,
             featureFlags: input.featureFlags,
         });
     }
@@ -271,13 +377,16 @@ export class PublicAnalyticsSdkService {
         if (!getFunnelSdkPublishableKey() || !hasPostHogRuntimeConfig()) {
             return true;
         }
-        const batch = events.map((event) => ({
-            event: toPostHogEventName(event.eventType),
-            properties: buildDefinedRecord(Object.assign(Object.assign({ distinct_id: this.ensureUserId(), $groups: {
-                    project: PROJECT_ID,
-                }, $insert_id: event.eventId, project_id: PROJECT_ID, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, step_id: event.stepId || undefined, step_name: event.stepName || undefined, event_source: 'client' }, buildFeatureFlagProperties(event.featureFlags)), { selected: Object.keys(event.selected).length > 0 ? event.selected : undefined, payload: Object.keys(event.payload).length > 0 ? event.payload : undefined, context: Object.keys(event.context).length > 0 ? event.context : undefined, metadata: Object.keys(event.metadata).length > 0 ? event.metadata : undefined })),
-            timestamp: event.occurredAt,
-        }));
+        const batch = events.map((event) => {
+            var _a, _b;
+            return ({
+                event: toPostHogEventName(event.eventType),
+                properties: buildDefinedRecord(Object.assign(Object.assign({ distinct_id: this.ensureUserId(), $groups: {
+                        project: PROJECT_ID,
+                    }, $insert_id: event.eventId, project_id: PROJECT_ID, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, step_id: event.stepId || undefined, step_name: event.stepName || undefined, started_at: event.startedAt || undefined, ended_at: event.endedAt || undefined, duration_ms: (_a = event.durationMs) !== null && _a !== void 0 ? _a : undefined, engagement_threshold_ms: (_b = event.engagementThresholdMs) !== null && _b !== void 0 ? _b : undefined, event_source: 'client' }, buildFeatureFlagProperties(event.featureFlags)), { selected: Object.keys(event.selected).length > 0 ? event.selected : undefined, payload: Object.keys(event.payload).length > 0 ? event.payload : undefined, context: Object.keys(event.context).length > 0 ? event.context : undefined, metadata: Object.keys(event.metadata).length > 0 ? event.metadata : undefined })),
+                timestamp: event.occurredAt,
+            });
+        });
         const payload = JSON.stringify({
             api_key: POSTHOG_PROJECT_API_KEY,
             batch,

package/dist/services/runtime-api.config.d.ts

@@ -5,6 +5,8 @@ export declare const FUNNEL_VERSION_ID: string;
 export declare const PROJECT_ID: string;
 export declare const POSTHOG_API_HOST = "https://us.i.posthog.com";
 export declare const POSTHOG_PROJECT_API_KEY: string;
+export declare const META_PIXEL_ENABLED: boolean;
+export declare const META_PIXEL_ID: string;
 export declare const hasRealFunnelSdkPublishableKey: (value?: string) => boolean;
 export declare const getFunnelSdkPublishableKey: () => string | null;
 export declare const hasPostHogRuntimeConfig: () => boolean;

package/dist/services/runtime-api.config.js

@@ -1,5 +1,5 @@
-var _a, _b, _c, _d, _e, _f;
-import { runtimeEnvConfig } from '@funnelsgrove/runtime/config/env.config';
+var _a, _b, _c, _d, _e, _f, _g, _h;
+import { resolveRuntimeSdkApiBaseUrl, runtimeEnvConfig, } from '@funnelsgrove/runtime/config/env.config';
 const DEFAULT_API_BASE_URL = 'https://sdk-api.funnelsgrove.com';
 const DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY = 'pk_test_app_deals_seed_public';
 const trimTrailingSlash = (value) => {
@@ -19,13 +19,15 @@ const isPreviewFrameRuntime = () => {
         return false;
     }
 };
-export const APP_DEALS_API_BASE_URL = trimTrailingSlash((_a = runtimeEnvConfig.appDealsApiBaseUrl) !== null && _a !== void 0 ? _a : DEFAULT_API_BASE_URL);
+export const APP_DEALS_API_BASE_URL = trimTrailingSlash(resolveRuntimeSdkApiBaseUrl((_a = runtimeEnvConfig.appDealsApiBaseUrl) !== null && _a !== void 0 ? _a : DEFAULT_API_BASE_URL));
 export const FUNNEL_SDK_PUBLISHABLE_KEY = ((_b = runtimeEnvConfig.funnelSdkPublishableKey) !== null && _b !== void 0 ? _b : DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY).trim();
 export const FUNNEL_ID = ((_c = runtimeEnvConfig.funnelId) !== null && _c !== void 0 ? _c : '').trim();
 export const FUNNEL_VERSION_ID = ((_d = runtimeEnvConfig.funnelVersionId) !== null && _d !== void 0 ? _d : '').trim();
 export const PROJECT_ID = ((_e = runtimeEnvConfig.projectId) !== null && _e !== void 0 ? _e : '').trim();
 export const POSTHOG_API_HOST = 'https://us.i.posthog.com';
 export const POSTHOG_PROJECT_API_KEY = ((_f = runtimeEnvConfig.posthogProjectApiKey) !== null && _f !== void 0 ? _f : '').trim();
+export const META_PIXEL_ENABLED = ((_g = runtimeEnvConfig.metaPixelEnabled) !== null && _g !== void 0 ? _g : '').trim() === 'true';
+export const META_PIXEL_ID = ((_h = runtimeEnvConfig.metaPixelId) !== null && _h !== void 0 ? _h : '').trim();
 export const hasRealFunnelSdkPublishableKey = (value = FUNNEL_SDK_PUBLISHABLE_KEY) => {
     const normalized = value.trim();
     return Boolean(normalized) && normalized !== DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/analytics",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "test:run": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@funnelsgrove/runtime": "0.1.2"
+    "@funnelsgrove/runtime": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20",