fragment-headless-sdk 2.2.1 → 2.3.0

package/dist/utils/attribution.d.ts

@@ -0,0 +1,22 @@
+export interface FragmentAttribution {
+    sectionId: string;
+    sectionType: 'announcement' | 'hero_banner';
+    timestamp: number;
+}
+/**
+ * Store attribution data for a section click
+ * Uses sessionStorage for session-scoped attribution (last-click wins)
+ * @param sectionId - The UUID of the section
+ * @param sectionType - The type of section (announcement or hero_banner)
+ */
+export declare function setAttribution(sectionId: string, sectionType: string): void;
+/**
+ * Retrieve stored attribution data
+ * @returns The stored attribution or null if none exists
+ */
+export declare function getAttribution(): FragmentAttribution | null;
+/**
+ * Clear stored attribution data
+ * Called after successful conversion tracking
+ */
+export declare function clearAttribution(): void;

package/dist/utils/attribution.js

@@ -0,0 +1,62 @@
+const STORAGE_KEY = 'fragment_attribution';
+/**
+ * Store attribution data for a section click
+ * Uses sessionStorage for session-scoped attribution (last-click wins)
+ * @param sectionId - The UUID of the section
+ * @param sectionType - The type of section (announcement or hero_banner)
+ */
+export function setAttribution(sectionId, sectionType) {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    const attribution = {
+        sectionId,
+        sectionType: sectionType,
+        timestamp: Date.now()
+    };
+    try {
+        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(attribution));
+    }
+    catch (e) {
+        // Handle quota exceeded or other storage errors silently
+        console.warn('Fragment: Failed to set attribution', e);
+    }
+}
+/**
+ * Retrieve stored attribution data
+ * @returns The stored attribution or null if none exists
+ */
+export function getAttribution() {
+    if (typeof sessionStorage === 'undefined')
+        return null;
+    try {
+        const stored = sessionStorage.getItem(STORAGE_KEY);
+        return stored ? JSON.parse(stored) : null;
+    }
+    catch (e) {
+        // Handle parse errors or other issues
+        console.warn('Fragment: Failed to get attribution', e);
+        return null;
+    }
+}
+/**
+ * Clear stored attribution data
+ * Called after successful conversion tracking
+ */
+export function clearAttribution() {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    try {
+        sessionStorage.removeItem(STORAGE_KEY);
+    }
+    catch (e) {
+        console.warn('Fragment: Failed to clear attribution', e);
+    }
+}
+// Make globally accessible for Shopify theme integrations
+if (typeof window !== 'undefined') {
+    window.fragmentAttribution = {
+        get: getAttribution,
+        set: setAttribution,
+        clear: clearAttribution
+    };
+}

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./announcement-resolvers";
+export * from "./attribution";
 export * from "./cache";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";

package/dist/utils/index.js

@@ -1,4 +1,5 @@
 export * from "./announcement-resolvers";
+export * from "./attribution";
 export * from "./cache";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";

package/dist/utils/metrics.d.ts

@@ -8,4 +8,8 @@ declare global {
         dataLayer?: unknown[];
     }
 }
+/**
+ * Fire a scroll past metric when user scrolls past a section
+ */
+export declare function fireScrollPastMetric(measurementId: string | undefined, sectionType: SectionType, sectionId: string): void;
 export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;

package/dist/utils/metrics.js

@@ -1,4 +1,5 @@
 import { SectionType } from "../constants";
