Segment

Hemsy can forward browser-side try-on events to Segment as track calls. Use this when you want try-on behavior in the same pipelines as your storefront (GA4, Mixpanel, Klaviyo, Snowflake, and so on). This is separate from Hemsy Home in the dashboard, which shows aggregated KPIs (sessions, conversion, revenue, and so on). Segment receives individual events with properties; Hemsy Home computes rollups from Hemsy’s internal event store.

Where Segment forwarding applies

Segment forwarding works in both ways shoppers use Hemsy:

Experience	URL pattern	How shoppers arrive
Embedded experience	`https://hemsy.ai/embed/{subdomain}?embed=1&…`	Your storefront loads `hemsy-embed.js` and opens Hemsy in a modal iframe.
Hosted experience	`https://{subdomain}.hemsy.ai?…`	Shoppers open your store’s Hemsy subdomain directly (link, QR code, email, and so on).

Both surfaces run the same try-on app and send events through the same browser API (POST /api/events). Segment is not limited to embeds. Segment forwarding does not apply to:

The Hemsy dashboard (merchant admin UI).
Server-only events (for example attributed orders written at checkout webhooks). Those feed Hemsy Home, not the Segment forwarder.

Setup

In the Hemsy dashboard, open Integrations.
Under Segment, enter your Segment Endpoint URL (for most workspaces: https://api.segment.io).
Optionally enter your Write Key (required for standard Segment endpoints; leave blank only if your proxy authenticates requests another way).
Save. The card shows Connected when an endpoint is configured.

Hemsy sends POST requests to {endpoint}/v1/track with JSON bodies in Segment’s HTTP API shape.

Identity stitching (`anonymousId`)

To align Hemsy Segment events with your storefront identity graph, pass the same stable ID you use elsewhere (for example Segment’s anonymousId). Hemsy sends this value as Segment’s anonymousId on every forwarded track. If you do not pass one, Hemsy uses its own browser visitor ID (hemsy_visitor_id in localStorage), which will not match your site unless you bridge IDs yourself. There is no automatic cross-domain handoff from your storefront to {subdomain}.hemsy.ai. You must pass the ID explicitly using one of the methods below.

Embedded experience

Set data-hemsy-anonymous-id on the embed script. The embed loader appends it to the iframe URL as anonymous_id:

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-anonymous-id="visitor-42"
  defer
></script>

You can also set anonymousId on window.HemsyEmbedConfig (see Hemsy Embeds).

Hosted experience

Add the anonymous_id query parameter to any link to your Hemsy subdomain:

https://mystore.hemsy.ai?anonymous_id=visitor-42

Works alongside other parameters:

https://mystore.hemsy.ai?anonymous_id=visitor-42&flow=<flowId>
https://mystore.hemsy.ai?anonymous_id=visitor-42&closet=<payload>

Use the same ID you use on your storefront and in Segment. When a shopper lands without anonymous_id, only Hemsy’s generated visitor ID is used.

Checkout metadata

The same anonymous_id is attached to Shopify cart/checkout line-item metadata as attributes[anonymous_id] when the shopper completes checkout from either experience.

How forwarding works

The shopper uses the embedded or hosted try-on experience.
The browser records the event in Hemsy and POSTs to /api/events.
If Segment is configured, Hemsy forwards a track call with a human-readable name prefixed with Hemsy .

Forwarding runs only when:

The event has a Segment mapping (see Forwarded events).
Your store has a valid Segment endpoint saved in Integrations.
The request passes Hemsy’s store context checks (host / origin / referer match your store slug or an allowed Hemsy host such as hemsy.ai, {subdomain}.hemsy.ai, staging, or local dev).

Properties on every track call

In addition to event-specific fields below, each forwarded track includes:

Property	Type	Description
`productIds`	`string[]`	Shopify product IDs for items in the shopper’s look, when applicable.
`variantIds`	`string[]`	Shopify variant IDs for items in the look, when applicable.
`sessionId`	`string \| null`	Hemsy session ID for this tab visit (`sessionStorage`).
`storeSlug`	`string`	Your Hemsy store subdomain slug.

Segment also receives anonymousId and an ISO timestamp.

Forwarded events

Session and engagement

Segment event	When it fires	Event properties
Hemsy Session Started	Once per browser tab session when the try-on experience loads and analytics bootstraps.	—
Hemsy Session Engaged	Once per session, 10 seconds after load (shopper remained in the experience).	—

Try-on funnel

Segment event	When it fires	Event properties
Hemsy Try On Started	Shopper starts try-on generation (photo + at least one item).	`selectedItemCount`
Hemsy Try On Completed	Try-on succeeds and the result screen is shown.	`selectedItemCount`
Hemsy Try On Failed	Try-on fails or returns without a generated image.	`reason` — e.g. `no_product_images`, `generation_failed`

Look building

Segment event	When it fires	Event properties
Hemsy Added Item to Look	Shopper adds a product variant to their look.	`productTitle`
Hemsy User Photo Uploaded	Shopper uploads a photo from their device.	—
Hemsy Model Photo Selected	Shopper picks a photo from the model library.	`model_id`

Guided flows

When a merchant flow is active (data-hemsy-flow on embed launchers, or flow query param on the hosted experience):

Segment event	When it fires	Event properties
Hemsy Flow Step Completed	Shopper completes a flow step by adding an item and advancing.	`flow_name`, `flow_id`, `flow_step_name`
Hemsy Flow Step Skipped	Shopper skips a non-required step.	`flow_name`, `flow_id`, `flow_step_name`
Hemsy Flow Exited	Shopper leaves the guided flow.	`flow_name`, `flow_id`, `flow_step_name`

Browse, filter, and search

In free-browse mode (no active flow):

Segment event	When it fires	Event properties
Hemsy Filter Selected	Shopper selects a category in Filter & Sort.	`filter_name`, `filter_scope`
Hemsy Sort Selected	Shopper changes sort (not “Featured”).	`sort_name` — `price-low`, `price-high`, etc.
Hemsy Search Submitted	Shopper submits a catalog search (Enter).	`query`, `result_count`

Result screen

Segment event	When it fires	Event properties
Hemsy Try On Edited	Shopper edits the look from the result screen.	`action` — `edit`, `swap`, or `remove`
Hemsy Checkout Clicked	Shopper taps checkout (or cart handoff in embed `cart` mode).	`selectedItemCount`, `hasStorefrontToken`, `fromSharedLook`, `sharedLookShortId`
Hemsy Look Shared	Shopper shares the result.	See Hemsy Look Shared below.

Hemsy Look Shared

This event fires on two different paths depending on whether share links are enabled for your store (sharing_enabled in Hemsy, or always on staging/preview hosts).

`type`	When	Segment properties
`share_link`	Share links are enabled. Hemsy creates a persisted share URL, then surfaces it to the shopper.	`shortId`, `shareUrl`, `storeSlug`, `selectedItemCount`, `usedNativeShare`
`share_image`	Share links are disabled. Hemsy shares or downloads the try-on image only (no share URL).	`storeSlug`, `selectedItemCount`

`usedNativeShare` vs `shareUrl` (`type: share_link` only)

These answer different questions:

Property	What it tells you
`usedNativeShare`	How the link was surfaced — `true` if the browser native share sheet was used (`navigator.share` with the URL, common on mobile), `false` if Hemsy fell back to copying the link to the clipboard (typical on desktop when Web Share API is unavailable or fails).
`shareUrl`	What link was shared — the URL recipients can open (for example `https://yourstore.com/?share=FreyjHz4` when redirecting to the store embed, or your hosted `https://{subdomain}.hemsy.ai/?share=…` URL).

Hemsy always tries the native share sheet first when navigator.share is available and the share completes without cancellation. If that is not available or fails (other than the user dismissing the sheet), Hemsy copies shareUrl to the clipboard and sets usedNativeShare to false. Cancelling the native sheet does not fire Hemsy Look Shared. share_image does not include usedNativeShare or shareUrl. That path uses the native share sheet with an image file when supported, otherwise a download — it is separate from the share-link pipeline in createShareHandler.

Segment event	When it fires	Event properties
Hemsy Shared Look Opened	When this event is reported through the browser events API.	`shortId` (when present)

Shared look opens are always counted in Hemsy Home (Top Shared Links). Confirm Hemsy Shared Look Opened in your Segment debugger for your traffic; contact Hemsy if you need guaranteed Segment delivery on every open.

Example track payload

{
  "anonymousId": "visitor-42",
  "event": "Hemsy Try On Completed",
  "properties": {
    "selectedItemCount": 3,
    "productIds": ["123", "456"],
    "variantIds": ["789", "101112"],
    "sessionId": "a1b2c3d4-...",
    "storeSlug": "mystore"
  },
  "timestamp": "2026-05-20T15:04:05.123Z"
}

Testing

Save your Segment endpoint (and write key) in Integrations.
Embedded experience: Open Hemsy from your storefront with data-hemsy-anonymous-id set to a test ID (for example segment-test-001).
Hosted experience: Open https://{subdomain}.hemsy.ai?anonymous_id=segment-test-001 and run through upload → add items → try-on → checkout.
In Segment Sources → Debugger, confirm Hemsy * track events with anonymousId: segment-test-001.

If events are missing:

Confirm the integration shows Connected.
Confirm you are on the correct subdomain or embed slug.
Confirm the event is listed under Forwarded events, not Not forwarded.

Hemsy Embeds — embedded launch modes, data-hemsy-anonymous-id, cart vs checkout
Hemsy dashboard Home — aggregated KPIs and funnels (no Segment required)

Guides

Dashboard

API Reference

Where Segment forwarding applies

Setup

Identity stitching (`anonymousId`)

Embedded experience

Hosted experience

Checkout metadata

How forwarding works

Properties on every track call

Forwarded events

Session and engagement

Try-on funnel

Look building

Guided flows

Browse, filter, and search

Result screen

Hemsy Look Shared

`usedNativeShare` vs `shareUrl` (`type: share_link` only)

Example track payload

Testing

​Where Segment forwarding applies

​Setup

​Identity stitching (anonymousId)

​Embedded experience

​Hosted experience

​Checkout metadata

​How forwarding works

​Properties on every track call

​Forwarded events

​Session and engagement

​Try-on funnel

​Look building

​Guided flows

​Browse, filter, and search

​Result screen

​Hemsy Look Shared

​usedNativeShare vs shareUrl (type: share_link only)

​Sharing

​Example track payload

​Testing

​Related docs

Where Segment forwarding applies

Setup

Identity stitching (`anonymousId`)

Embedded experience

Hosted experience

Checkout metadata

How forwarding works

Properties on every track call

Forwarded events

Session and engagement

Try-on funnel

Look building

Guided flows

Browse, filter, and search

Result screen

Hemsy Look Shared

`usedNativeShare` vs `shareUrl` (`type: share_link` only)

Sharing

Example track payload

Testing

Related docs