Events fired by @pixelrelay/hydrogen and where they go. Each event can leave your storefront two ways: from PixelRelay's servers, and from a browser tag. The tables show both.

Storefront events

Sent from PixelRelay's servers

A dash means nothing is sent for that platform.

Platform	`page_viewed`	`product_viewed`	`cart_viewed`	`collection_viewed`	`search_submitted`	`product_added_to_cart`	`product_removed_from_cart`
GA4	`page_view` ¹	`view_item`	`view_cart`	`view_item_list`	`search`	`add_to_cart`	`remove_from_cart`
Meta	`PageView` ²	`ViewContent`	`ViewContent`	–	`Search`	`AddToCart`	–
TikTok	–	`ViewContent`	`ViewContent`	–	`Search`	`AddToCart`	–
Pinterest	`page_visit` ²	`view_content`	–	`view_category`	`search`	`add_to_cart`	–
Snapchat	`PAGE_VIEW` ²	`VIEW_CONTENT`	`VIEW_CONTENT`	–	`SEARCH`	`ADD_CART`	–
Reddit	–	`ViewContent`	–	–	`Search`	`AddToCart`	–
Microsoft Ads	–	`view_item`	–	–	`search`	`add_to_cart`	–
Klaviyo	–	`Viewed Product`	`Viewed Cart`	–	–	`Added to Cart`	–
Segment	`page_viewed` ²	`Product Viewed`	`Cart Viewed`	`collection_viewed`	`Products Searched`	`Product Added`	`product_removed_from_cart`
Google Ads ³	`page_view`	`view_item`	–	–	`search`	`add_to_cart`	–

LinkedIn only receives purchases.

¹ GA4's own browser tag sends page views. PixelRelay's server copy is only sent when that tag is blocked or failed to configure, and only if Track page views server-side is on.

² Only sent if Track page views server-side is on (Settings → Relay, Pro or higher, off by default).

³ Google Ads browse uploads are off by default (Settings → Google Ads → Browse event uploads). The browser tag sends these events instead.

Segment names that aren't Segment spec names are the raw PixelRelay event name.

Sent from the browser tag

Platform	Events	Notes
Meta	`PageView`, `ViewContent` (product and cart), `Search`, `AddToCart`	Shares an event ID with the server copy
TikTok	`PageView`, `ViewContent` (product and cart), `Search`, `AddToCart`	Shares an event ID with the server copy
GA4	`page_view`	Page views only. The other GA4 events come from the server
Klaviyo	`Active on Site`, `Viewed Product`, `Added to Cart`	Onsite tracking
Google Ads	`page_view`, `view_item`, `add_to_cart`, `search`	Only for events that have a conversion action mapped
Reddit	`PageVisit`	Fires when the tag loads
Snapchat, Microsoft Ads	–	The tag loads to set cookies only

Browser tags need the CSP change from the quickstart.

How each event fires

page_viewed: every client-side route change. Source is Hydrogen's PAGE_VIEWED bus event, or a useLocation fallback when the bus is blocked.
product_viewed: when you render <Analytics.ProductView>.
product_added_to_cart: use useTrackAddToCart() on your button's onClick. It works with ad blockers. Hydrogen's PRODUCT_ADD_TO_CART bus event is the fallback and only fires while the bus is alive.
product_removed_from_cart: from the analytics bus when a line is reduced or removed.
cart_viewed: needs <Analytics.CartView>.
collection_viewed: needs <Analytics.CollectionView>.
search_submitted: needs <Analytics.SearchView>.

Checkout and purchase

Hydrogen sends no storefront conversion for these. Call useTrackCheckout(cart) before following the checkout URL so attribution lands on the cart. Shopify's checkout and the order webhook take over from there.

Event	Source
`checkout_started`	PixelRelay's Web Pixel in Shopify checkout
`payment_info_submitted`	Web Pixel
`checkout_completed` / `order_placed`	Order webhook. This is the source of truth for purchases

PixelRelay won't send the same order twice, but it can't merge with a copy sent by another tool. See Conversions counted twice.

Browser dispatch outcomes

Meta, TikTok, Klaviyo, GA4 and Google Ads have browser adapters. Each reports what its own attempt did.

Outcome	Meaning
`sent`	Handed to the vendor tag
`blocked`	The vendor tag couldn't be reached. Usually an ad blocker or your CSP
`config_failed`	The tag loaded but the destination was never configured
`consent_denied`	The shopper's consent choice stopped that platform
`unsupported`	That platform doesn't accept this event

This records the attempt, not whether the vendor accepted it, and it never stops the server copy. In the merchant event log, only Google Ads shows this today. See Check delivery in the event log.

Custom events

import { useTrackEvent } from '@pixelrelay/hydrogen';

const track = useTrackEvent();
track('lead', { email: user.email });

Custom events go to GA4 and Segment only. GA4 gets the event name and event ID, without your properties. Segment gets your properties as event properties. An email is never sent raw. It's only used to make Segment's hashed userId.

For purchase-class events you must pass payload.orderId. Purchases without one are dropped, because the order webhook is the source of truth for purchases.

Attribution signals

Sent with every event when available.

Field	Source
`fbp`, `fbc`	Meta cookies, or `fbclid` in the URL
`ttclid`, `ttp`	TikTok
`gclid`, `gbraid`, `wbraid`	Google Ads, including the iOS click IDs
`msclkid`	Microsoft Ads
`scid`, `sccid`	Snapchat cookie and `ScCid` click ID
`epik`	Pinterest
`rdt_cid`	Reddit
`li_fat_id`	LinkedIn
`gaClientId`, `gaSessionId`	GA4 `_ga` and `_ga_<container>` cookies
`durableId`	`_relay_uid`, a first-party cookie kept for 365 days
`consentState`	Shopify's Customer Privacy API
`eventSourceUrl`	Current page URL

Cookie-based signals depend on the vendor tags loading, which needs the CSP step from the quickstart. Signals read from URL parameters don't. When a visitor declines consent, the matching signals are removed. See Privacy & consent.

`<PixelRelayProvider>` props

Prop	Required	Description
`shop`	Yes	`store.myshopify.com`
`proxyUrl`	No	First-party POST URL. Defaults to `/api/pixel` for 1.x compatibility. New installs pass `/api/relay`
`autoConfig`	No	Fetch connected pixel IDs and Ads labels through the proxy. Defaults to `true`
`customer`	No	Signed-in shopper, for Klaviyo identify and reset. Pass `null` on logout
`scripts`	No	Override the fetched pixel IDs
`storefrontApiUrl`	No	Storefront GraphQL endpoint. Needed to write cart attributes
`storefrontToken`	No	Public Storefront token. Needed to write cart attributes
`cartId`	No	Cart GID, if you write attributes from the provider instead of `<PixelRelayCartAttributes>`
`debug`	No	Verbose console logging. Also switchable with `localStorage.setItem('pixelrelay:debug', '1')`

Need help? Email [email protected]