Running Features

Features are resolved through variations of relevant experiences. When you run a feature, the SDK finds all experiences whose variations include a fullStackFeature change linked to that feature, evaluates targeting rules, buckets the visitor, and returns the resolved feature status and variable values. See the data model for the full resolution chain.

Run a Single Feature

Returns a single feature's status and variable values for the current visitor.

const feature = userContext.runFeature('feature-key');

// With attributes and experience filter:
const feature = userContext.runFeature('feature-key', {
  locationProperties: { url: '/settings' },
  visitorProperties: { role: 'admin' },
  typeCasting: true,
  experienceKeys: ['specific-experience-key']
});

use ConvertSdk\DTO\BucketedFeature;
use ConvertSdk\Enums\FeatureStatus;
use OpenAPI\Client\BucketingAttributes;

/** @var BucketedFeature|null $feature */
$feature = $context->runFeature('feature-key');

// With attributes and experience filter:
$feature = $context->runFeature('feature-key', new BucketingAttributes([
    'locationProperties' => ['url' => '/settings'],
    'visitorProperties' => ['role' => 'admin'],
    'typeCasting' => true,
    'experienceKeys' => ['specific-experience-key'],
]));

Parameters:

Parameter	Type	Required	Description
featureKey	string	Yes	The feature's unique key
attributes	object	No	Bucketing attributes (see creating a user context for the full attributes reference), plus:
			`typeCasting` (boolean) -- auto-convert values to the variable's defined type (default: `true`)
			`experienceKeys` (string[]) -- limit evaluation to specific experiences only

Run All Features

Returns all features with their status and variable values for the current visitor.

const features = userContext.runFeatures();

// With attributes:
const features = userContext.runFeatures({
  locationProperties: { url: '/dashboard' },
  visitorProperties: { tier: 'premium' },
  typeCasting: true
});

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

/** @var BucketedFeature[] $features */
$features = $context->runFeatures();

// With attributes:
$features = $context->runFeatures(new BucketingAttributes([
    'locationProperties' => ['url' => '/dashboard'],
    'visitorProperties' => ['tier' => 'premium'],
    'typeCasting' => true,
]));

Parameters:

Parameter	Type	Required	Description
attributes	object	No	Bucketing attributes (see creating a user context for the full attributes reference), plus `typeCasting` (boolean, default: `true`)

Returns: An array of BucketedFeature objects.

BucketedFeature Fields

Each resolved feature is returned as a BucketedFeature with the following fields:

Field	Type	Description
`featureId`	string	The feature ID
`featureKey`	string	The feature key
`status`	string / FeatureStatus	`"enabled"` or `"disabled"` (PHP uses the `FeatureStatus` enum)
`variables`	object / array	The feature variables with their resolved values

Complete Example

End-to-end flow: initialize the SDK, create a user context, run a feature, and check its status and variables.

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

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

convertSDK.onReady().then(() => {
  const context = convertSDK.createContext('user-unique-id');
  const feature = context.runFeature('feature-key');

  if (feature && feature.status === 'enabled') {
    console.log('Feature is enabled with variables:', feature.variables);
  }
});

use ConvertSdk\ConvertSDK;
use ConvertSdk\DTO\BucketedFeature;
use ConvertSdk\Enums\FeatureStatus;

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

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

    /** @var BucketedFeature|null $feature */
    $feature = $context->runFeature('feature-key');

    if ($feature !== null && $feature->status === FeatureStatus::Enabled) {
        echo 'Feature is enabled';
        print_r($feature->variables);
    }
}