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.

const variation: BucketedVariation = userContext.runExperience('experience-key');

// With attributes:
const variation: BucketedVariation = userContext.runExperience('experience-key', {
  locationProperties: { url: '/' },
  visitorProperties: { country: 'US' }
});

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.

const variations: BucketedVariation[] = userContext.runExperiences();

// With attributes:
const variations: BucketedVariation[] = userContext.runExperiences({
  locationProperties: { url: '/pricing' },
  visitorProperties: { plan: 'pro' },
  enableTracking: true
});

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.

import type {
  ConvertInterface, ConvertConfig, ContextInterface, BucketedVariation
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx'
} as ConvertConfig);

convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variation: BucketedVariation = context.runExperience('experience-key');
  console.log(variation);
});

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'
    }
}