Custom Segments

A segment is an attribute you attach to a visitor, like their subscription plan or account tier. Use it to slice your experiment results later. Tag visitors with their plan, then on the results page filter to see how the experiment performed for premium users versus free users.

Method signature

TypeScript

// avsb.track.segment, a member of AvsbTrackFunction in @avsbhq/snippet-typessegment(segmentKey: string, segmentValue: string): void

TypeScript2 lines

Parameters

Name	Type	Required	Description
`segmentKey`	string	Yes	The name of the attribute, matching a segment you already created in Metrics → Segments. Use letters, digits, and underscores, for example `userTier`, `plan_type`, `utm_source`.
`segmentValue`	string	Yes	The value to assign for this visitor. Must be a string. Examples: "premium", "enterprise", "free", "returning".

avsb.track.segment() itself also accepts dots and hyphens in a segmentKey without complaint, for example utm.source. But a segment can only ever be created with letters, digits, and underscores. A key with a dot or a hyphen can never be registered, so it will never appear as a filter. Stick to letters, digits, and underscores everywhere.

Defining segments first

Before a segment can be used to filter results, you must create it in your project. Calling avsb.track.segment() with a key you have not created will not throw an error, and the data is still recorded. It just will not appear as a filter on the results page until you create a matching segment. If you register the key later, the values you already sent show up too. So nothing is lost by creating the segment after the code that tracks it.

To create a custom segment:

The project's Metrics page with the Segments tab open, showing a table of existing segments and a New segment button.

In your project, go to Metrics in the sidebar.
Select the Segments tab.

Then select New segment. Enter a Name and a Key, using the key exactly as you will use it in code. Optionally add a description and starting values, then select Create segment.

The segment key is now registered, and calls to avsb.track.segment() using that key will be recorded.

When to call it

An exposure is the moment a visitor is actually counted in an experiment, usually when they see the part being tested. Call avsb.track.segment() as early in the page as you can, before that moment, ideally right after you know the visitor's attributes. A good time is right after your login check, or after loading the visitor's profile from your own API. The earlier you call it, the more exposures will carry the segment.

If you call avsb.track.segment() after a visitor has already been counted in an exposure, the segment still applies retroactively to that exposure record. Calling it before any experiment runs is still the safest habit.

Code examples

The simplest case: set one attribute once you know it.

JavaScript

avsb.track.segment('userTier', 'premium');

JavaScript1 line

A common example: load the visitor's profile, then tag several attributes at once.

JavaScript

fetch('/api/me')  .then(function(response) { return response.json(); })  .then(function(user) {    avsb.track.segment('plan', user.plan);    avsb.track.segment('userTier', user.tier);    avsb.track.segment('region', user.region);  });

JavaScript7 lines

Auto-collected segments

A vs B automatically collects several segments for every visitor, with no avsb.track.segment() call needed. These already show up as filters on the results page:

Device: desktop, mobile, or tablet, worked out from the visitor's browser.
Country: the visitor's country, worked out from their network location.
Browser: chrome, firefox, safari, edge, and others.
Platform: windows, macos, ios, android, linux.
Language: the visitor's browser language, for example en or fr (just the language, not the region).
User type: new for a first-time visitor, returning for one who has been to the site before.

cart_band (the visitor's cart total at exposure, bucketed) and purchaser (true or false, from purchase history) are sent automatically once an experiment uses commerce conditions. No code is needed to collect them.

Like the segments above, they need no registration. They appear as results filters (Cart value and Purchaser) on any experiment that has recorded them, and stay hidden on experiments that have not.

Using segments to filter results

Once a segment is being collected, it appears as a filter in your experiment results. On the results page, look for the Segments panel. Select any segment key and filter the results table to show only visitors with a specific value.

For example, if you tagged visitors with avsb.track.segment('plan', 'premium'), you can filter the results to see conversion rates for premium subscribers only. This can reveal whether your experiment had different effects on different groups, which is often more useful than the overall result.

Segment values are stored on the visitor record, not tied to one experiment. A segment you set for one experiment automatically applies to every other running experiment for the same visitor. Tag visitors consistently with their plan, and every experiment benefits without extra work.

Calling avsb.track.segment() with a key you have not created will not throw an error, and it does not lose the data. But the key will not appear in the Segments panel on the results page until you create it, so create the segment key before you rely on filtering by it.