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 BucketedVariation object tells you which variation the visitor was assigned to and what changes (feature flags, variables) are associated with it.

Run a Single Experience

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

use ConvertSdk\DTO\BucketedVariation;
use OpenAPI\Client\BucketingAttributes;

/** @var BucketedVariation|null $variation */
$variation = $context->runExperience('experience-key');

// With attributes:
$variation = $context->runExperience('experience-key', new BucketingAttributes([
    'locationProperties' => ['url' => '/'],
    'visitorProperties' => ['country' => 'US'],
]));

Parameters:

Parameter	Type	Required	Description
experienceKey	string	Yes	The experience's unique key
attributes	object	No	See BucketingAttributes below

Returns: BucketedVariation -- the assigned variation, or null if the visitor was not bucketed (rule mismatch, inactive experience, etc.). See BucketedVariation below.

Run All Active Experiences

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

use ConvertSdk\DTO\BucketedVariation;
use OpenAPI\Client\BucketingAttributes;

/** @var BucketedVariation[] $variations */
$variations = $context->runExperiences();

// With attributes:
$variations = $context->runExperiences(new BucketingAttributes([
    'locationProperties' => ['url' => '/pricing'],
    'visitorProperties' => ['plan' => 'pro'],
    'enableTracking' => true,
]));

Parameters:

Parameter	Type	Required	Description
attributes	object	No	See BucketingAttributes below

Returns: Array<BucketedVariation> -- one entry per experience the visitor was bucketed into.

BucketingAttributes

Every context method that runs experiences or features accepts an optional attributes object. In PHP this is a BucketingAttributes DTO; in JavaScript it is a plain object.

Property	Type	Description
locationProperties	object	Key-value pairs used for evaluating experience locations
visitorProperties	object	Key-value pairs used for evaluating experience audiences (overwrites same keys from context creation)
updateVisitorProperties	boolean	Whether to permanently update in-memory visitor properties
enableTracking	boolean	Whether to track bucketing events immediately (default: true)
environment	string	Override environment for this call

BucketedVariation

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

Property	Type	Description
experienceId	string	The experience ID
experienceKey	string	The experience key
variationId	string	The variation ID
variationKey	string	The variation key
changes	array	The variation changes (feature change data)

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

Complete Example

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

use ConvertSdk\ConvertSDK;
use ConvertSdk\DTO\BucketedVariation;

$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
]);

if ($sdk->isReady()) {
    $context = $sdk->createContext('visitor-unique-id');

    /** @var BucketedVariation|null $variation */
    $variation = $context->runExperience('experience-key');

    if ($variation !== null) {
        echo $variation->experienceKey; // 'experience-key'
        echo $variation->variationKey;  // e.g. 'variation-1'
    }
}