@shopify/shop-minis-react 0.11.1 → 0.12.0

package/src/components/commerce/product-card.tsx

@@ -6,6 +6,7 @@ import {type Product, type ProductVariant} from '@shopify/shop-minis-platform'
 import {useShopNavigation} from '../../hooks/navigation/useShopNavigation'
 import {useSavedProductsActions} from '../../hooks/user/useSavedProductsActions'
 import {ProductReviewStars} from '../../internal/components/product-review-stars'
+import {useProductImpression} from '../../internal/useProductImpression'
 import {cn} from '../../lib/utils'
 import {formatMoney} from '../../utils/formatMoney'
 import {Image} from '../atoms/image'
@@ -326,6 +327,8 @@ export interface ProductCardProps {
   favoriteButtonDisabled?: boolean
   /** Whether review stars are disabled */
   reviewsDisabled?: boolean
+  /** Whether to disable impression tracking */
+  impressionTrackingDisabled?: boolean
 }
 
 function ProductCard({
@@ -340,9 +343,14 @@ function ProductCard({
   children,
   favoriteButtonDisabled = false,
   reviewsDisabled = false,
+  impressionTrackingDisabled = false,
 }: ProductCardProps) {
   const {navigateToProduct} = useShopNavigation()
   const {saveProduct, unsaveProduct} = useSavedProductsActions()
+  const {ref: impressionRef} = useProductImpression({
+    productId: product.id,
+    skip: impressionTrackingDisabled,
+  })
 
   // Local state for optimistic UI updates
   const [isFavoritedLocal, setIsFavoritedLocal] = useState(product.isFavorited)
@@ -433,23 +441,25 @@ function ProductCard({
 
   return (
     <ProductCardContext.Provider value={contextValue}>
-      {children ?? (
-        <ProductCardContainer>
-          <ProductCardImageContainer>
-            <ProductCardImage />
-            {variant === 'priceOverlay' && <ProductCardPriceOverlayBadge />}
-            <ProductCardBadge />
-            <ProductCardFavoriteButton />
-          </ProductCardImageContainer>
-          {variant === 'default' && (
-            <ProductCardInfo>
-              <ProductCardTitle />
-              <ProductCardReviewStars />
-              <ProductCardPrice />
-            </ProductCardInfo>
-          )}
-        </ProductCardContainer>
-      )}
+      <div ref={impressionRef}>
+        {children ?? (
+          <ProductCardContainer>
+            <ProductCardImageContainer>
+              <ProductCardImage />
+              {variant === 'priceOverlay' && <ProductCardPriceOverlayBadge />}
+              <ProductCardBadge />
+              <ProductCardFavoriteButton />
+            </ProductCardImageContainer>
+            {variant === 'default' && (
+              <ProductCardInfo>
+                <ProductCardTitle />
+                <ProductCardReviewStars />
+                <ProductCardPrice />
+              </ProductCardInfo>
+            )}
+          </ProductCardContainer>
+        )}
+      </div>
     </ProductCardContext.Provider>
   )
 }

package/src/components/commerce/product-link.tsx

@@ -7,6 +7,7 @@ import {Slot as SlotPrimitive} from 'radix-ui'
 import {useShopNavigation} from '../../hooks/navigation/useShopNavigation'
 import {useSavedProductsActions} from '../../hooks/user/useSavedProductsActions'
 import {ProductReviewStars} from '../../internal/components/product-review-stars'
+import {useProductImpression} from '../../internal/useProductImpression'
 import {cn} from '../../lib/utils'
 import {formatMoney} from '../../utils/formatMoney'
 import {Touchable} from '../atoms/touchable'
@@ -239,6 +240,8 @@ export interface ProductLinkDocProps {
   customAction?: React.ReactNode
   /** Callback when the custom action is clicked. Must be provided with `customAction`. */
   onCustomActionClick?: () => void
+  /** Whether to disable impression tracking */
+  impressionTrackingDisabled?: boolean
 }
 
 export type ProductLinkProps = {
@@ -246,6 +249,7 @@ export type ProductLinkProps = {
   hideFavoriteAction?: boolean
   onClick?: (product: Product) => void
   reviewsDisabled?: boolean
+  impressionTrackingDisabled?: boolean
 } & (
   | {
       customAction?: never
@@ -265,9 +269,14 @@ function ProductLink({
   customAction,
   onCustomActionClick,
   reviewsDisabled = false,
+  impressionTrackingDisabled = false,
 }: ProductLinkProps) {
   const {navigateToProduct} = useShopNavigation()
   const {saveProduct, unsaveProduct} = useSavedProductsActions()
+  const {ref: impressionRef} = useProductImpression({
+    productId: product.id,
+    skip: impressionTrackingDisabled,
+  })
 
   const {
     id,
@@ -346,58 +355,60 @@ function ProductLink({
   ])
 
   return (
-    <ProductLinkRoot
-      layout="horizontal"
-      discount={hasDiscount ? 'small' : 'none'}
-      onPress={handlePress}
-    >
-      <ProductLinkImage layout="horizontal">
-        {imageUrl ? (
-          <img
-            src={imageUrl}
-            alt={imageAltText}
-            className="h-full w-full object-cover"
-          />
-        ) : (
-          <div className="h-full w-full bg-muted flex items-center justify-center text-muted-foreground text-xs">
-            No Image
-          </div>
-        )}
-      </ProductLinkImage>
-
-      <ProductLinkInfo layout="horizontal">
-        <ProductLinkTitle>{title}</ProductLinkTitle>
-
-        {averageRating && !reviewsDisabled ? (
-          <ProductLinkRating>
-            <ProductReviewStars
-              averageRating={averageRating}
-              reviewCount={reviewCount}
+    <div ref={impressionRef}>
+      <ProductLinkRoot
+        layout="horizontal"
+        discount={hasDiscount ? 'small' : 'none'}
+        onPress={handlePress}
+      >
+        <ProductLinkImage layout="horizontal">
+          {imageUrl ? (
+            <img
+              src={imageUrl}
+              alt={imageAltText}
+              className="h-full w-full object-cover"
             />
-          </ProductLinkRating>
-        ) : null}
-
-        <ProductLinkPrice>
-          {hasDiscount ? (
-            <>
-              <ProductLinkDiscountPrice>{amount}</ProductLinkDiscountPrice>
-              <ProductLinkOriginalPrice>
-                {compareAtPriceAmount}
-              </ProductLinkOriginalPrice>
-            </>
           ) : (
-            <ProductLinkCurrentPrice>{amount}</ProductLinkCurrentPrice>
+            <div className="h-full w-full bg-muted flex items-center justify-center text-muted-foreground text-xs">
+              No Image
+            </div>
           )}
-        </ProductLinkPrice>
-      </ProductLinkInfo>
-
-      <ProductLinkActions
-        filled={isFavoritedLocal}
-        onPress={handleActionPress}
-        customAction={customAction}
-        hideFavoriteAction={hideFavoriteAction}
-      />
-    </ProductLinkRoot>
+        </ProductLinkImage>
+
+        <ProductLinkInfo layout="horizontal">
+          <ProductLinkTitle>{title}</ProductLinkTitle>
+
+          {averageRating && !reviewsDisabled ? (
+            <ProductLinkRating>
+              <ProductReviewStars
+                averageRating={averageRating}
+                reviewCount={reviewCount}
+              />
+            </ProductLinkRating>
+          ) : null}
+
+          <ProductLinkPrice>
+            {hasDiscount ? (
+              <>
+                <ProductLinkDiscountPrice>{amount}</ProductLinkDiscountPrice>
+                <ProductLinkOriginalPrice>
+                  {compareAtPriceAmount}
+                </ProductLinkOriginalPrice>
+              </>
+            ) : (
+              <ProductLinkCurrentPrice>{amount}</ProductLinkCurrentPrice>
+            )}
+          </ProductLinkPrice>
+        </ProductLinkInfo>
+
+        <ProductLinkActions
+          filled={isFavoritedLocal}
+          onPress={handleActionPress}
+          customAction={customAction}
+          hideFavoriteAction={hideFavoriteAction}
+        />
+      </ProductLinkRoot>
+    </div>
   )
 }
 

package/src/internal/useContentImpression.ts

@@ -0,0 +1,75 @@
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useHandleAction} from './useHandleAction'
+import {useShopActions} from './useShopActions'
+
+export interface UseContentImpressionParams {
+  /**
+   * The public ID of the content to report impressions for
+   */
+  publicId: string
+  /**
+   * Whether to skip reporting impressions
+   */
+  skip?: boolean
+}
+
+export interface UseContentImpressionReturns {
+  /**
+   * Ref to attach to the content element for visibility tracking.
+   * When the element becomes visible, an impression will be reported.
+   */
+  ref: {current: HTMLDivElement | null}
+}
+
+export function useContentImpression({
+  publicId,
+  skip = false,
+}: UseContentImpressionParams): UseContentImpressionReturns {
+  const {reportContentImpression} = useShopActions()
+  const handleAction = useHandleAction(reportContentImpression)
+  const ref = useRef<HTMLDivElement>(null)
+  const hasReportedRef = useRef(false)
+
+  const reportImpression = useCallback(() => {
+    if (hasReportedRef.current || skip || !publicId) {
+      return
+    }
+
+    hasReportedRef.current = true
+    handleAction({publicId, pageValue: window.location.pathname})
+  }, [handleAction, publicId, skip])
+
+  useEffect(() => {
+    hasReportedRef.current = false
+  }, [publicId])
+
+  useEffect(() => {
+    if (skip || !ref.current) {
+      return
+    }
+
+    const element = ref.current
+
+    const observer = new IntersectionObserver(
+      entries => {
+        const [entry] = entries
+        if (entry?.isIntersecting) {
+          reportImpression()
+          observer.disconnect()
+        }
+      },
+      {
+        threshold: 0.5,
+      }
+    )
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [reportImpression, skip])
+
+  return {ref}
+}

package/src/internal/useProductImpression.ts

@@ -0,0 +1,88 @@
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useHandleAction} from './useHandleAction'
+import {useShopActions} from './useShopActions'
+
+export interface UseProductImpressionParams {
+  /**
+   * The product GID string to report impressions for
+   */
+  productId: string
+  /**
+   * Whether to skip reporting impressions (e.g., when product data is loading)
+   */
+  skip?: boolean
+}
+
+export interface UseProductImpressionReturns {
+  /**
+   * Ref to attach to the product element for visibility tracking.
+   * When the element becomes visible, an impression will be reported.
+   */
+  ref: {current: HTMLDivElement | null}
+}
+
+/**
+ * Hook to report product impressions when a product becomes visible.
+ * Attach the returned ref to the product container element.
+ *
+ * @example
+ * ```tsx
+ * function ProductCard({ product }) {
+ *   const { ref } = useProductImpression({ productId: product.id });
+ *   return <div ref={ref}>...</div>;
+ * }
+ * ```
+ */
+export function useProductImpression({
+  productId,
+  skip = false,
+}: UseProductImpressionParams): UseProductImpressionReturns {
+  const {productRecommendationImpression} = useShopActions()
+  const handleAction = useHandleAction(productRecommendationImpression)
+  const ref = useRef<HTMLDivElement>(null)
+  const hasReportedRef = useRef(false)
+
+  const reportImpression = useCallback(() => {
+    if (hasReportedRef.current || skip || !productId) {
+      return
+    }
+
+    hasReportedRef.current = true
+    handleAction({productId})
+  }, [handleAction, productId, skip])
+
+  useEffect(() => {
+    // Reset reported state when productId changes
+    hasReportedRef.current = false
+  }, [productId])
+
+  useEffect(() => {
+    if (skip || !ref.current) {
+      return
+    }
+
+    const element = ref.current
+
+    const observer = new IntersectionObserver(
+      entries => {
+        const [entry] = entries
+        if (entry?.isIntersecting) {
+          reportImpression()
+          observer.disconnect()
+        }
+      },
+      {
+        threshold: 0.5, // Report when 50% of the element is visible
+      }
+    )
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [reportImpression, skip])
+
+  return {ref}
+}