useAnalytics

A hook that provides access to the analytics provider context. Must be a descendent of [`Analytics.Provider`](/docs/api/hydrogen/2024-10/components/Analytics-provider).

import {useAnalytics} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function CustomAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('CustomAnalytics'); // unique string identifier

  useEffect(() => {
    // Triggers on every page navigation
    subscribe('page_viewed', (data) => {
      console.log('CustomAnalytics - Page viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.ProductView>`
    subscribe('product_viewed', (data) => {
      console.log('CustomAnalytics - Product viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CollectionView>`
    subscribe('collection_viewed', (data) => {
      console.log('CustomAnalytics - Collection viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CartView>`
    subscribe('cart_viewed', (data) => {
      console.log('CustomAnalytics - Cart viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.SearchView>`
    subscribe('search_viewed', (data) => {
      console.log('CustomAnalytics - Search viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CustomView type="custom_promotion_viewed">`
    subscribe('custom_promotion_viewed', (data) => {
      console.log('CustomAnalytics - Promotion viewed:', data);
    });

    // Triggers when the cart is updated
    subscribe('cart_updated', (data) => {
      console.log('CustomAnalytics - Cart updated:', data);
    });

    // Triggers when an existing cart line increases in quantity or a new cart line is added
    subscribe('product_added_to_cart', (data) => {
      console.log('CustomAnalytics - Product added to cart:', data);
    });

    // Triggers when an existing cart line decreases in quantity or a cart line is removed
    subscribe('product_removed_from_cart', (data) => {
      console.log('CustomAnalytics - Product removed from cart:', data);
    });

    // Register the CustomAnalytics component as ready
    ready();
  }, []);

  return null;
}

import {
  type PageViewPayload,
  type ProductViewPayload,
  type CollectionViewPayload,
  type CartViewPayload,
  type CartUpdatePayload,
  type CartLineUpdatePayload,
  type SearchViewPayload,
  useAnalytics,
} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function CustomAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('CustomAnalytics'); // unique string identifier

  useEffect(() => {
    // Triggers on every page navigation
    subscribe('page_viewed', (data: PageViewPayload) => {
      console.log('CustomAnalytics - Page viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.ProductView>`
    subscribe('product_viewed', (data: ProductViewPayload) => {
      console.log('CustomAnalytics - Product viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CollectionView>`
    subscribe('collection_viewed', (data: CollectionViewPayload) => {
      console.log('CustomAnalytics - Collection viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CartView>`
    subscribe('cart_viewed', (data: CartViewPayload) => {
      console.log('CustomAnalytics - Cart viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.SearchView>`
    subscribe('search_viewed', (data: SearchViewPayload) => {
      console.log('CustomAnalytics - Search viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CustomView type="custom_promotion_viewed">`
    subscribe('custom_promotion_viewed', (data: unknown) => {
      console.log('CustomAnalytics - Promotion viewed:', data);
    });

    // Triggers when the cart is updated
    subscribe('cart_updated', (data: CartUpdatePayload) => {
      console.log('CustomAnalytics - Cart updated:', data);
    });

    // Triggers when an existing cart line increases in quantity or a new cart line is added
    subscribe('product_added_to_cart', (data: CartLineUpdatePayload) => {
      console.log('CustomAnalytics - Product added to cart:', data);
    });

    // Triggers when an existing cart line decreases in quantity or a cart line is removed
    subscribe('product_removed_from_cart', (data: CartLineUpdatePayload) => {
      console.log('CustomAnalytics - Product removed from cart:', data);
    });

    // Register the CustomAnalytics component as ready
    ready();
  }, []);

  return null;
}

Returns

AnalyticsContextValueForDoc

canTrack

A function to tell you the current state of if the user can be tracked by analytics. Defaults to Customer Privacy API's `window.Shopify.customerPrivacy.analyticsProcessingAllowed()`.

cart

The current cart state. You can overwrite the type by passing a generic

customData

The custom data passed in from the `AnalyticsProvider`.

prevCart

The previous cart state. You can overwrite the type by passing a generic

publish

A function to publish an analytics event.

register

A function to register with the analytics provider. It holds the first browser load events until all registered key has executed the supplied `ready` function. [See example register usage](/docs/api/hydrogen/2024-10/hooks/useanalytics#example-useanalytics.register).

shop

The shop configuration required to publish events to Shopify.

subscribe

A function to subscribe to analytics events.

DefaultCart

Promise<CartReturn | null> | CartReturn | null

CartReturn

Cart & { errors?: StorefrontApiErrors; }

Cart

Cart

StorefrontApiErrors

JsonGraphQLError[] | undefined

JsonGraphQLError

ReturnType<GraphQLError['toJSON']>

AnalyticsContextPublishForDoc

PublishPageView | PublishProductView | PublishCollectionView | PublishCartView | PublishSearchView | PublishCartUpdated | PublishProductAddedToCart | PublishProductRemovedFromCart | PublishCustomEvent

PublishPageView

Returns: void

Params:

event: "page_viewed"

payload: PageViewPayload

type PublishPageView = (event: 'page_viewed', payload: PageViewPayload) => void;

PageViewPayload

UrlPayload & BasePayload

UrlPayload

url

The url location of when this event is collected.

BasePayload

customData

The custom data passed in from the `AnalyticsProvider`.

shop

The shop data passed in from the `AnalyticsProvider`.

ShopAnalytics

acceptedLanguage

The language code that is being displayed to user.

currency

The currency code that is being displayed to user.

hydrogenSubchannelId

The Hydrogen subchannel ID generated by Oxygen in the environment variable.

shopId

The shop ID.

PublishProductView

Returns: void

Params:

event: "product_viewed"

payload: ProductViewPayload

type PublishProductView = ( event: 'product_viewed', payload: ProductViewPayload, ) => void;

ProductViewPayload

ProductsPayload & UrlPayload & BasePayload

ProductsPayload

products

The products associated with this event.

ProductPayload

id

The product id.

price

The displaying variant price.

productType

The product type.

quantity

The quantity of product.

sku

The product sku.

title

The product title.

variantId

The displaying variant id.

variantTitle

The displaying variant title.

vendor

The product vendor.

OtherData

OtherData

PublishCollectionView

Returns: void

Params:

event: "collection_viewed"

payload: CollectionViewPayload

type PublishCollectionView = ( event: 'collection_viewed', payload: CollectionViewPayload, ) => void;

CollectionViewPayload

CollectionPayload & UrlPayload & BasePayload

CollectionPayload

collection

CollectionPayloadDetails

handle

The collection handle.

id

The collection id.

PublishCartView

Returns: void

Params:

event: "cart_viewed"

payload: CartViewPayload

type PublishCartView = (event: 'cart_viewed', payload: CartViewPayload) => void;

CartViewPayload

CartPayload & UrlPayload & BasePayload

CartPayload

cart

The current cart state.

prevCart

The previous cart state.

PublishSearchView

Returns: void

Params:

event: "search_viewed"

payload: SearchViewPayload

type PublishSearchView = ( event: 'search_viewed', payload: SearchViewPayload, ) => void;

SearchViewPayload

SearchPayload & UrlPayload & BasePayload

SearchPayload

searchResults

The search results

searchTerm

The search term used for the search results page

PublishCartUpdated

Returns: void

Params:

event: "cart_updated"

payload: CartUpdatePayload

type PublishCartUpdated = ( event: 'cart_updated', payload: CartUpdatePayload, ) => void;

CartUpdatePayload

CartPayload & BasePayload & OtherData

PublishProductAddedToCart

Returns: void

Params:

event: "product_added_to_cart"

payload: CartLineUpdatePayload

type PublishProductAddedToCart = ( event: 'product_added_to_cart', payload: CartLineUpdatePayload, ) => void;

CartLineUpdatePayload

CartLinePayload & CartPayload & BasePayload & OtherData

CartLinePayload

currentLine

The current state of the cart line that got updated.

prevLine

The previous state of the cart line that got updated.

PublishProductRemovedFromCart

Returns: void

Params:

event: "product_removed_from_cart"

payload: CartLineUpdatePayload

type PublishProductRemovedFromCart = ( event: 'product_removed_from_cart', payload: CartLineUpdatePayload, ) => void;

PublishCustomEvent

Returns: void

Params:

event: `custom_${string}`

payload: OtherData

type PublishCustomEvent = ( event: `custom_${string}`, payload: OtherData, ) => void;

AnalyticsContextSubscribeForDoc

SubscribePageView | SubscribeProductView | SubscribeCollectionView | SubscribeCartView | SubscribeSearchView | SubscribeCartUpdated | SubscribeProductAddedToCart | SubscribeProductRemovedFromCart | SubscribeCustomEvent

SubscribePageView

Returns: void

Params:

event: "page_viewed"

callback: (payload: PageViewPayload) => void

type SubscribePageView = ( event: 'page_viewed', callback: (payload: PageViewPayload) => void, ) => void;

SubscribeProductView

Returns: void

Params:

event: "product_viewed"

callback: (payload: ProductViewPayload) => void

type SubscribeProductView = ( event: 'product_viewed', callback: (payload: ProductViewPayload) => void, ) => void;

SubscribeCollectionView

Returns: void

Params:

event: "collection_viewed"

callback: (payload: CollectionViewPayload) => void

type SubscribeCollectionView = ( event: 'collection_viewed', callback: (payload: CollectionViewPayload) => void, ) => void;

SubscribeCartView

Returns: void

Params:

event: "cart_viewed"

callback: (payload: CartViewPayload) => void

type SubscribeCartView = ( event: 'cart_viewed', callback: (payload: CartViewPayload) => void, ) => void;

SubscribeSearchView

Returns: void

Params:

event: "search_viewed"

callback: (payload: SearchViewPayload) => void

type SubscribeSearchView = ( event: 'search_viewed', callback: (payload: SearchViewPayload) => void, ) => void;

SubscribeCartUpdated

Returns: void

Params:

event: "cart_updated"

callback: (payload: CartUpdatePayload) => void

type SubscribeCartUpdated = ( event: 'cart_updated', callback: (payload: CartUpdatePayload) => void, ) => void;

SubscribeProductAddedToCart

Returns: void

Params:

event: "product_added_to_cart"

callback: (payload: CartLineUpdatePayload) => void

type SubscribeProductAddedToCart = ( event: 'product_added_to_cart', callback: (payload: CartLineUpdatePayload) => void, ) => void;

SubscribeProductRemovedFromCart

Returns: void

Params:

event: "product_removed_from_cart"

callback: (payload: CartLineUpdatePayload) => void

type SubscribeProductRemovedFromCart = ( event: 'product_removed_from_cart', callback: (payload: CartLineUpdatePayload) => void, ) => void;

SubscribeCustomEvent

Returns: void

Params:

event: `custom_${string}`

callback: (payload: OtherData) => void

type SubscribeCustomEvent = ( event: `custom_${string}`, callback: (payload: OtherData) => void, ) => void;

Examples

A hook that provides access to the analytics provider context. Must be a descendent of [`Analytics.Provider`](/docs/api/hydrogen/2024-10/components/Analytics-provider).

useAnalytics.register

import {
  type PageViewPayload,
  useAnalytics,
  useLoadScript,
} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function MyAnalytics() {
  const {subscribe, register} = useAnalytics();

  // Load the 3p analytics script
  const scriptStatus = useLoadScript(
    'https://example.com/some-3p-analytics-script.js',
  );

  // unique string identifier
  const {ready} = register('MyAnalytics');

  useEffect(() => {
    // Make sure the 3p script is loaded
    if (scriptStatus !== 'done') return;

    // Initialize the 3p analytics script

    // Subscribe to analytics events
    subscribe('page_viewed', (data: PageViewPayload) => {
      // report to 3p analytics
    });

    // Register the MyAnalytics component as ready
    ready();
  }, []);

  return null;
}