+import { setAttribution } from "./attribution";
 // --- Unicode-safe Base64URL ---
 export function toBase64Url(input) {
     // Handles emojis & non-ASCII reliably:
@@ -22,6 +23,10 @@ export function fireClickMetric(clickUrl, measurementId, sectionType, sectionId)
         return;
     if (!clickUrl)
         return;
+    // Store attribution for potential purchase/add-to-cart tracking
+    if (sectionType && sectionId) {
+        setAttribution(sectionId, sectionType);
+    }
     // Send to GA4 first (if available)
     if (measurementId && sectionType && sectionId) {
         sendGA4Event("click", measurementId, sectionType, sectionId);
@@ -55,7 +60,9 @@ export function fireClickMetric(clickUrl, measurementId, sectionType, sectionId)
  * This allows filtering by event name in GA4 without requiring custom dimensions.
  */
 function getSectionEventName(baseEventName, sectionType) {
-    const sectionPrefix = sectionType === SectionType.Announcement ? "fragment_announcement" : "fragment_hero_banner";
+    const sectionPrefix = sectionType === SectionType.Announcement
+        ? "fragment_announcement"
+        : "fragment_hero_banner";
     return `${sectionPrefix}_${baseEventName}`;
 }
 /**
@@ -65,7 +72,7 @@ function getSectionEventName(baseEventName, sectionType) {
  * Only sends section_id parameter - event name already indicates section type.
  * This is a fire-and-forget operation that won't throw errors.
  */
-function sendGA4Event(baseEventName, measurementId, sectionType, sectionId) {
+function sendGA4Event(baseEventName, measurementId, sectionType, sectionId, additionalParams) {
     if (typeof window === "undefined")
         return;
     if (!measurementId)
@@ -76,12 +83,25 @@ function sendGA4Event(baseEventName, measurementId, sectionType, sectionId) {
         const eventName = getSectionEventName(baseEventName, sectionType);
         window.gtag("event", eventName, {
             section_id: sectionId,
+            ...additionalParams,
         });
     }
     catch {
         // Silently fail - don't break tracking if GA4 fails
     }
 }
+/**
+ * Fire a scroll past metric when user scrolls past a section
+ */
+export function fireScrollPastMetric(measurementId, sectionType, sectionId) {
+    if (typeof window === "undefined")
+        return;
+    if (!measurementId || !sectionType || !sectionId)
+        return;
+    sendGA4Event("scroll_past", measurementId, sectionType, sectionId, {
+        engagement_type: "scroll_past",
+    });
+}
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
 export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionType, sectionId) {
@@ -92,6 +112,7 @@ export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionTy
     if (seenEls && seenEls.has(el))
         return; // de-dupe by element
     let fired = false;
+    let hasScrolledPast = false;
     const img = new Image();
     const fire = () => {
         if (fired)
@@ -119,8 +140,18 @@ export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionTy
         for (const e of entries) {
             if (e.isIntersecting && e.intersectionRatio >= 0.3) {
                 fire();
+                // Don't disconnect - keep observing for scroll past
+            }
+            else if (!e.isIntersecting &&
+                !hasScrolledPast &&
+                e.boundingClientRect.top < 0 &&
+                fired) {
+                // User has scrolled past the section (it was visible, now it's above viewport)
+                hasScrolledPast = true;
+                if (measurementId && sectionType && sectionId) {
+                    fireScrollPastMetric(measurementId, sectionType, sectionId);
+                }
                 io.disconnect();
-                break;
             }
         }
     }, { threshold: [0, 0.3] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -4,7 +4,7 @@ The official SDK for integrating with Fragment-Shopify CMS. Provides React compo
 
 ## ✨ What's New
 
-**v2.2.0** - Google Analytics 4 (GA4) integration with automatic section tracking
+**v2.3.0** - Attribution tracking system and scroll-past engagement metrics
 
 > See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history
 
@@ -73,12 +73,21 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 
 ### Google Analytics 4 (GA4) Integration (v2.2.0+)
 
-- 📊 **Automatic Event Tracking**: Automatic `section_view` and `section_click` events
+- 📊 **Automatic Event Tracking**: Automatic section-specific events (`fragment_announcement_view`, `fragment_hero_banner_click`, etc.)
 - 🎯 **Type-Safe Section Types**: `SectionType` enum for consistent section identification
 - 🔧 **Configurable Tracking**: Control tracking via `measurementId`, `sectionId`, and `sectionType` fields
 - ⚡ **Dual Tracking**: Maintains existing pixel tracking while adding GA4 support
 - 🛡️ **Graceful Fallback**: Works even if GA4 is not configured (doesn't break functionality)
 - 📦 **Exported Types**: `SectionType` enum available for consumer use
+- 📈 **Scroll Past Tracking**: Automatic `scroll_past` events when users scroll past sections (v2.3.0+)
+
+### Attribution Tracking System (v2.3.0+)
+
+- 🎯 **Last-Click Attribution**: Session-scoped attribution tracking for section interactions
+- 💾 **SessionStorage Integration**: Stores attribution data in browser sessionStorage
+- 🔗 **Shopify Theme Integration**: Accessible via `window.fragmentAttribution` for purchase tracking
+- 📊 **Conversion Tracking**: Enables tracking which sections lead to conversions
+- 🧹 **Automatic Cleanup**: Attribution data can be cleared after successful conversion tracking
 
 ---