Analytics

The AnalyticsService class (accessed via client.analytics) records first-party storefront analytics — page views and session starts. These power the merchant’s Store Analytics: traffic and audience, the conversion funnel, top products, and revenue-by-source. You send only the lightweight signals a browser has; the device, browser, operating system, and approximate location (country/region) are derived automatically from the request. The endpoint is publishable-key accessible, so you call it directly from the browser. It returns immediately and is processed in the background — sending an event never blocks the page.

Methods

`collectAnalyticsEvent`

Record one analytics event. Fire session_start for the first event of a new browsing session, then page_view on each route change.

// Fire once at the beginning of a browsing session (first page load).
await client.analytics.collectAnalyticsEvent({
  requestBody: {
    event_type: 'session_start',
    visitor_id: 'v_8f2a1c',                 // stable per-visitor id (localStorage)
    session_id: 'browser-session-id',       // per-session id (same as anonymous cart)
    path: '/',
    referrer: document.referrer,
    utm_source: 'google',
    utm_medium: 'organic'
  }
});

// Fire on each subsequent route change.
await client.analytics.collectAnalyticsEvent({
  requestBody: {
    event_type: 'page_view',
    visitor_id: 'v_8f2a1c',
    session_id: 'browser-session-id',
    path: '/products/wireless-headphones',
    customer_id: 'customer-uuid'            // include once the shopper signs in
  }
});

// Fire on page hide to capture time-on-page + exit pages. Use sendBeacon from a
// visibilitychange/pagehide handler so it survives the unload.
await client.analytics.collectAnalyticsEvent({
  requestBody: {
    event_type: 'page_close',
    visitor_id: 'v_8f2a1c',
    session_id: 'browser-session-id',
    path: '/products/wireless-headphones',
    duration_ms: 45000                       // ms spent on the page
  }
});

// What the shopper searched for, and how many results came back. Send 0 when the
// search found nothing — that is the case worth knowing about.
await client.analytics.collectAnalyticsEvent({
  requestBody: {
    event_type: 'search',
    visitor_id: 'v_8f2a1c',
    session_id: 'browser-session-id',
    search_query: 'winter jacket',
    search_result_count: 0
  }
});

// Which result the shopper clicked, and where it sat in the list. This is what makes
// merchandising measurable — without it a rule can only be judged by whether searches
// matching it happened to convert.
await client.analytics.collectAnalyticsEvent({
  requestBody: {
    event_type: 'search_result_click',
    visitor_id: 'v_8f2a1c',
    session_id: 'browser-session-id',
    search_query: 'winter jacket',
    search_result_product_id: '02525ff5-0916-4f00-857c-c2c6237e671b',
    search_result_position: 1
  }
});

Response

{
  "recorded": true
}

Every event type returns the same acknowledgement with a 202. The collector is a fire-and-forget beacon: it never returns data to read, and a failed write is never surfaced to the shopper. Parameters:

Parameter	Type	Description
`requestBody.event_type`	`string`	`session_start` (first event of a session), `page_view` (each route change), `page_close` (on page hide, with `duration_ms`, to capture time-on-page and exit pages — send via `navigator.sendBeacon`), `search` (what the shopper searched for), or `search_result_click` (which result they clicked).
`requestBody.search_query`	`string`	The shopper’s search term. Required with `search`, ignored otherwise. Casing and extra spacing are normalised before storage, so they do not fragment the reporting. May also be sent as `q`.
`requestBody.search_result_count`	`number`	How many results the search returned. Send `0` when it found nothing — that marks a search the catalogue could not answer.
`requestBody.search_result_product_id`	`string`	The product the shopper clicked. Required with `search_result_click` — a click with no product cannot be attributed to anything.
`requestBody.search_result_position`	`number`	Its 1-based position in the results as shown. Optional, but worth sending: it distinguishes a product clicked because it was featured from one that would have been found anyway.
`requestBody.duration_ms`	`number`	Time on the page in milliseconds; send with `page_close` to power average time-on-page and session-duration.
`requestBody.visitor_id`	`string`	A stable per-visitor identifier you persist in the browser (e.g. localStorage). Lets returning visitors be recognised.
`requestBody.session_id`	`string`	The browsing-session identifier — the same one you use for an anonymous cart. May also be sent as the `x-session-id` header.
`requestBody.path`	`string`	The page path. Only the pathname is stored; any query string is discarded.
`requestBody.referrer`	`string`	The document referrer, when present.
`requestBody.utm_source` `utm_medium` `utm_campaign` `utm_term` `utm_content`	`string`	UTM campaign parameters from the landing URL, when present. These drive revenue-by-source reporting.
`requestBody.customer_id`	`string`	The signed-in shopper, when known.

