Segments

When analyzing A/B test results, you often want to break down the data by visitor characteristics:

• "How did mobile users respond to variation B?"
• "Did premium-tier users convert more often?"
• "What was the conversion rate for visitors from Canada?"

These categorizations are called segments. The SDK needs a way to evaluate which segments a visitor belongs to and include that information in tracking data sent to the Convert dashboard.

What is SegmentsManager? The Sorting Desk

Think of the SegmentsManager as a sorting desk that categorizes incoming mail (visitors) into the right mailboxes (segments). It checks visitor attributes against segment rules and stores the results for use in tracking and reporting.

Its key responsibilities are:

1. Evaluate Segments: Check which segments a visitor matches based on their attributes.
2. Store Segment Data: Persist segment assignments in the visitor's data store.
3. Provide Segments for Tracking: Supply segment information to the API layer for inclusion in tracking payloads.

How Segments Are Used

You interact with the SegmentsManager through the Context object:

1. Set Default Segments (for reporting):

Default segments are standard dimensions that appear in Convert reports.

context = sdk.createContext("user123", {country: "US"})

// Set reporting segments
context.setDefaultSegments({
    country: "US",
    browser: "chrome",
    devices: "desktop",
    source: "organic",
})

Only these properties are included in Convert Reports: browser, devices, source, campaign, visitorType, country.

2. Run Custom Segments:

Custom segments use rule-based matching against visitor attributes.

// Evaluate which custom segments match this visitor
matchedSegments = context.runCustomSegments(
    ["premium-users", "high-value"],
    {plan: "enterprise", lifetime_value: 5000}
)

Under the Hood: How Segments Are Evaluated

When you call context.runCustomSegments():

1. Context delegates to the SegmentsManager.
2. SegmentsManager looks up the segment definitions from the Data Management layer by key.
3. For each segment, it uses the Rule Evaluation engine to evaluate the segment's rules against the visitor's attributes.
4. Matched segments are stored via the Data Management layer and returned.

sequenceDiagram
    participant Context as Context
    participant SegMgr as SegmentsManager
    participant DataMgr as DataManager
    participant RuleMgr as RuleManager

    Context->>+SegMgr: selectCustomSegments('user123', ['premium-users'], attributes)
    SegMgr->>+DataMgr: Get segment definition for 'premium-users'
    DataMgr-->>-SegMgr: ConfigSegment {rules: {...}}
    SegMgr->>+RuleMgr: isRuleMatched(visitorData, segmentRules)
    RuleMgr-->>-SegMgr: true (match)
    SegMgr->>+DataMgr: Store segment assignment for 'user123'
    DataMgr-->>-SegMgr: Done
    SegMgr-->>-Context: Return VisitorSegments

How Segment Evaluation Works

1. Evaluating Custom Segments

The SegmentsManager iterates through each requested segment key:

function selectCustomSegments(visitorId, segmentKeys, segmentRule):
    matchedSegments = {}

    for each key in segmentKeys:
        // Look up the segment definition
        segment = dataManager.getEntity(key, "segments")
        if segment is null:
            continue

        // Use RuleManager to evaluate the segment's rules
        rules = segmentRule or segment.rules
        matched = ruleManager.isRuleMatched(segmentRule or {}, rules)

        if matched is true:
            matchedSegments[segment.id] = segment.key
        else if matched is RuleError:
            return matched

    // Store the matched segments
    segments = VisitorSegments(customSegments: matchedSegments)
    putSegments(visitorId, matchedSegments)

    return segments

• Iterates through each segment key.
• Looks up the segment definition from the config via the Data Management layer.
• Uses the Rule Evaluation engine to check if the visitor matches the segment rules.
• Stores matched segments and returns them.

2. Storing and Retrieving Segments

function getSegments(visitorId):
    data = dataManager.getData(visitorId)
    return VisitorSegments(
        customSegments: data.segments.customSegments or {}
    )

function putSegments(visitorId, segments):
    dataManager.putData(visitorId, {
        segments: {customSegments: segments}
    })

• Segments are persisted alongside other visitor data (bucketing decisions, etc.) in the data store.
• If a persistent cache is configured, segments persist across requests.

Segments vs. Audiences

While both segments and audiences involve categorizing visitors, they serve different purposes:

• Audiences determine whether a visitor qualifies for an experience. They act as gatekeepers evaluated before bucketing.
• Segments categorize visitors after bucketing for reporting and analysis. They do not affect which variation a visitor sees.

Summary

The SegmentsManager handles visitor categorization for Convert's reporting system. It evaluates segment rules against visitor attributes and stores the results for inclusion in tracking data.

Key takeaways:

1. Segments are important for analyzing A/B test results by visitor characteristics.
2. Default reporting segments cover standard dimensions (browser, device, source, country, etc.).
3. Custom segments use rule-based matching via the Rule Evaluation engine.
4. Segment data persists alongside other visitor data in the data store managed by the Data Management layer.