fragment-headless-sdk 2.1.9 → 2.2.0

package/dist/components/Announcement/AnnouncementButton.js

@@ -1,5 +1,5 @@
 import React from "react";
-import { ButtonType } from "../../constants";
+import { ButtonType, SectionType } from "../../constants";
 import { fireClickMetric, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveAnnouncementColors, } from "../../utils";
 export default function AnnouncementButton({ content, buttonHref, clickHref, }) {
     // Don’t render if no button or explicitly None
@@ -31,7 +31,7 @@ export default function AnnouncementButton({ content, buttonHref, clickHref, })
     const handleClick = React.useCallback(() => {
         if (!clickHref)
             return;
-        fireClickMetric(clickHref);
-    }, [clickHref]);
+        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
+    }, [clickHref, 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,6 +1,6 @@
 import { XMarkIcon } from "@heroicons/react/24/outline";
 import React, { useEffect, useRef } from "react";
-import { AnnouncementType, ButtonType } from "../../constants";
+import { AnnouncementType, ButtonType, SectionType } from "../../constants";
 import { buildClickUrl, fireImpressionWhenVisible, getThemeClasses, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveAnnouncementColors, } from "../../utils";
 import AnnouncementButton from "./AnnouncementButton";
 import { AnnouncementStyles } from "./AnnouncementStyles";
@@ -9,9 +9,9 @@ export default function Announcement({ content, type, handleClose, }) {
     const ref = useRef(null);
     useEffect(() => {
         if (ref.current && content.impressionUrl) {
-            fireImpressionWhenVisible(ref.current, content.impressionUrl);
+            fireImpressionWhenVisible(ref.current, content.impressionUrl, content.measurementId, content.sectionType || SectionType.Announcement, content.sectionId);
         }
-    }, [content?.impressionUrl]);
+    }, [content?.impressionUrl, content?.measurementId, content?.sectionType, content?.sectionId]);
     const buttonHref = content?.buttonLink || undefined;
     const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)

package/dist/components/Hero/DesktopHero.js

