fragment-headless-sdk 2.3.0 → 2.3.2

package/dist/components/Announcement/AnnouncementButton.d.ts

@@ -1,7 +1,6 @@
 import React from "react";
 import { IAnnouncementContent } from "../../types";
-export default function AnnouncementButton({ content, buttonHref, clickHref, }: {
+export default function AnnouncementButton({ content, buttonHref, }: {
     content: IAnnouncementContent;
     buttonHref?: string;
-    clickHref?: string;
 }): React.JSX.Element | null;

package/dist/components/Announcement/AnnouncementButton.js

@@ -1,7 +1,7 @@
 import React from "react";
 import { ButtonType, SectionType } from "../../constants";
 import { fireClickMetric, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveAnnouncementColors, } from "../../utils";
-export default function AnnouncementButton({ content, buttonHref, clickHref, }) {
+export default function AnnouncementButton({ content, buttonHref, }) {
     // Don’t render if no button or explicitly None
     if (!content?.buttonText || content.buttonType === ButtonType.None)
         return null;
@@ -29,9 +29,7 @@ export default function AnnouncementButton({ content, buttonHref, clickHref, })
         delete attributes["aria-label"];
     }
     const handleClick = React.useCallback(() => {
-        if (!clickHref)
-            return;
-        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
-    }, [clickHref, content.measurementId, content.sectionType, content.sectionId]);
+        fireClickMetric(content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
+    }, [content.measurementId, content.sectionType, content.sectionId]);
     return (React.createElement("a", { href: buttonHref, className: className, style: style, onClick: handleClick, ...(attributes ?? {}), "aria-label": ariaLabel }, content.buttonText));
 }

package/dist/components/Announcement/index.js

@@ -1,21 +1,19 @@
+"use client";
 import { XMarkIcon } from "@heroicons/react/24/outline";
 import React, { useEffect, useRef } from "react";
 import { AnnouncementType, ButtonType, SectionType } from "../../constants";
-import { buildClickUrl, fireImpressionWhenVisible, getThemeClasses, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveAnnouncementColors, } from "../../utils";
+import { fireImpressionWhenVisible, getThemeClasses, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveAnnouncementColors, } from "../../utils";
 import AnnouncementButton from "./AnnouncementButton";
 import { AnnouncementStyles } from "./AnnouncementStyles";
 import CountdownTimer from "./CountdownTimer";
 export default function Announcement({ content, type, handleClose, }) {
     const ref = useRef(null);
     useEffect(() => {
-        if (ref.current && content.impressionUrl) {
-            fireImpressionWhenVisible(ref.current, content.impressionUrl, content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
+        if (ref.current) {
+            fireImpressionWhenVisible(ref.current, content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
         }
-    }, [content?.impressionUrl, content?.measurementId, content?.sectionType, content?.sectionId]);
+    }, [content?.measurementId, content?.sectionType, content?.sectionId]);
     const buttonHref = content?.buttonLink || undefined;
-    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
-        ? buildClickUrl(content.clickUrlBase, content.buttonLink)
-        : undefined;
     if (!content)
         return null;
     const styling = content.styling;
@@ -60,13 +58,13 @@ export default function Announcement({ content, type, handleClose, }) {
                         React.createElement("div", { className: marqueeContentClass, style: marqueeContentStyle, ...(marqueeContentAttributes ?? {}), dangerouslySetInnerHTML: {
                                 __html: content.announcementHtml || "",
                             } }))),
-                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
+                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
                 React.createElement("div", { className: announcementTextClass, style: announcementTextStyle, ...(announcementTextAttributes ?? {}) },
                     React.createElement("div", { dangerouslySetInnerHTML: {
                             __html: content.announcementHtml || "",
                         } })),
                 type === AnnouncementType.Countdown && (React.createElement(CountdownTimer, { content: content })),
-                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref })))),
+                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref })))),
             React.createElement("div", { onClick: handleClose, className: closeButtonClass, style: closeButtonStyle, ...(closeButtonAttributes ?? {}) },
                 React.createElement(XMarkIcon, { className: "w-5 h-5" })))));
 }

package/dist/components/Hero/DesktopHero.d.ts

