Visitor Context & Properties

A Context 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. To ensure consistency even when configuration changes, provide a persistent DataStore.

Creating a User Context

import type {ContextInterface} from '@convertcom/js-sdk';

const userContext = convertSDK.createContext(
  'user-unique-id',
  {
    country: 'US',
    language: 'en'
  }
);

use ConvertSdk\Interfaces\ContextInterface;

$context = $sdk->createContext(
    'visitor-unique-id',
    [
        'country' => 'US',
        'language' => 'en',
    ]
);

The first argument is the visitor's unique ID. The second is an optional object of initial visitor properties used for audience and segment evaluation.

Bucketing Attributes

Every context method that runs experiences or features accepts an optional attributes object. This table lists all supported properties:

Property	Type	Description
`locationProperties`	object / array	Key-value pairs used for evaluating experience locations
`visitorProperties`	object / array	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
`typeCasting`	boolean	Auto-convert feature variable values to the variable's defined type (default: `true`)
`experienceKeys`	string[]	Limit feature evaluation to specific experiences only

const variation = userContext.runExperience('experience-key', {
  locationProperties: { url: '/pricing' },
  visitorProperties: { plan: 'pro' },
  updateVisitorProperties: true,
  enableTracking: true
});

use OpenAPI\Client\BucketingAttributes;

$variation = $context->runExperience('experience-key', new BucketingAttributes([
    'locationProperties' => ['url' => '/pricing'],
    'visitorProperties' => ['plan' => 'pro'],
    'updateVisitorProperties' => true,
    'enableTracking' => true,
]));

Visitor Properties

Visitor properties are key-value pairs used in audience evaluation and segment matching. They can be set at context creation, updated later, or passed inline with any experience/feature call.

Update Visitor Properties

Permanently merges new properties into the visitor's existing properties.

userContext.updateVisitorProperties({
  weather: 'rainy',
  plan: 'enterprise'
});

// Set a single attribute
$context->setAttribute('weather', 'rainy');

// Set multiple attributes (merges with existing)
$context->setAttributes([
    'weather' => 'rainy',
    'plan' => 'enterprise',
]);

// Update via the data store (persists across requests when using a persistent cache)
$context->updateVisitorProperties('visitor-unique-id', [
    'weather' => 'rainy',
    'plan' => 'enterprise',
]);

Inline Update

Visitor properties can also be updated inline when calling any experience or feature method by setting updateVisitorProperties to true in the attributes:

const variation = userContext.runExperience('experience-key', {
  visitorProperties: { weather: 'rainy' },
  updateVisitorProperties: true
});

use OpenAPI\Client\BucketingAttributes;

$variation = $context->runExperience('experience-key', new BucketingAttributes([
    'visitorProperties' => ['weather' => 'rainy'],
    'updateVisitorProperties' => true,
]));

Custom Segments

Custom segments represent audiences of type segmentation. Use runCustomSegments to evaluate segment rules against the current visitor context.

userContext.runCustomSegments(['segment-key-1', 'segment-key-2'], {
  enabled: true
});

$context->runCustomSegments(['segment-key-1', 'segment-key-2'], [
    'ruleData' => ['enabled' => true],
]);

Parameters:

Parameter	Type	Required	Description
segmentKeys	string[]	Yes	List of segment keys to evaluate
attributes	object / array	No	Key-value pairs used for segment matching (PHP wraps these under a `ruleData` key)

In Fullstack projects, segments do not persist unless you provide a DataStore. See the segments concept for more detail on how segmentation works.

Default Segments

Default segments are used for Convert reporting. Use setDefaultSegments to permanently update the visitor's default segments. Only the following properties are included in Convert Reports:

browser
devices
source
campaign
visitorType
country

userContext.setDefaultSegments({
  country: 'US',
  browser: 'chrome',
  devices: 'desktop'
});

$context->setDefaultSegments([
    'country' => 'US',
    'browser' => 'chrome',
    'devices' => 'desktop',
]);

Parameters:

Parameter	Type	Required	Description
segments	object / array	Yes	Key-value pairs merged with the initial visitor properties

Config Entity Lookup

You can look up any entity in the project configuration by its key or numeric ID.

Get Entity by Key

import ConvertSDK, {EntityType} from '@convertcom/js-sdk';
import type {Experience} from '@convertcom/js-sdk';

const experience = userContext.getConfigEntity(
  'experience-key',
  EntityType.EXPERIENCE
);

use ConvertSdk\Enums\EntityType;

$experience = $context->getConfigEntity('experience-key', EntityType::Experience->value);

Parameters:

Parameter	Type	Required	Description
key	string	Yes	Entity key
entityType	EntityType / string	Yes	One of: `AUDIENCE`, `LOCATION`, `SEGMENT`, `FEATURE`, `GOAL`, `EXPERIENCE`, `VARIATION`

Get Entity by ID

import ConvertSDK, {EntityType, VariationChangeType} from '@convertcom/js-sdk';
import type {BucketedVariation, Feature, VariationChange} from '@convertcom/js-sdk';

const variation = userContext.runExperience('experience-key');
const changesData = variation.changes.find(
  ({type}) => type === VariationChangeType.FULLSTACK_FEATURE
);
const feature = userContext.getConfigEntityById(
  changesData.data.feature_id,
  EntityType.FEATURE
);

use ConvertSdk\Enums\EntityType;

$variation = $context->runExperience('experience-key');
if ($variation !== null) {
    $changes = $variation->changes;
    foreach ($changes as $change) {
        if (isset($change['data']['feature_id'])) {
            $feature = $context->getConfigEntityById(
                (string) $change['data']['feature_id'],
                EntityType::Feature->value
            );
        }
    }
}

Parameters:

Parameter	Type	Required	Description
id	number / string	Yes	Entity numeric ID (PHP passes it as a string)
entityType	EntityType / string	Yes	Same values as `getConfigEntity` above

Both methods return the matching entity object (or array in PHP), or null if not found.