@funnelsgrove/runtime 0.1.55 → 0.1.56

package/dist/runtime/funnel-attribution.d.ts

@@ -15,4 +15,5 @@ export declare const collectCurrentFunnelAttribution: (input?: {
     posthogProperties?: Record<string, unknown> | null;
 }) => FunnelUserAttribution;
 export declare const mergeFunnelUserAttribution: (current: unknown, incoming: FunnelUserAttribution | null | undefined) => FunnelUserAttribution;
+export declare const buildFunnelAttributionEventMetadata: (attribution: FunnelUserAttribution | null | undefined) => Record<string, string>;
 export declare const getFunnelUserAttribution: (document: unknown) => FunnelUserAttribution | null;

package/dist/runtime/funnel-attribution.js

@@ -6,6 +6,22 @@ const INTERNAL_ATTRIBUTION_QUERY_KEYS = new Set([
     'step',
     'user_id',
 ]);
+const EVENT_ATTRIBUTION_CLICK_ID_KEYS = new Set([
+    '_fbc',
+    '_fbp',
+    'epik',
+    'fbc',
+    'fbclid',
+    'fbp',
+    'gbraid',
+    'gclid',
+    'li_fat_id',
+    'msclkid',
+    'scclid',
+    'ttclid',
+    'twclid',
+    'wbraid',
+]);
 const POSTHOG_CONTEXT_MAPPINGS = {
     $geoip_city_name: 'cityName',
     $geoip_country_code: 'countryCode',
@@ -41,6 +57,13 @@ const normalizeTouch = (value) => {
         return [[normalizedKey, normalizedValue]];
     }));
 };
