Choose a version:

useAnalytics

A hook that provides access to the analytics provider context. Must be a descendent of Analytics.Provider.

Anchor to returnsReturns

Anchor to canTrack canTrack () => boolean: 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().
Anchor to cart cart UserCart |: The current cart state. You can overwrite the type by passing a generic
Anchor to customData customData Record<string, unknown>: The custom data passed in from the AnalyticsProvider.
Anchor to prevCart prevCart UserCart |: The previous cart state. You can overwrite the type by passing a generic
Anchor to publish publish: A function to publish an analytics event.
Anchor to register register (key: string) => { ready: () => void; }: 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.
Anchor to shop shop Promise< | null> | | null: The shop configuration required to publish events to Shopify.
Anchor to subscribe subscribe: A function to subscribe to analytics events.

DefaultCart

Promise<CartReturn | null> | CartReturn | null

CartReturn

Cart & {
  errors?: StorefrontApiErrors;
}

Cart

StorefrontApiErrors

JsonGraphQLError[] | undefined

JsonGraphQLError

AnalyticsContextPublishForDoc

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

PublishPageView

event
```
"page_viewed"
```
payload
```
PageViewPayload
```

void

void

PageViewPayload

UrlPayload & BasePayload

UrlPayload

url
The url location of when this event is collected.
```
string
```

BasePayload

customData
The custom data passed in from the `AnalyticsProvider`.
```
Record<string, unknown>
```
shop
The shop data passed in from the `AnalyticsProvider`.
```
ShopAnalytics | null
```

ShopAnalytics

acceptedLanguage
The language code that is being displayed to user.
```
LanguageCode
```
currency
The currency code that is being displayed to user.
```
CurrencyCode
```
hydrogenSubchannelId
The Hydrogen subchannel ID generated by Oxygen in the environment variable.
```
string | '0'
```
shopId
The shop ID.
```
string
```

PublishProductView

event
```
"product_viewed"
```
payload
```
ProductViewPayload
```

void

void

ProductViewPayload

ProductsPayload & UrlPayload & BasePayload

ProductsPayload

products
The products associated with this event.
```
Array<ProductPayload & OtherData>
```

ProductPayload

id
The product id.
```
Product
```
price
The displaying variant price.
```
ProductVariant
```
productType
The product type.
```
Product
```
quantity
The quantity of product.
```
number
```
sku
The product sku.
```
ProductVariant
```
title
The product title.
```
Product
```
variantId
The displaying variant id.
```
ProductVariant
```
variantTitle
The displaying variant title.
```
ProductVariant
```
vendor
The product vendor.
```
Product
```

OtherData

PublishCollectionView

event
```
"collection_viewed"
```
payload
```
CollectionViewPayload
```

void

void

CollectionViewPayload

CollectionPayload & UrlPayload & BasePayload

CollectionPayload

collection
```
CollectionPayloadDetails
```

CollectionPayloadDetails

handle
The collection handle.
```
string
```
id
The collection id.
```
string
```

PublishCartView

event
```
"cart_viewed"
```
payload
```
CartViewPayload
```

void

void

CartViewPayload

CartPayload & UrlPayload & BasePayload

CartPayload

cart
The current cart state.
```
CartReturn | null
```
prevCart
The previous cart state.
```
CartReturn | null
```

PublishSearchView

event
```
"search_viewed"
```
payload
```
SearchViewPayload
```

void

void

SearchViewPayload

SearchPayload & UrlPayload & BasePayload

SearchPayload

searchResults
The search results
```
any
```
searchTerm
The search term used for the search results page
```
string
```

PublishCartUpdated

event
```
"cart_updated"
```
payload
```
CartUpdatePayload
```

void

void

CartUpdatePayload

CartPayload & BasePayload & OtherData

PublishProductAddedToCart

event
```
"product_added_to_cart"
```
payload
```
CartLineUpdatePayload
```

void

void

CartLineUpdatePayload

CartLinePayload & CartPayload & BasePayload & OtherData

CartLinePayload

currentLine
The current state of the cart line that got updated.
```
CartLine | ComponentizableCartLine
```
prevLine
The previous state of the cart line that got updated.
```
CartLine | ComponentizableCartLine
```

PublishProductRemovedFromCart

event
```
"product_removed_from_cart"
```
payload
```
CartLineUpdatePayload
```

void

void

PublishCustomEvent

event
```
`custom_${string}`
```
payload
```
OtherData
```

void

void

AnalyticsContextSubscribeForDoc

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

SubscribePageView

event
```
"page_viewed"
```
callback
```
(payload: PageViewPayload) => void
```

void

void

SubscribeProductView

event
```
"product_viewed"
```
callback
```
(payload: ProductViewPayload) => void
```

void

void

SubscribeCollectionView

event
```
"collection_viewed"
```

callback

(payload: CollectionViewPayload) => void

void

void

SubscribeCartView

event
```
"cart_viewed"
```
callback
```
(payload: CartViewPayload) => void
```

void

void

SubscribeSearchView

event
```
"search_viewed"
```
callback
```
(payload: SearchViewPayload) => void
```

void

void

SubscribeCartUpdated

event
```
"cart_updated"
```
callback
```
(payload: CartUpdatePayload) => void
```

void

void

SubscribeProductAddedToCart

event
```
"product_added_to_cart"
```

callback

(payload: CartLineUpdatePayload) => void

void

void

SubscribeProductRemovedFromCart

event
```
"product_removed_from_cart"
```

callback

(payload: CartLineUpdatePayload) => void

void

void

SubscribeCustomEvent

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

void

void

Examples

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;

}

Examples

example

Description

This is the default example

JavaScript

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;
}

TypeScript

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;
}

Description

Registers a unique key with the analytics provider component, enabling custom analytics integrations to wait for a callback before sending event data.

JavaScript

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;
}

Was this page helpful?