@@ -1,4 +1,5 @@
 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, }) {
@@ -16,8 +17,13 @@ export default function DesktopHero({ buttonHref, clickHref, content, colors, co
     const handleClick = React.useCallback(() => {
         if (!clickHref)
             return;
-        fireClickMetric(clickHref);
-    }, [clickHref]);
+        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
+    }, [
+        clickHref,
+        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.js

@@ -1,12 +1,18 @@
 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, }) {
     const handleClick = React.useCallback(() => {
         if (!clickHref)
             return;
-        fireClickMetric(clickHref);
-    }, [clickHref]);
+        fireClickMetric(clickHref, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
+    }, [
+        clickHref,
+        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,4 +1,5 @@
 import React, { useEffect, useRef } from "react";
+import { SectionType } from "../../constants";
 import { buildClickUrl, fireImpressionWhenVisible, } from "../../utils";
 import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, } from "../../utils/hero-resolvers";
 import DesktopHero from "./DesktopHero";
@@ -7,9 +8,9 @@ export default function Hero({ content }) {
     const ref = useRef(null);
     useEffect(() => {
         if (ref.current && content.impressionUrl) {
-            fireImpressionWhenVisible(ref.current, content.impressionUrl);
+            fireImpressionWhenVisible(ref.current, content.impressionUrl, content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
         }
-    }, [content?.impressionUrl]);
+    }, [content?.impressionUrl, content?.measurementId, content?.sectionType, content?.sectionId]);
     const buttonHref = content?.buttonLink || undefined;
     const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)

package/dist/constants/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./announcement";
 export * from "./hero";
+export * from "./section";

package/dist/constants/index.js

@@ -1,2 +1,3 @@
 export * from "./announcement";
 export * from "./hero";
+export * from "./section";

package/dist/constants/section.d.ts

@@ -0,0 +1,4 @@
+export declare enum SectionType {
+    Announcement = "announcement",
+    HeroBanner = "hero_banner"
+}

package/dist/constants/section.js

@@ -0,0 +1,5 @@
+export var SectionType;
+(function (SectionType) {
+    SectionType["Announcement"] = "announcement";
+    SectionType["HeroBanner"] = "hero_banner";
+})(SectionType || (SectionType = {}));

package/dist/types/announcement.d.ts

@@ -1,4 +1,4 @@
-import { AnnouncementStatus, AnnouncementType, ButtonType } from "../constants";
+import { AnnouncementStatus, AnnouncementType, ButtonType, SectionType } from "../constants";
 import { IAnnouncementStyling } from "./styling";
 export declare const buttonTypes: {
     label: string;
@@ -12,6 +12,9 @@ export interface IAnnouncementContent {
     counterEndDate?: string;
     impressionUrl: string;
     clickUrlBase: string;
+    measurementId?: string;
+    sectionId?: string;
+    sectionType?: SectionType;
     styling?: IAnnouncementStyling;
 }
 export interface IAnnouncement {

package/dist/types/hero.d.ts

@@ -1,4 +1,4 @@
-import { HeroStatus, HeroType } from "../constants";
+import { HeroStatus, HeroType, SectionType } from "../constants";
 import { IHeroStyling } from "./styling";
 export type ShopPage = {
     id: string;
@@ -15,6 +15,9 @@ export interface IHeroContent {
     videoUrl?: string;
     impressionUrl: string;
     clickUrlBase: string;
+    measurementId?: string;
+    sectionId?: string;
+    sectionType?: SectionType;
     styling?: IHeroStyling;
 }
 export interface IHero {

package/dist/utils/metrics.d.ts

@@ -1,4 +1,11 @@
+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): void;
-export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string): void;
+export declare function fireClickMetric(clickUrl: string, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;
+declare global {
+    interface Window {
+        gtag?: (command: string, targetId: string | Date, config?: Record<string, unknown>) => void;
+        dataLayer?: unknown[];
+    }
+}
+export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;

package/dist/utils/metrics.js

@@ -16,11 +16,15 @@ export function buildClickUrl(clickUrlBase, targetHref) {
 }
 // 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) {
+export function fireClickMetric(clickUrl, measurementId, sectionType, sectionId) {
     if (typeof window === "undefined")
         return;
     if (!clickUrl)
         return;
+    // Send to GA4 first (if available)
+    if (measurementId && sectionType && sectionId) {
+        sendGA4Event("section_click", measurementId, sectionType, sectionId);
+    }
     try {
         if (typeof fetch === "function") {
             fetch(clickUrl, {
@@ -45,9 +49,32 @@ export function fireClickMetric(clickUrl) {
         // nothing else we can do
     }
 }
+/**
+ * Sends a GA4 event if gtag is available and measurementId is provided.
+ * This is a fire-and-forget operation that won't throw errors.
+ */
+function sendGA4Event(eventName, measurementId, sectionType, sectionId) {
+    if (typeof window === "undefined")
+        return;
+    if (!measurementId)
+        return;
+    if (!window.gtag)
+        return;
+    try {
+        window.gtag("event", eventName, {
+            section_type: sectionType,
+            section_id: sectionId,
+            event_category: "Fragment Sections",
+            event_label: `${sectionType}_${sectionId}`,
+        });
+    }
+    catch {
+        // Silently fail - don't break tracking if GA4 fails
+    }
+}
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
-export function fireImpressionWhenVisible(el, pixelUrl) {
+export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionType, sectionId) {
     if (typeof window === "undefined")
         return; // SSR guard
     if (!el || !pixelUrl)
@@ -64,6 +91,10 @@ export function fireImpressionWhenVisible(el, pixelUrl) {
             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("section_view", measurementId, sectionType, sectionId);
+        }
     };
     // Fallback if IntersectionObserver is missing
     const fallback = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.1.9",
+  "version": "2.2.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.1.8** - Enhanced countdown timer styling with customizable color tokens
+**v2.2.0** - Google Analytics 4 (GA4) integration with automatic section tracking
 
 > See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history
 
@@ -71,6 +71,15 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - 🌐 **Cross-Browser**: Works across all modern browsers with appropriate fallbacks
 - 🔄 **Graceful Degradation**: Tracking fails silently without affecting user experience
 
+### Google Analytics 4 (GA4) Integration (v2.2.0+)
+
+- 📊 **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
+
 ---
 
 ## 📦 Installation