visitor context

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

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
});

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

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
});

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
});

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

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

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

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.