visitor context

Visitor Context & Properties

A ConvertContext ties all SDK actions to a specific visitor. A unique visitor ID is required for deterministic bucketing — as long as the ID and experience configuration remain the same, bucketing stays consistent. The iOS SDK persists the visitor ID automatically (see Persistent Datastore for how this works).

Creating a User Context

// Auto-generated visitor ID (persisted in Keychain across sessions):
let ctx = sdk.createContext()

// Caller-supplied visitor ID (used verbatim; no store access):
let ctx = sdk.createContext(visitorId: "user-unique-id")

// With initial visitor attributes for audience and segment evaluation:
let ctx = sdk.createContext(
    visitorId: "user-unique-id",
    attributes: ["country": "US", "language": "en"]
)

The visitorId parameter is optional. When omitted (or nil), the SDK resolves a persistent UUID from the Keychain, falling back to a UserDefaults mirror and then generating a fresh one. See Persistent Datastore for the full resolution precedence.

The attributes parameter is [String: Any], accepting String, Int, Double, and Bool scalar values. Nested objects and arrays are not supported and are silently dropped (logged at DEBUG). These attributes are used in audience and segment evaluation.

Parameters:

Parameter	Type	Required	Description
visitorId	String?	No	The visitor's unique ID. When nil, a persistent UUID is resolved from the Keychain
attributes	[String: Any]?	No	Initial visitor attributes for audience and segment evaluation

Returns: ConvertContext — a visitor-scoped handle for running experiences, features, and tracking conversions.

Visitor Attributes

Visitor attributes are key-value pairs used in audience evaluation. They are set at context creation and are immutable for the lifetime of a ConvertContext. To supply different attributes for a new session, create a new context.

let ctx = sdk.createContext(
    visitorId: "user-unique-id",
    attributes: [
        "country": "US",
        "plan": "pro",
        "accountAge": 365,
    ]
)

The visitorId is resolved at context creation and never changes. Bucketing is always deterministic for the same (visitorId, experience) pair.

Default Segments

Default segments are used for Convert reporting. Call setDefaultSegments to record the visitor's recognized segment values. Only the following keys are included in Convert Reports:

• browser
• devices
• source
• campaign
• visitorType
• country

await ctx.setDefaultSegments([
    "country": "US",
    "browser": "safari",
    "devices": "mobile",
    "visitorType": "returning",
])

Unrecognized keys are ignored with a [WARN] log line. setDefaultSegments is async but never throws (AOD-6 — the SDK's always-on degradation contract).

Parameters:

Parameter	Type	Required	Description
segments	[String: String]	Yes	Key-value pairs for the six recognized reporting fields

Default segments are persisted in the SDK's decision store and overlaid onto the audience rule attribute map on each runExperience / runExperiences / runFeature / runFeatures call. Explicit createContext attributes take precedence on key collision.

Custom Segments

Custom segments represent audiences of type segmentation. Use setCustomSegments to append segment identifiers for the visitor:

await ctx.setCustomSegments(["vip", "beta-tester"])

Custom segment IDs are appended to the visitor's existing set. The backend owns deduplication.

Parameters:

Parameter	Type	Required	Description
segmentIds	[String]	Yes	Custom segment identifiers to append

Both setDefaultSegments and setCustomSegments fire the SystemEvent.segments bus event once with the updated Segments payload, so any sdk.on(.segments) subscriber is notified.

Completion-Handler Overloads

The segment methods are async. For UIKit callers that prefer a callback style, wrap them in a Task:

Task {
    await ctx.setDefaultSegments(["country": "US", "browser": "safari"])
}

Context Isolation

Each call to sdk.createContext(...) returns an independent ConvertContext. However, all contexts created from the same SDK share a single DecisionStore, so sticky variation assignments, goal deduplication, and segment state converge on the same in-memory and on-disk store.