+const isEventAttributionKey = (key) => {
+    const normalizedKey = key.trim().toLowerCase();
+    return normalizedKey.startsWith('utm_') || EVENT_ATTRIBUTION_CLICK_ID_KEYS.has(normalizedKey);
+};
+const normalizeEventAttributionTouch = (value) => {
+    return Object.fromEntries(Object.entries(normalizeTouch(value)).filter(([key]) => isEventAttributionKey(key)));
+};
 const normalizeContext = (value) => {
     if (!isRecord(value)) {
         return {};
@@ -219,6 +242,7 @@ export const mergeFunnelUserAttribution = (current, incoming) => {
         context: deepMergeRecords(currentContext, nextContext),
     };
 };
+export const buildFunnelAttributionEventMetadata = (attribution) => normalizeEventAttributionTouch(attribution === null || attribution === void 0 ? void 0 : attribution.firstTouch);
 export const getFunnelUserAttribution = (document) => {
     if (!isRecord(document) || !isRecord(document.attribution)) {
         return null;

package/dist/runtime/use-funnel-flow-controller.d.ts

@@ -2,6 +2,7 @@ import { type Dispatch, type SetStateAction } from 'react';
 import type { FunnelContextValue } from '../components/FunnelContext.js';
 import type { FunnelManifestExperiment } from '../config/funnel.manifest.types.js';
 import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
+import { type FunnelUserAttribution } from './funnel-attribution.js';
 import type { FunnelStepMeta } from '../steps/types.js';
 export type FunnelFlowControllerExperiment<StepId extends string> = FunnelManifestExperiment & {
     stepId: StepId;
@@ -18,6 +19,7 @@ type FunnelFlowAnalyticsAdapter = {
         stepName: string;
         stepType?: string;
         startedAt: string;
+        metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
     trackStepCompleted?: (input: {
@@ -29,6 +31,7 @@ type FunnelFlowAnalyticsAdapter = {
         startedAt: string;
         endedAt: string;
         selected?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
     trackFunnelStarted?: (input: {
@@ -38,6 +41,7 @@ type FunnelFlowAnalyticsAdapter = {
         stepName: string;
         stepType?: string;
         occurredAt: string;
+        metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
     trackFirstStepViewed?: (input: {
@@ -47,6 +51,7 @@ type FunnelFlowAnalyticsAdapter = {
         stepName: string;
         stepType?: string;
         occurredAt: string;
+        metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
 };
@@ -99,8 +104,16 @@ type UseFunnelFlowControllerResult<StepId extends string> = {
     setRuntimeMode: (mode: 'test' | 'live') => void;
     showShellContinue: boolean;
 };
+export declare function resolveFunnelEventAttribution(document: unknown, provisionalAttribution: FunnelUserAttribution | null): FunnelUserAttribution | null;
+export declare function buildReadyFunnelAttributionEventMetadata(attributionReady: boolean, attribution: FunnelUserAttribution | null): Record<string, string> | null;
+export declare function scheduleAttributionFailOpen(onReady: () => void, timeoutMs: number): () => void;
+export declare function takeInitialFunnelAttributionMetadata(tracked: boolean, attributionReady: boolean, attribution: FunnelUserAttribution | null): {
+    tracked: boolean;
+    metadata: Record<string, string> | null;
+};
 export declare function computeRenderSuspended(input: {
     activeStepId: string;
+    attributionReady?: boolean;
     postHogReady: boolean;
     experiments: ReadonlyArray<{
         stepId: string;

package/dist/runtime/use-funnel-flow-controller.js

@@ -8,14 +8,38 @@ import { buildHostedStepLocation, dispatchWindowCustomEvent, } from './browser-h
 import { isPreviewStepLockRequested, resolveNextStepFromContext, shouldRunAutoAdvanceTimer, } from './funnel-flow.js';
 import { usePreviewBridge } from './preview-bridge.js';
 import { resolveExperimentAssignment, resolveForcedExperimentAssignment, } from './experiment-assignment.js';
-import { collectCurrentFunnelAttribution } from './funnel-attribution.js';
+import { buildFunnelAttributionEventMetadata, collectCurrentFunnelAttribution, getFunnelUserAttribution, } from './funnel-attribution.js';
 import { resolveUrlUserAttributes } from './url-user-attributes.js';
 import { bootstrapPostHog, identifyPostHog, isPostHogReady, resolveExperimentVariant, } from './posthog-flags.js';
 import { getRuntimeMode, isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
 import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
+export function resolveFunnelEventAttribution(document, provisionalAttribution) {
+    var _a;
+    return (_a = getFunnelUserAttribution(document)) !== null && _a !== void 0 ? _a : provisionalAttribution;
+}
+export function buildReadyFunnelAttributionEventMetadata(attributionReady, attribution) {
+    return attributionReady ? buildFunnelAttributionEventMetadata(attribution) : null;
+}
+export function scheduleAttributionFailOpen(onReady, timeoutMs) {
+    const timeoutId = setTimeout(onReady, timeoutMs);
+    return () => clearTimeout(timeoutId);
+}
+export function takeInitialFunnelAttributionMetadata(tracked, attributionReady, attribution) {
+    if (tracked) {
+        return { tracked, metadata: null };
+    }
+    const metadata = buildReadyFunnelAttributionEventMetadata(attributionReady, attribution);
+    return { tracked: metadata !== null, metadata };
+}
 export function computeRenderSuspended(input) {
     var _a;
-    if (input.isPreviewRuntime || input.postHogReady) {
+    if (input.isPreviewRuntime) {
+        return false;
+    }
+    if (input.attributionReady === false) {
+        return true;
+    }
+    if (input.postHogReady) {
         return false;
     }
     const activeExperiment = input.experiments.find((experiment) => experiment.stepId === input.activeStepId);
@@ -114,6 +138,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         completedSteps: [],
     }));
     const [userBootstrapped, setUserBootstrapped] = useState(isPreviewRuntime);
+    const [attributionReady, setAttributionReady] = useState(isPreviewRuntime);
     const attributesAtStepStart = useRef({});
     const attributesRef = useRef(attributes);
     const postHogFeatureFlagsRef = useRef({});
@@ -121,14 +146,16 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
     const firstStepViewedTrackedRef = useRef(false);
     const stepStartedAtByIdRef = useRef({});
     const currentUserIdRef = useRef(user.id);
+    const initialAttributionRef = useRef(null);
     const safeActiveStepId = useMemo(() => { var _a; return (_a = resolveRenderableStepId(activeStepId)) !== null && _a !== void 0 ? _a : safeInitialStepId; }, [activeStepId, resolveRenderableStepId, safeInitialStepId]);
     const activeStepMeta = stepById[safeActiveStepId];
     const renderSuspended = useMemo(() => computeRenderSuspended({
         activeStepId: safeActiveStepId,
+        attributionReady,
         postHogReady,
         experiments: funnelExperiments,
         isPreviewRuntime,
-    }), [funnelExperiments, isPreviewRuntime, postHogReady, safeActiveStepId]);
+    }), [attributionReady, funnelExperiments, isPreviewRuntime, postHogReady, safeActiveStepId]);
     const resolveExperimentVariantKey = useCallback((experiment) => {
         var _a;
         const override = editorVariantOverrides[experiment.experimentId];
@@ -251,11 +278,13 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         const urlUserAttributes = resolveUrlUserAttributes();
         const bootstrapCandidateUserId = apiService.getBootstrapCandidateUserId(localUserId);
         const initialAttribution = collectCurrentFunnelAttribution();
+        initialAttributionRef.current = initialAttribution;
         setUserBootstrapped(isPreviewRuntime);
         setUser((prev) => (Object.assign(Object.assign({}, prev), { id: localUserId })));
         if (isPreviewRuntime) {
             return;
         }
+        const cancelAttributionFailOpen = scheduleAttributionFailOpen(() => setAttributionReady(true), 5000);
         const postHogBootstrap = bootstrapPostHog({
             apiKey: POSTHOG_PROJECT_API_KEY,
             apiHost: POSTHOG_API_HOST,
@@ -276,14 +305,17 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             attribution: initialAttribution,
         })
             .then((sessionUser) => {
+            cancelAttributionFailOpen();
             const sessionAttributes = Object.keys(sessionUser.attributes || {}).length > 0
                 ? sessionUser.attributes
                 : null;
             if (sessionAttributes) {
                 setAttributes((prev) => (Object.assign(Object.assign({}, sessionAttributes), prev)));
             }
+            initialAttributionRef.current = resolveFunnelEventAttribution(sessionUser.document, initialAttribution);
             setUser((prev) => (Object.assign(Object.assign({}, prev), { id: sessionUser.id || prev.id, name: sessionUser.name || prev.name, email: sessionUser.email || prev.email, document: sessionUser.document, attributes: sessionAttributes ? Object.assign(Object.assign({}, sessionAttributes), prev.attributes) : prev.attributes })));
             setUserBootstrapped(true);
+            setAttributionReady(true);
             void apiService.pingUserContext(sessionUser.id)
                 .then((pingedUser) => {
                 if (!pingedUser) {
@@ -301,8 +333,10 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             return sessionUser;
         })
             .catch((error) => {
+            cancelAttributionFailOpen();
             logger.error('Failed to bootstrap user session:', error);
             setUserBootstrapped(false);
+            setAttributionReady(true);
             return null;
         });
         Promise.all([postHogBootstrap, sessionBootstrap])
@@ -314,6 +348,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             .catch((error) => {
             logger.error('Failed to identify PostHog user:', error);
         });
+        return cancelAttributionFailOpen;
     }, [isPreviewRuntime]);
     const recordStepCompletion = useCallback((stepId, explicitChoices) => {
         var _a;
@@ -321,6 +356,10 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         if (!meta) {
             return;
         }
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null) {
+            return;
+        }
         let choices;
         if (explicitChoices) {
             choices = explicitChoices;
@@ -354,6 +393,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                 startedAt,
                 endedAt: record.completedAt,
                 selected: record.choices,
+                metadata: attributionMetadata,
                 featureFlags: postHogFeatureFlagsRef.current,
             });
         }
@@ -378,7 +418,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             }
             return updatedUser;
         });
-    }, [analytics, isPreviewRuntime, stepById]);
+    }, [analytics, attributionReady, isPreviewRuntime, stepById]);
     const completeStep = useCallback((stepId, choices) => {
         recordStepCompletion(stepId, choices);
     }, [recordStepCompletion]);
@@ -404,6 +444,12 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         const stepType = renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.type;
         stepStartedAtByIdRef.current[renderedStepId] = startedAt;
         const analyticsRuntimeMode = getRuntimeMode();
+        attributesAtStepStart.current = Object.assign({}, attributesRef.current);
+        prevStepIdRef.current = renderedStepId;
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null) {
+            return;
+        }
         if (!isPreviewRuntime) {
             (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepStarted) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                 userId: currentUserIdRef.current,
@@ -412,10 +458,15 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                 stepName,
                 stepType,
                 startedAt,
+                metadata: attributionMetadata,
                 featureFlags: postHogFeatureFlagsRef.current,
             });
             if (!firstStepViewedTrackedRef.current && safeActiveStepId === defaultStepId) {
-                firstStepViewedTrackedRef.current = true;
+                const initialAttribution = takeInitialFunnelAttributionMetadata(firstStepViewedTrackedRef.current, attributionReady, initialAttributionRef.current);
+                firstStepViewedTrackedRef.current = initialAttribution.tracked;
+                if (!initialAttribution.metadata) {
+                    return;
+                }
                 (_b = analytics === null || analytics === void 0 ? void 0 : analytics.trackFunnelStarted) === null || _b === void 0 ? void 0 : _b.call(analytics, {
                     userId: currentUserIdRef.current,
                     environment: analyticsRuntimeMode,
@@ -423,6 +474,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                     stepName,
                     stepType,
                     occurredAt: startedAt,
+                    metadata: initialAttribution.metadata,
                     featureFlags: postHogFeatureFlagsRef.current,
                 });
                 (_c = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepViewed) === null || _c === void 0 ? void 0 : _c.call(analytics, {
@@ -432,15 +484,15 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                     stepName,
                     stepType,
                     occurredAt: startedAt,
+                    metadata: initialAttribution.metadata,
                     featureFlags: postHogFeatureFlagsRef.current,
                 });
             }
         }
-        attributesAtStepStart.current = Object.assign({}, attributesRef.current);
-        prevStepIdRef.current = renderedStepId;
     }, [
         activeStepId,
         analytics,
+        attributionReady,
         defaultStepId,
         isPreviewRuntime,
         recordStepCompletion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",