Persist visitor_id across sessions (e.g. in localStorage) and keep one session_id per browsing session. Send session_start once per session and a page_view on every route change — that’s all that’s needed for the full traffic, funnel, and revenue picture.

What you don’t send

Device type, browser, operating system, and country/region are detected from the request automatically — there is no client-side tracking script to add and no fingerprinting. Only the pathname is stored (query strings are dropped), keeping the capture privacy-light. A search or search_result_click event is stored without a customer, even when one is signed in and customer_id is sent. The reporting question is how a search term and its results perform, which the term, the product and the counts answer on their own.

Attributing revenue to a source

To see which traffic sources actually drive revenue (not just visits), pass the session’s first-touch attribution when you create the order — see Orders. The order’s attribution (session_id + the UTM parameters) lets Store Analytics join revenue back to the campaign that brought the shopper in.

What the merchant sees in Store Analytics

These events are the raw material behind the merchant’s Store Analytics dashboards in Galactic Core Admin. Nothing sent here is shown to shoppers; it is aggregated into daily rollups the merchant reads:

Overview & Traffic — session_start + page_view produce sessions, visitors (new vs returning, via visitor_id), pageviews, pages/session, and bounce rate. The device / browser / OS and country / region / city derived from each request become the Devices, Countries, and Cities breakdowns. page_close duration_ms powers average time-on-page.
Traffic sources & Revenue-by-source — the utm_* on session_start become the Traffic sources breakdown; joined with orders that carry the matching session_id in their attribution, they become Revenue by source (which campaigns actually convert).
Conversion funnel — the funnel stages (Viewed → Added to cart → Reached checkout → Purchased) are stitched by session_id across surfaces: product view / add_to_cart come from the Events API, “reached checkout” from a stock reservation, and “purchased” from a paid order whose attribution.session_id matches. Use one stable session_id for a shopper’s whole journey or the funnel can’t connect the stages.
Landing / exit pages — from the path on each page_view.
Content funnel — post_view / lookbook_view and content_click (with content_id + content_product_id) feed the Content tab’s views → clicks → orders → revenue per post/lookbook, closed by orders carrying attribution.content_id.

Because these are the only inputs to those dashboards, the completeness of what you send maps directly to what the merchant can see — e.g. omit utm_* and there’s no revenue-by-source; reuse one session_id per journey and the funnel lights up. The rollups recompute continuously, so recent activity shows up within minutes.

Response Codes

Code	Meaning
`202`	The event was accepted (`{ recorded: true }`). Beacons are fire-and-forget.
`400`	Missing `event_type`, `visitor_id`, or `session_id`.
`401`	Invalid or missing API key.
`429`	Rate limit exceeded.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Methods

`collectAnalyticsEvent`

What you don’t send

Attributing revenue to a source

What the merchant sees in Store Analytics

Response Codes

​Methods

​collectAnalyticsEvent

​What you don’t send

​Attributing revenue to a source

​What the merchant sees in Store Analytics

​Response Codes

Methods

`collectAnalyticsEvent`

What you don’t send

Attributing revenue to a source

What the merchant sees in Store Analytics

Response Codes