@@ -3,7 +3,6 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface HeroViewProps {
     buttonHref?: string;
-    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     contentWidthClass: string;
@@ -11,5 +10,5 @@ interface HeroViewProps {
     position: "left" | "center" | "right";
     height: string;
 }
-export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
+export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
 export {};

package/dist/components/Hero/DesktopHero.js

@@ -2,7 +2,7 @@ import React from "react";
 import { SectionType } from "../../constants";
 import { fireClickMetric } from "../../utils";
 import { DEFAULT_CONTENT_WIDTH_CLASS, joinClassNames, renderText, } from "../../utils/hero-resolvers";
-export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }) {
+export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }) {
     const getPositionClasses = () => {
         switch (position) {
             case "center":
@@ -15,15 +15,8 @@ export default function DesktopHero({ buttonHref, clickHref, content, colors, co
         }
     };
     const handleClick = React.useCallback(() => {
-        if (!clickHref)
-            return;
-        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
-    }, [
-        clickHref,
-        content.measurementId,
-        content.sectionType,
-        content.sectionId,
-    ]);
+        fireClickMetric(content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
+    }, [content.measurementId, content.sectionType, content.sectionId]);
     return (React.createElement("div", { className: `relative ${height} gap-4 w-full`, style: { backgroundColor: colors.background } },
         content?.videoUrl ? (React.createElement("video", { src: content.videoUrl, autoPlay: true, muted: true, loop: true, playsInline: true, className: "absolute inset-0 z-0 object-cover w-full h-full" })) : (
         /* Image Background */

package/dist/components/Hero/MobileHero.d.ts

@@ -3,10 +3,9 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface MobileHeroProps {
     buttonHref?: string;
-    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     typography: ReturnType<typeof resolveHeroTypography>;
 }
-export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
+export default function MobileHero({ buttonHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
 export {};

package/dist/components/Hero/MobileHero.js

@@ -2,17 +2,10 @@ import React from "react";
 import { SectionType } from "../../constants";
 import { fireClickMetric } from "../../utils";
 import { renderText, } from "../../utils/hero-resolvers";
-export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }) {
+export default function MobileHero({ buttonHref, content, colors, typography, }) {
     const handleClick = React.useCallback(() => {
-        if (!clickHref)
-            return;
-        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
-    }, [
-        clickHref,
-        content.measurementId,
-        content.sectionType,
-        content.sectionId,
-    ]);
+        fireClickMetric(content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
+    }, [content.measurementId, content.sectionType, content.sectionId]);
     return (React.createElement("div", { className: "relative z-10 mx-auto gap-4 flex max-w-screen-md flex-col items-center justify-center py-6 text-center", style: { backgroundColor: colors.background } },
         renderText({
             fontSize: typography.title.fontSize,

package/dist/components/Hero/index.js

@@ -1,20 +1,18 @@
+"use client";
 import React, { useEffect, useRef } from "react";
 import { SectionType } from "../../constants";
-import { buildClickUrl, fireImpressionWhenVisible, } from "../../utils";
+import { fireImpressionWhenVisible, } from "../../utils";
 import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, } from "../../utils/hero-resolvers";
 import DesktopHero from "./DesktopHero";
 import MobileHero from "./MobileHero";
 export default function Hero({ content }) {
     const ref = useRef(null);
     useEffect(() => {
-        if (ref.current && content.impressionUrl) {
-            fireImpressionWhenVisible(ref.current, content.impressionUrl, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
+        if (ref.current) {
+            fireImpressionWhenVisible(ref.current, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
         }
-    }, [content?.impressionUrl, content?.measurementId, content?.sectionType, content?.sectionId]);
+    }, [content?.measurementId, content?.sectionType, content?.sectionId]);
     const buttonHref = content?.buttonLink || undefined;
-    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
-        ? buildClickUrl(content.clickUrlBase, content.buttonLink)
-        : undefined;
     if (!content)
         return null;
     const colors = resolveHeroColors(content);
@@ -24,7 +22,7 @@ export default function Hero({ content }) {
     const height = resolveHeight(content);
     return (React.createElement("div", { className: "bg-black", ref: ref, style: { backgroundColor: colors.background } },
         React.createElement("div", { className: "hidden lg:block" },
-            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
+            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
         React.createElement("div", { className: "block lg:hidden" },
-            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, typography: typography }))));
+            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, colors: colors, typography: typography }))));
 }

package/dist/types/announcement.d.ts

@@ -10,8 +10,6 @@ export interface IAnnouncementContent {
     buttonLink: string;
     announcementHtml: string;
     counterEndDate?: string;
-    impressionUrl: string;
-    clickUrlBase: string;
     measurementId?: string;
     sectionId?: string;
     sectionType?: SectionType;

package/dist/types/hero.d.ts

@@ -13,8 +13,6 @@ export interface IHeroContent {
     imageUrl: string;
     mobileImageUrl: string;
     videoUrl?: string;
-    impressionUrl: string;
-    clickUrlBase: string;
     measurementId?: string;
     sectionId?: string;
     sectionType?: SectionType;

package/dist/utils/attribution.d.ts

@@ -1,6 +1,7 @@
+import { SectionType } from '../constants';
 export interface FragmentAttribution {
     sectionId: string;
-    sectionType: 'announcement' | 'hero_banner';
+    sectionType: SectionType;
     timestamp: number;
 }
 /**
@@ -9,10 +10,10 @@ export interface FragmentAttribution {
  * @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;
+export declare function setAttribution(sectionId: string, sectionType: SectionType): void;
 /**
  * Retrieve stored attribution data
- * @returns The stored attribution or null if none exists
+ * @returns The stored attribution or null if none exists or data is invalid
  */
 export declare function getAttribution(): FragmentAttribution | null;
 /**
@@ -20,3 +21,12 @@ export declare function getAttribution(): FragmentAttribution | null;
  * Called after successful conversion tracking
  */
 export declare function clearAttribution(): void;
+declare global {
+    interface Window {
+        fragmentAttribution?: {
+            get: () => FragmentAttribution | null;
+            set: (sectionId: string, sectionType: SectionType) => void;
+            clear: () => void;
+        };
+    }
+}

package/dist/utils/attribution.js

@@ -1,3 +1,4 @@
+import { SectionType } from '../constants';
 const STORAGE_KEY = 'fragment_attribution';
 /**
  * Store attribution data for a section click
@@ -10,7 +11,7 @@ export function setAttribution(sectionId, sectionType) {
         return;
     const attribution = {
         sectionId,
-        sectionType: sectionType,
+        sectionType,
         timestamp: Date.now()
     };
     try {
@@ -21,20 +22,46 @@ export function setAttribution(sectionId, sectionType) {
         console.warn('Fragment: Failed to set attribution', e);
     }
 }
+/**
+ * Validates that parsed data matches the FragmentAttribution interface
+ */
+function isValidAttribution(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    return (typeof obj.sectionId === 'string' &&
+        (obj.sectionType === SectionType.Announcement || obj.sectionType === SectionType.HeroBanner) &&
+        typeof obj.timestamp === 'number');
+}
 /**
  * Retrieve stored attribution data
- * @returns The stored attribution or null if none exists
+ * @returns The stored attribution or null if none exists or data is invalid
  */
 export function getAttribution() {
     if (typeof sessionStorage === 'undefined')
         return null;
     try {
         const stored = sessionStorage.getItem(STORAGE_KEY);
-        return stored ? JSON.parse(stored) : null;
+        if (!stored)
+            return null;
+        const parsed = JSON.parse(stored);
+        if (!isValidAttribution(parsed)) {
+            // Invalid data - clear it and return null
+            sessionStorage.removeItem(STORAGE_KEY);
+            return null;
+        }
+        return parsed;
     }
     catch (e) {
         // Handle parse errors or other issues
         console.warn('Fragment: Failed to get attribution', e);
+        // Clear potentially corrupted data
+        try {
+            sessionStorage.removeItem(STORAGE_KEY);
+        }
+        catch {
+            // Ignore errors when clearing
+        }
         return null;
     }
 }

package/dist/utils/cache.js

@@ -15,12 +15,14 @@ export async function revalidateFragmentCache(tags) {
     try {
         // Dynamic import to avoid issues in non-Next.js environments
         // @ts-ignore - next/cache may not be available in all environments
-        const { revalidateTag } = await import("next/cache");
+        const mod = await import("next/cache");
+        // Cast: Next.js types vary by version (1 arg vs 2 arg with profile). Pass tag + "max" for Next 16+.
+        const revalidateTag = mod.revalidateTag;
         if (tags && tags.length > 0) {
             // Revalidate specific tags
             tags.forEach((tag) => {
                 try {
-                    revalidateTag(tag);
+                    revalidateTag(tag, "max");
                 }
                 catch (err) {
                     console.warn(`Failed to revalidate tag ${tag}:`, err);
@@ -31,7 +33,7 @@ export async function revalidateFragmentCache(tags) {
             // Revalidate all Fragment resource types
             Object.values(ResourceType).forEach((type) => {
                 try {
-                    revalidateTag(`fragment-${type}`);
+                    revalidateTag(`fragment-${type}`, "max");
                 }
                 catch (err) {
                     console.warn(`Failed to revalidate fragment-${type}:`, err);

package/dist/utils/metrics.d.ts

@@ -1,7 +1,5 @@
 import { SectionType } from "../constants";
-export declare function toBase64Url(input: string): string;
-export declare function buildClickUrl(clickUrlBase: string, targetHref: string): string;
-export declare function fireClickMetric(clickUrl: string, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;
+export declare function fireClickMetric(measurementId?: string, sectionType?: SectionType, sectionId?: string): void;
 declare global {
     interface Window {
         gtag?: (command: string, targetId: string | Date, config?: Record<string, unknown>) => void;
@@ -12,4 +10,4 @@ declare global {
  * 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;
+export declare function fireImpressionWhenVisible(el: HTMLElement, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;

package/dist/utils/metrics.js

@@ -1,68 +1,22 @@
 import { SectionType } from "../constants";
 import { setAttribution } from "./attribution";
-// --- Unicode-safe Base64URL ---
-export function toBase64Url(input) {
-    // Handles emojis & non-ASCII reliably:
-    const b64 = btoa(encodeURIComponent(input).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16))));
-    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-// --- Robust query appender ---
-function appendQuery(url, key, value) {
-    const sep = url.includes("?") ? "&" : "?";
-    return `${url}${sep}${key}=${value}`;
-}
-// Build the tracking URL that encodes the final destination for metrics
-export function buildClickUrl(clickUrlBase, targetHref) {
-    const u = encodeURIComponent(toBase64Url(targetHref));
-    return appendQuery(clickUrlBase, "u", u);
-}
-// Fire the click tracking URL without relying on a redirect
-// Default to GET so legacy tracking endpoints continue to accept the request
-export function fireClickMetric(clickUrl, measurementId, sectionType, sectionId) {
+export function fireClickMetric(measurementId, sectionType, sectionId) {
     if (typeof window === "undefined")
         return;
-    if (!clickUrl)
-        return;
-    // Store attribution for potential purchase/add-to-cart tracking
+    // Store attribution for potential purchase/add-to-cart
     if (sectionType && sectionId) {
         setAttribution(sectionId, sectionType);
     }
-    // Send to GA4 first (if available)
     if (measurementId && sectionType && sectionId) {
         sendGA4Event("click", measurementId, sectionType, sectionId);
     }
-    try {
-        if (typeof fetch === "function") {
-            fetch(clickUrl, {
-                method: "GET",
-                mode: "no-cors",
-                keepalive: true,
-            }).catch(() => {
-                /* no-op */
-            });
-            return;
-        }
-    }
-    catch {
-        // swallow and fall back to <img>
-    }
-    try {
-        const img = new Image();
-        img.referrerPolicy = "strict-origin-when-cross-origin";
-        img.src = clickUrl;
-    }
-    catch {
-        // nothing else we can do
-    }
 }
 /**
  * Generates a section-specific event name for GA4 tracking.
  * 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}`;
 }
 /**
@@ -104,25 +58,21 @@ export function fireScrollPastMetric(measurementId, sectionType, sectionId) {
 }
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
-export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionType, sectionId) {
+export function fireImpressionWhenVisible(el, measurementId, sectionType, sectionId) {
     if (typeof window === "undefined")
         return; // SSR guard
-    if (!el || !pixelUrl)
+    if (!el)
         return;
     if (seenEls && seenEls.has(el))
         return; // de-dupe by element
     let fired = false;
     let hasScrolledPast = false;
-    const img = new Image();
     const fire = () => {
         if (fired)
             return;
         fired = true;
         if (seenEls)
             seenEls.add(el);
-        img.referrerPolicy = "strict-origin-when-cross-origin";
-        img.src = pixelUrl; // GET to your /api/v1/metrics/i?e=...&sig=...
-        // Also send to GA4 if available
         if (measurementId && sectionType && sectionId) {
             sendGA4Event("view", measurementId, sectionType, sectionId);
         }
@@ -140,18 +90,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)
+                // User scrolled past the section (it's above viewport and was previously visible)
                 hasScrolledPast = true;
                 if (measurementId && sectionType && sectionId) {
                     fireScrollPastMetric(measurementId, sectionType, sectionId);
                 }
                 io.disconnect();
+                break;
             }
         }
     }, { threshold: [0, 0.3] });

package/docs/CHANGELOG.md

@@ -0,0 +1,555 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+### [Unreleased]
+
+#### Removed
+
+### [2.3.2] - 2026-02-27
+
+#### Removed
+
+- **Legacy server-side tracking** – The previous pixel/click tracking system has been fully replaced by Google Analytics 4 (GA4):
+  - `impressionUrl` and `clickUrlBase` on content objects are no longer used; the API now provides `measurementId`, `sectionId`, and `sectionType` for GA4 events.
+  - The `makeSignedMetricUrls` helper and server-side `/api/v1/t` endpoints (impression/click) have been removed from the Fragment app; the SDK sends view/click/scroll_past via `gtag` only.
+  - See [2.2.0] for GA4 integration details. Historical entries [1.0.5] and earlier described the old pixel-based flow.
+
+### [2.3.1] - 2026-01-25
+
+### 🔧 Technical Improvements
+
+- **Enhanced Error Handling** – Improved error handling in attribution functions
+  - Better error messages and logging
+  - Automatic cleanup of corrupted data
+  - Graceful degradation when sessionStorage is unavailable
+
+## [2.3.0] - 2026-01-25
+
+### ✨ Attribution Tracking System
+
+- **Session-Based Attribution** – New attribution tracking system for purchase/add-to-cart attribution
+  - Automatically stores attribution data when users click section buttons
+  - Uses sessionStorage for session-scoped attribution (last-click wins)
+  - Tracks section ID, section type, and timestamp for each click
+
+### 📚 Documentation
+
+- **New Attribution Section** – Added comprehensive documentation for attribution tracking
+  - Usage examples for Shopify theme integrations
+  - Programmatic access examples
+  - Use cases for purchase and add-to-cart attribution
+
+## [2.2.0] - 2025-01-18
+
+### ✨ Google Analytics 4 (GA4) Integration
+
+- **GA4 Event Tracking** – Added comprehensive Google Analytics 4 integration for section tracking
+  - Automatic `section_view` events when sections become visible
+  - Automatic `section_click` events when users interact with buttons
+  - Configurable via `measurementId`, `sectionId`, and `sectionType` fields
+  - Graceful fallback if GA4 is not available (doesn't break functionality)
+
+## [2.1.9] - 2025-12-26
+
+### ✨ Announcement Resolvers System
+
+- **New Announcement Resolvers Utility** – Added centralized color resolution system for Announcement components
+  - `resolveAnnouncementColors()` – Intelligent color resolution with guaranteed fallback values
+  - `resolveCountdownColors()` – Dedicated color resolver for countdown timer styling
+  - Supports both new format (`colors.background`) and legacy format (`bgColor`) for backward compatibility
+
+### 🔧 Component Refactoring
+
+- **Centralized Color Resolution** – Refactored all Announcement components to use the new resolver system
+  - Improved code maintainability and consistency across all announcement types
+
+### 🎨 Countdown Timer Styling Improvements
+
+- **Enhanced Layout** – Improved visual spacing and sizing
+  - Added `gap-1` between countdown digits
+  - Reduced digit font size from `text-xl` to `text-lg`
+  - Changed line height from `leading-none` to `leading-tight`
+
+### 🔧 Type System Updates
+
+- **Enhanced Type Definitions** – Updated `IAnnouncement` and `IHero` interfaces
+  - Added `active_duration_seconds`, `last_activated_at`, and `last_deactivated_at` fields
+
+### 📚 Documentation
+
+- **New Announcement Resolvers Documentation** – Added comprehensive guide for the new resolver system
+
+## [2.1.8] - 2025-12-25
+
+### ✨ Countdown Timer Styling Enhancements
+
+- **Enhanced Countdown Timer Color Tokens** – Added comprehensive color customization for countdown timers
+  - `counterDigitColor` – Customize the color of countdown digits (default: `#FFFFFF`)
+  - `counterDigitBackgroundColor` – Customize the background color of countdown digits (default: `#000000`)
+  - `counterTextColor` – Customize the color of labels and separators (default: uses `counterDigitColor`)
+- **Fixed Token Resolution** – Corrected `counterTextColor` token resolution to use proper fallback handling
+- **Documentation Updates** – Added comprehensive countdown timer styling documentation to README
+
+## [2.1.5] - 2025-12-05
+
+### 🔧 Type System Updates
+
+- **Enhanced Type Definitions** – Updated `IAnnouncement` and `IHero` interfaces to match Supabase schema
+  - Added `active_start_date: string | null` field
+  - Added `active_end_date: string | null` field
+  - Made `created_at` and `updated_at` nullable
+  - Made `page` field nullable in `IHero`
+
+### 🗑️ Breaking Changes
+
+- **Removed Theme & Variant System** – Simplified styling system by removing unused theme/variant abstractions
+  - Removed `theme` property from `IFragmentStyling`
+  - Removed `variant` property from `IFragmentStyling`
+  - Focus now exclusively on design tokens, slots, responsive design, and state-based styling
+  - Updated all documentation to reflect the simplified system
+
+## [2.1.4] - 2025-11-18
+
+### ✨ UI/UX Improvements
+
+- **Countdown Timer Enhancements** – Improved countdown timer visual design
+  - Removed background color from countdown digits for cleaner appearance
+  - Increased digit font size for better visibility
+  - Shortened label text: "Minutes" → "Mins", "Seconds" → "Secs"
+
+- **Announcement Component Updates** – Enhanced announcement functionality
+  - Countdown timers can now display alongside buttons when both are enabled
+  - Improved layout flexibility for countdown announcements with CTAs
+
+## [2.1.2] - 2025-10-30
+
+### 📚 Documentation Updates
+
+- **Enhanced README** – Updated documentation to highlight new click tracking features
+- **Feature Highlights** – Added comprehensive documentation for the enhanced click tracking system
+- **Usage Examples** – Improved examples showing the separation of button destinations and tracking
+
+## [2.1.1] - 2025-10-30
+
+### 🎯 Enhanced Click Tracking System
+
+- **Improved Click Tracking Architecture** – Separated button destinations from click tracking for better user experience
+  - `buttonHref` now contains the actual destination URL (no redirect)
+  - `clickHref` contains the tracking URL for metrics collection
+  - Users go directly to intended destinations instead of through redirects
+- **New `fireClickMetric()` Function** – Advanced click tracking without relying on redirects
+  - Uses `fetch()` with `no-cors` mode and `keepalive` for reliable tracking
+  - Falls back to Image pixel tracking for maximum compatibility
+  - Handles server-side rendering gracefully
+- **Removed Automatic New Tab Behavior** – Links no longer force `target="_blank"`
+  - Provides more natural user experience
+  - Allows developers to control link behavior explicitly
+  - Maintains accessibility with proper ARIA labels
+
+### 🛠 Technical Improvements
+
+- **Enhanced Component Props** – Both Hero and Announcement components now accept separate tracking parameters
+  - `buttonHref` for the actual destination
+  - `clickHref` for tracking metrics
+- **Better Error Handling** – Click tracking fails gracefully without affecting user experience
+- **Performance Optimized** – Non-blocking click tracking that doesn't delay navigation
+- **Cross-Browser Compatible** – Works across all modern browsers with appropriate fallbacks
+
+### 📝 Usage Examples
+
+```typescript
+// The SDK automatically handles the separation of concerns
+const heroContent = {
+  title: "Shop Now",
+  buttonText: "Get Started",
+  buttonLink: "https://example.com/products", // Direct destination
+  clickUrlBase: "https://tracking.example.com/click", // Tracking base
+  // SDK automatically creates:
+  // - buttonHref: "https://example.com/products" (direct link)
+  // - clickHref: "https://tracking.example.com/click?u=..." (tracking)
+};
+
+<Hero content={heroContent} />;
+```
+
+### ⚡ Performance Benefits
+
+- **Faster Navigation** – Users go directly to destinations without redirect delays
+- **Reliable Tracking** – Click metrics are captured even if users navigate away quickly
+- **Better SEO** – Direct links improve search engine crawling and indexing
+- **Enhanced UX** – More predictable link behavior for better user experience
+
+### 🔄 Backward Compatibility
+
+- **No Breaking Changes** – All existing implementations continue to work
+- **Automatic Upgrade** – New tracking system activates automatically when `clickUrlBase` is present
+- **Legacy Support** – Existing tracking URLs continue to function as before
+
+## [2.1.0] - 2025-10-27
+
+### 🎨 Enhanced Hero Styling System
+
+- **New Hero Resolvers Utility** – Comprehensive utility system for advanced Hero component customization
+  - `resolveHeroColors()` – Intelligent color resolution with fallback handling
+  - `resolveHeroTypography()` – Typography settings with font family, size, and line height control
+  - `resolveContentWidthClass()` – Dynamic content width management
+  - `resolvePosition()` – Content positioning (left, center, right alignment)
+  - `resolveHeight()` – Flexible height configuration
+  - `renderText()` – Unified text rendering with typography and styling support
+
+### ✨ Advanced Typography Features
+
+- **Font Family Support** – Built-in support for popular font families:
+  - Roboto, Open Sans, Lato, Montserrat, Poppins, Inter, Nunito Sans, Source Sans Pro
+  - Custom font family support through `FontKey` type system
+- **Responsive Typography** – Granular control over font sizes and line heights
+  - Separate title and description typography settings
+  - Tailwind CSS class integration for responsive design
+- **Typography Tokens** – New styling tokens for enhanced typography control:
+  - `titleFontSize`, `titleLineHeight`, `titleFont`
+  - `descriptionFontSize`, `descriptionLineHeight`, `descriptionFont`
+
+### 🏗️ Layout & Positioning Enhancements
+
+- **Content Positioning** – New positioning system for Hero content alignment
+  - Left, center, and right alignment options
+  - Responsive positioning with proper text alignment
+- **Content Width Control** – Dynamic content width management
+  - Configurable content container widths
+  - Responsive design integration
+- **Height Management** – Flexible height configuration system
+  - Custom height classes support
+  - Default height fallbacks
+
+### 🎯 Developer Experience Improvements
+
+- **Type Safety** – Enhanced TypeScript interfaces for all new features
+  - `HeroResolvedColors` interface for color resolution
+  - `HeroTypographySettings` interface for typography configuration
+  - `FontKey` type for font family validation
+- **Utility Functions** – New helper functions for common operations
+  - `joinClassNames()` – Safe CSS class concatenation
+  - `fallbackColor()` – Color value validation with fallbacks
+- **Better Defaults** – Comprehensive default values for all styling options
+  - `DEFAULT_COLORS` for color fallbacks
+  - `DEFAULT_TYPOGRAPHY` for typography defaults
+  - `FONT_FAMILY_MAP` for font family mappings
+
+### 🔄 Backward Compatibility
+
+- **Seamless Migration** – All existing Hero components continue to work without changes
+- **Progressive Enhancement** – New features are opt-in and don't affect existing implementations
+- **Legacy Support** – Existing styling approaches remain fully supported
+
+### 📝 Usage Examples
+
+```typescript
+// Enhanced Hero with new typography and positioning
+const heroContent = {
+  title: "Welcome to Our Store",
+  description: "Discover amazing products",
+  buttonText: "Shop Now",
+  buttonLink: "/products",
+  imageUrl: "https://example.com/hero.jpg",
+
+  styling: {
+    tokens: {
+      colors: {
+        title: "#ffffff",
+        text: "#f0f0f0",
+        button: "#007bff",
+        buttonText: "#ffffff",
+        background: "#1a1a1a",
+      },
+      typography: {
+        titleFont: "montserrat",
+        titleFontSize: "text-6xl",
+        titleLineHeight: "leading-tight",
+        descriptionFont: "inter",
+        descriptionFontSize: "text-xl",
+        descriptionLineHeight: "leading-relaxed",
+      },
+      layout: {
+        contentWidth: "max-w-4xl",
+        position: "center",
+        height: "min-h-screen",
+      },
+    },
+  },
+};
+```
+
+### 🛠 Technical Improvements
+
+- **Performance Optimized** – Efficient color and typography resolution
+- **Memory Efficient** – Optimized utility functions with minimal overhead
+- **Tree Shakeable** – Individual utility functions can be imported separately
+- **CSS-in-JS Ready** – Full compatibility with styled-components and emotion
+
+## [1.0.6] - 2025-10-16
+
+### 🚀 Next.js Caching Fix
+
+- **Fixed Vercel/Next.js Caching Issues** – Resolved aggressive caching that prevented fresh data from appearing in production deployments
+  - Added `cache: 'no-store'` by default for all `fetchResource()` calls
+  - Added Next.js-specific `revalidate: 0` configuration
+  - Added cache-busting headers (`Cache-Control`, `Pragma`) to prevent CDN caching
+  - Smart environment detection for Next.js vs other frameworks
+
+### ✨ New Cache Management Features
+
+- **Cache Configuration Options** – Added optional `cacheOptions` parameter to `fetchResource()`
+  - `cache`: Control request cache mode (default: 'no-store' for fresh data)
+  - `revalidate`: Next.js revalidation time in seconds (default: 0)
+  - `tags`: Next.js cache tags for selective invalidation
+- **Cache Invalidation Utilities** – New helper functions for cache management
+  - `revalidateFragmentCache()` – Invalidate all or specific Fragment caches
+  - `revalidateResourceType()` – Invalidate cache for specific resource type
+  - `revalidateAllFragmentCaches()` – Clear all Fragment-related caches
+  - `createCacheTag()` / `createCacheTags()` – Generate cache tags
+
+### 🛠 Technical Improvements
+
+- **Environment Detection** – Automatic Next.js environment detection for optimal cache settings
+- **Backward Compatibility** – All existing code continues to work without changes
+- **TypeScript Support** – Full type definitions for new cache options
+
+### 📝 Usage Examples
+
+```typescript
+// Default behavior - always fresh data (recommended)
+const announcements = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.Announcements,
+});
+
+// Optional: Enable caching for performance
+const cachedHeroes = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+  cacheOptions: {
+    cache: "default",
+    revalidate: 300, // 5 minutes
+  },
+});
+
+// Cache invalidation (server-side only)
+import { revalidateResourceType } from "fragment-headless-sdk";
+await revalidateResourceType(ResourceType.Announcements);
+```
+
+### ⚠️ Migration Notes
+
+- **No breaking changes** – Existing code works without modification
+- **Fresh data by default** – Your database updates will now appear immediately in production
+- **Opt-in caching** – Use `cacheOptions` if you want to enable caching for performance
+
+## [1.0.5] - 2025-09-28
+
+### ✨ New Features
+
+- **Metrics Tracking** – Added built-in view and click tracking for both **Hero** and **Announcement** sections.
+  - Each resource’s `content` object now includes two server-generated fields:
+    - `impressionUrl` – 1×1 pixel URL automatically fired when the component enters the viewport.
+    - `clickUrlBase` – base redirect URL used to record button clicks before sending the user to the final destination.
+  - The SDK’s `<Hero>` and `<Announcement>` components now automatically:
+    - trigger a view pixel when visible, and
+    - wrap their CTA buttons with a signed click-tracking redirect.
+
+### 🛠 Technical Notes
+
+- The `makeSignedMetricUrls` helper was refactored to attach `impressionUrl` and `clickUrlBase` **inside the `content` object** for each item returned by the API.
+- New client-side utilities exported from `utils`:
+  - `buildClickUrl()` – safely appends the final destination (`&u=...`) to a signed `clickUrlBase`.
+  - `fireImpressionWhenVisible()` – fires a pixel only once when an element is at least 30 % visible.
+
+### ⚠️ Migration Notes
+
+- **No breaking changes.**  
+  Existing components continue to work; the new tracking is automatic when you upgrade to v1.0.5.
+- If you build custom CTAs outside the provided components, use the new helpers to track clicks and views manually.
+
+## [1.0.4] - 2025-09-27
+
+- **Types:** `IHero` now includes `views_count: number` and `clicks_count: number`.
+
+### 📝 Notes
+
+- No breaking changes..
+
+## [1.0.3] - 2025-09-21
+
+### 🎨 UI/UX Improvements
+
+- **Announcement Type Rename** - Changed `AnnouncementType.Announcement` to `AnnouncementType.Static` for better clarity
+- **Countdown Timer Styling** - Removed white background from countdown timer for cleaner appearance
+- **Layout Optimization** - Improved announcement banner layout with:
+  - Removed top/bottom padding (`py-3`) for more compact design
+  - Added 50px minimum height for consistent banner sizing
+  - Enhanced vertical centering of all content elements
+- **Timer Digit Sizing** - Made countdown timer digits smaller and more compact:
+  - Reduced digit size from 24×28px to 20×24px
+  - Changed font size from `text-xl` to `text-base`
+
+### 🔧 Technical Changes
+
+- Updated `announcementTypes` array to reflect new "Static" label
+- Improved flexbox layout for better vertical alignment
+- Maintained responsive design across all screen sizes
+
+## [1.0.2] - 2025-09-20
+
+### 🔄 Breaking Changes
+
+- **Component Naming** - Renamed `Banner` component and all related types to `Announcement`
+  - `Banner` → `Announcement`
+  - `IBannerContent` → `IAnnouncementContent`
+  - `IBanner` → `IAnnouncement`
+  - `BannerType` → `AnnouncementType`
+  - `BannerStatus` → `AnnouncementStatus`
+  - `BannerButton` → `AnnouncementButton`
+  - `BannerStyles` → `AnnouncementStyles`
+  - `bannerHtml` property → `announcementHtml`
+
+- **Resource Type Updates** - Updated resource type enums for consistency
+  - `ResourceType.HeroSections` → `ResourceType.HeroBanners`
+  - `ResourceType.Banners` → `ResourceType.Announcements`
+
+### 🔗 API Endpoint Changes
+
+- Updated API endpoints to match new naming:
+  - `/api/v1/hero-sections` → `/api/v1/hero-banners`
+  - `/api/v1/banners` → `/api/v1/announcements`
+
+### 📚 Documentation
+
+- Updated all documentation to reflect new component and type names
+- Updated README.md examples with new ResourceType values
+- Updated code examples throughout
+
+### 🛠️ Migration Guide
+
+To update your existing code:
+
+```typescript
+// Before (v1.0.1)
+import {
+  Banner,
+  BannerType,
+  IBannerContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const banners = await fetchResource({
+  type: ResourceType.Banners,
+});
+
+<Banner content={bannerContent} type={BannerType.Standard} />;
+
+// After (v1.0.2)
+import {
+  Announcement,
+  AnnouncementType,
+  IAnnouncementContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const announcements = await fetchResource({
+  type: ResourceType.Announcements,
+});
+
+<Announcement
+  content={announcementContent}
+  type={AnnouncementType.Announcement}
+/>;
+```
+
+## [1.0.1] - 2025-09-07
+
+### 🎉 Initial Release
+
+The official SDK for integrating with fragment-shopify CMS. Production-ready with full API key authentication support.
+
+### Features
+
+- **Complete TypeScript Support** - Full type definitions for all components and API responses
+- **React Components** - Pre-built Hero and Announcement components with responsive design
+- **API Integration** - Built-in utilities for fetching sections from fragment-shopify app
+- **Production Ready** - Full API key authentication with v1 endpoints
+- **Tailwind CSS** - Styled components with customizable design system
+
+### Components
+
+- **Hero Component** - Responsive hero sections with desktop/mobile layouts
+  - Support for images, videos, and call-to-action buttons
+  - Customizable content and styling
+- **Announcement Component** - Flexible announcement bars with multiple display types
+  - Standard, marquee, and countdown announcement types
+  - `AnnouncementButton` and `CountdownTimer` sub-components
+
+### API Integration
+
+- **`fetchResource()` Function** - Simple API for fetching sections
+- **API Key Authentication** - Secure authentication using `keyId:secret` format
+- **v1 Endpoints** - Production endpoints (`/api/v1/announcements`, `/api/v1/hero-banners`)
+- **Error Handling** - Comprehensive error handling and logging
+- **Type Safety** - Full TypeScript support for all API responses
+
+### Usage
+
+```tsx
+import {
+  fetchResource,
+  ResourceType,
+  Hero,
+  Announcement,
+} from "fragment-headless-sdk";
+
+// Fetch data
+const heroes = await fetchResource({
+  baseUrl: process.env.EXTERNAL_API_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+});
+
+// Render components
+<Hero content={heroes[0]?.content} />;
+```
+
+### Environment Variables
+
+```bash
+EXTERNAL_API_URL=https://your-fragment-app.vercel.app
+FRAGMENT_API_KEY=bh_a1b2c3d4e5f6:your-64-char-secret
+```
+
+---
+
+## Upcoming Changes
+
+### v1.1.0 (Planned)
+
+- Enhanced error handling with specific error types
+- Support for additional section types
+- Caching and performance optimizations
+
+### v1.2.0 (Planned)
+
+- Real-time updates via webhooks
+- Advanced filtering and sorting options
+- Batch operations support
+- TypeScript strict mode compatibility
+
+---
+
+## Support
+
+- **Documentation**: [README.md](./README.md)
+- **NPM Package**: https://www.npmjs.com/package/fragment-shopify-sdk
+- **Issues**: Please report issues in the GitHub repository

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.3.0",
+  "version": "2.3.2",
+  "description": "Headless SDK for Fragment Shopify storefronts",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,14 +13,37 @@
     "./styles": "./dist/styles/fragment-sdk.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/CHANGELOG.md"
   ],
+  "sideEffects": false,
   "scripts": {
-    "build": "tsc"
+    "build": "tsc && mkdir -p dist/styles && cp src/styles/*.css dist/styles/",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sevenbrand/fragment-monorepo",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "shopify",
+    "headless",
+    "fragment",
+    "sdk",
+    "storefront"
+  ],
   "dependencies": {
-    "@heroicons/react": "^2.2.0",
-    "react": "^19.1.0"
+    "@heroicons/react": "^2.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.2",

package/readme.md

@@ -4,7 +4,7 @@ The official SDK for integrating with Fragment-Shopify CMS. Provides React compo
 
 ## ✨ What's New
 
-**v2.3.0** - Attribution tracking system and scroll-past engagement metrics
+**v2.3.1** - Enhanced attribution tracking with session storage and global API
 
 > See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history
 
@@ -73,21 +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-specific events (`fragment_announcement_view`, `fragment_hero_banner_click`, etc.)
+- 📊 **Automatic Event Tracking**: Automatic `section_view` and `section_click` events
 - 🎯 **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+)
+### Attribution Tracking System (v2.4.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
+- 🎯 **Session-Based Attribution**: Tracks which section was clicked for purchase/add-to-cart attribution
+- 💾 **SessionStorage Integration**: Uses sessionStorage for session-scoped attribution (last-click wins)
+- 🌐 **Global API Access**: Exposed as `window.fragmentAttribution` for Shopify theme integrations
+- 🔒 **Type-Safe**: Full TypeScript support with proper type definitions
+- ✅ **Data Validation**: Automatic validation and cleanup of corrupted attribution data
+- 🧹 **Auto-Cleanup**: Invalid or corrupted data is automatically cleared from storage
 
 ---
 
@@ -126,7 +126,7 @@ module.exports = {
     "./components/**/*.{js,ts,jsx,tsx,mdx}",
     path.join(
       __dirname,
-      "node_modules/fragment-headless-sdk/dist/**/*.{js,ts,jsx,tsx}"
+      "node_modules/fragment-headless-sdk/dist/**/*.{js,ts,jsx,tsx}",
     ),
   ],
   theme: {
@@ -377,8 +377,9 @@ interface IHeroContent {
   imageUrl: string;
   mobileImageUrl: string;
   videoUrl?: string;
-  impressionUrl: string;
-  clickUrlBase: string;
+  measurementId?: string;   // GA4 measurement ID (from app config)
+  sectionId?: string;      // Section ID for GA4 event params
+  sectionType?: SectionType;
   styling?: IHeroStyling; // v2.0+ enhanced styling
 }
 ```
@@ -434,8 +435,9 @@ interface IAnnouncementContent {
   buttonLink: string;
   announcementHtml: string;
   counterEndDate?: string;
-  impressionUrl: string;
-  clickUrlBase: string;
+  measurementId?: string;   // GA4 measurement ID (from app config)
+  sectionId?: string;       // Section ID for GA4 event params
+  sectionType?: SectionType;
   styling?: IAnnouncementStyling; // v2.0+ enhanced styling
 }
 ```
@@ -490,6 +492,105 @@ const announcementContent = {
 };
 ```
 
+## 🎯 Attribution Tracking
+
+The SDK automatically tracks which section was clicked for attribution purposes. This is useful for tracking conversions (purchases, add-to-cart) back to the original section interaction.
+
+### Automatic Attribution
+
+When a user clicks a button in a Hero or Announcement section, the SDK automatically stores attribution data in `sessionStorage`:
+
+```typescript
+// Attribution is automatically set when clicks occur
+// No additional code needed - it happens automatically!
+```
+
+### Global API (Shopify Theme Integration)
+
+For Shopify theme integrations, attribution data is exposed globally via `window.fragmentAttribution`:
+
+```javascript
+// Get current attribution data
+const attribution = window.fragmentAttribution.get();
+// Returns: { sectionId: "uuid", sectionType: "announcement" | "hero_banner", timestamp: 1234567890 }
+// Or: null if no attribution exists
+
+// Manually set attribution (usually not needed - SDK handles this automatically)
+window.fragmentAttribution.set("section-uuid", "announcement");
+
+// Clear attribution (e.g., after successful conversion tracking)
+window.fragmentAttribution.clear();
+```
+
+### Programmatic Access
+
+You can also import and use attribution functions directly:
+
+```typescript
+import { getAttribution, clearAttribution } from "fragment-headless-sdk";
+
+// Get attribution data
+const attribution = getAttribution();
+if (attribution) {
+  console.log(`User clicked section: ${attribution.sectionId}`);
+  console.log(`Section type: ${attribution.sectionType}`);
+  console.log(`Clicked at: ${new Date(attribution.timestamp)}`);
+}
+
+// Clear attribution after tracking conversion
+clearAttribution();
+```
+
+### Use Cases
+
+**Purchase Attribution:**
+
+```javascript
+// In your Shopify checkout success page
+if (window.fragmentAttribution) {
+  const attribution = window.fragmentAttribution.get();
+  if (attribution) {
+    // Track purchase back to the section click
+    // e.g., send to analytics, update database, etc.
+    trackPurchase(attribution.sectionId, attribution.sectionType);
+
+    // Clear attribution after tracking
+    window.fragmentAttribution.clear();
+  }
+}
+```
+
+**Add-to-Cart Attribution:**
+
+```javascript
+// In your add-to-cart handler
+if (window.fragmentAttribution) {
+  const attribution = window.fragmentAttribution.get();
+  if (attribution) {
+    // Track add-to-cart back to the section click
+    trackAddToCart(attribution.sectionId, attribution.sectionType);
+  }
+}
+```
+
+### Attribution Data Structure
+
+```typescript
+interface FragmentAttribution {
+  sectionId: string; // UUID of the section that was clicked
+  sectionType: SectionType; // "announcement" | "hero_banner"
+  timestamp: number; // Unix timestamp of when the click occurred
+}
+```
+
+### Features
+
+- ✅ **Session-Scoped**: Attribution data persists for the browser session only
+- ✅ **Last-Click Wins**: New clicks overwrite previous attribution data
+- ✅ **Type-Safe**: Full TypeScript support with proper type definitions
+- ✅ **Data Validation**: Automatically validates and cleans corrupted data
+- ✅ **Graceful Degradation**: Works even if sessionStorage is unavailable
+
 ## 🔑 API Key Setup
 
 Before using the SDK, you need to generate an API key from your Fragment-Shopify app: