running experiences

Running Experiences

Running an experience evaluates a visitor against the experience's targeting rules (audiences and locations) and deterministically assigns them to a variation. The SDK uses the visitor's unique ID and a MurmurHash-based bucketing algorithm to ensure the same visitor always sees the same variation, as long as the experience configuration has not changed.

Once bucketed, the returned Variation object tells you which experience and variation the visitor was assigned to.

Run a Single Experience

Evaluate a single experience by its unique key. Returns the bucketed variation if the visitor qualifies, or nil if they do not.

// Async/await
if let variation = await ctx.runExperience("experience-key") {
    print("variation: \(variation.key)")
}

// With tracking disabled for this call:
let variation = await ctx.runExperience("experience-key", enableTracking: false)

Completion-handler overload (for UIKit / Objective-C callers):

// Completion variant — result delivered on the MainActor
ctx.runExperience("experience-key") { variation in
    guard let variation else { return }
    print("variation: \(variation.key)")
}

Parameters:

Parameter	Type	Required	Description
key	String	Yes	The experience's unique key
enableTracking	Bool	No	Whether to report the bucketing event (default: true)

Returns: Variation? — the assigned variation, or nil if the visitor was not bucketed (rule mismatch, inactive experience, or the SDK is not yet ready).

Run All Active Experiences

Loop through every active experience in the project, evaluate targeting rules for each, and return the bucketed Variation for every experience the visitor qualifies for.

// Async/await
let variations = await ctx.runExperiences()

for variation in variations {
    print("\(variation.experienceKey) → \(variation.key)")
}

// Evaluate without reporting bucketing events:
let untracked = await ctx.runExperiences(enableTracking: false)

Completion-handler overload:

ctx.runExperiences { variations in
    for variation in variations {
        print("\(variation.experienceKey) → \(variation.key)")
    }
}

Parameters:

Parameter	Type	Required	Description
enableTracking	Bool	No	Whether to report bucketing events (default: true)

Returns: [Variation] — one entry per experience the visitor was bucketed into, in config order. Returns [] when the SDK is not yet ready.

Variation Fields

The object returned when a visitor is successfully bucketed into an experience variation.

Property	Type	Description
id	String	The variation ID
key	String	The variation key
experienceId	String	The experience ID
experienceKey	String	The experience key

See the Data Model for the full type definition and how variations map to features.

Tracking Control

The iOS SDK has three layers of tracking control:

• Config-level (ConvertConfiguration.networkTracking): a static flag set at init time. When false, no bucketing events are ever enqueued.
• Per-call (enableTracking parameter): suppresses the bucketing enqueue for this call only. Decisioning still runs and the variation is still persisted.
• Runtime (sdk.setTrackingEnabled(_:)): a mutable actor-isolated flag that can be toggled mid-session (for consent withdrawal). See Tracking Control.

Both the config-level and runtime flags are combined with the per-call parameter: a bucketing event is only enqueued when all three allow it.

Complete Example

A full flow: initialize the SDK, create a visitor context, run an experience, and use the result.

import ConvertSwiftSDK

let sdk = ConvertSwiftSDK(configuration: ConvertConfiguration(sdkKey: "YOUR_SDK_KEY"))

Task {
    try await sdk.ready()
    let ctx = sdk.createContext(visitorId: "user-unique-id")
    if let variation = await ctx.runExperience("experience-key") {
        switch variation.key {
        case "control":
            renderControl()
        case "treatment":
            renderTreatment()
        default:
            renderControl()
        }
    } else {
        renderControl() // not bucketed / experience absent
    }
}