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',
    ]
);

val context = sdk.createContext(
    visitorId = "user-unique-id",
    attributes = mapOf("country" to "US", "language" to "en"),
)

context = CONVERT_SDK.create_context(
  "user-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,
]));

// Targeting input is set on the context, then the experience is run:
ctx.setLocationProperties(mapOf("url" to "/pricing"))
ctx.setAttributes(mapOf("plan" to "pro"))
val variation = ctx.runExperience("experience-key")

# Visitor properties are flat top-level keys; location_properties, environment,
# and enable_tracking are the reserved keys. (There is no inline
# updateVisitorProperties flag — use update_visitor_properties below to persist.)
variation = context.run_experience("experience-key", {
  plan: "pro",
  location_properties: { url: "/pricing" },
  enable_tracking: 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',
]);

// setAttributes replaces the visitor's attributes; combine maps to merge.
ctx.setAttributes(mapOf("weather" to "rainy", "plan" to "enterprise"))

# Merges into the visitor's stored properties (persists via the configured store)
# and the in-memory context attributes.
context.update_visitor_properties(
  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,
]));

The Ruby SDK has no inline updateVisitorProperties flag — pass per-call visitor properties for matching only, and call update_visitor_properties (above) when you want them persisted.

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],
]);

context.run_custom_segments(["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',
]);

ctx.setDefaultSegments(mapOf(
    "country" to "US",
    "browser" to "chrome",
    "devices" to "desktop",
))

context.set_default_segments(
  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);

# entity_type accepts :experience, :feature, or :goal (symbol or string).
experience = context.get_config_entity("experience-key", :experience)

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.

The Ruby SDK resolves config entities by key only (get_config_entity(key, entity_type) with entity_type one of :experience, :feature, :goal); it has no by-ID variant.