Decide methods for the JavaScript (Node) SDK

Use the decide methods to return feature flag decisions for a user. Each decision includes whether the flag is enabled and which variation the user receives.

Decide

Returns a decision for a specific feature flag and user.

Minimum SDK version – v4.5+

Description

The decide method handles the variation decision for an individual experiment. It returns a decision result for a flag key for a user in an OptimizelyDecision object and contains the data required to deliver the flag rule.

This method ensures that Feature Experimentation properly buckets the user in experiment analytics, and you should use it if there is no need for pre-rendering decisions.

📘

Note

Decide is a method of the UserContext object. See OptimizelyUserContext for details.

See the OptimizelyDecision documentation for details of the returned decision object.

Parameters

The following table describes parameters for the decide method:

Returns

The decide method returns an OptimizelyDecision .

If the method encounters a critical error (SDK not ready, invalid flag key, and so on), then it returns a decision with a null variationKey field and populates the reasons field with error messages (regardless of the OptimizelyDecideOption.INCLUDE_REASONS option).

Example decide

// Create the user and decide which flag rule and variation they bucket into 
const attributes = {
  logged_in: true
};
const user = optimizely.createUserContext('user123', attributes);
const decision = user.decide('product_sort');

// The variation key. If null, decision fail with a critical error
const variationKey = decision['variationKey'];
if (variationKey === null) {
  console.log(' decision error: ', decision['reasons']);
}

// The flag enabled state
const enabled = decision['enabled'];

// Teh string variable value
const value = decision.variables['sort_method'];

// All variable values
const allVarValues = decision['variables'];

// Flag decision reasons
const reasons = decision['reasons'];

// The user for which the decision was made
const userContext = decision['userContext'];

Side Effects

Invokes the decision notification listener if this listener is enabled.

Decide all

Returns decisions for all active (unarchived) flags for a user.

Minimum SDK version – v4.5+

Description

Use the decide all method to retrieve decisions for all active flags before rendering content. This is particularly useful when you need to serve the correct cached version of your page or component based on the user's variation. For example when using an edge worker or cloud function.

Key features

• Pre-rendering decision – Lets you know all variation assignments ahead of time.
• Cache control – Lets you serve the correct cached content based on the user's pre-determined variations.
• Delay experiment tracking – Use DISABLE_DECISION_EVENT to prevent the SDK from recording a decision before the user sees the feature. This ensures that participation is only tracked when the experience is delivered.

Parameters

The following table describes parameters for the decide all method:

Returns

The decide all method returns a map of OptimizelyDecisions. For more information, see OptimizelyDecision.

If the method fails for all flags (for example, the SDK is not ready or the user context is invalid), then it returns an empty map. If the method detects an error for a specific flag, it returns error messages in the reasons field of the decision for that flag.

Example decideAll

const attributes = {
  logged_in: true
};

const user = optimizely.createUserContext('user123', attributes);
// Make decisions for all active (unarchived) flags in the project for a user
let decisions = user.decideAll();
// Or only for enabled flags
decisions = user.decideAll([OptimizelyDecideOption.ENABLED_FLAGS_ONLY]);

const flagKeys = Object.keys(decisions);
const decisionForFlag1 = decisions['flag_1'];

Side effects

Invokes the decide notification listener for each decision if this listener is enabled.

Decide for keys

Returns a map of flag decisions for specified flag keys.

Minimum SDK version – v4.5+

Description

Returns a map of decisions for the specified flag keys.

Parameters

The following table describes the parameters for the decide for keys method:

Returns

Returns a map of OptimizelyDecisions. For more information, see OptimizelyDecision.

If the method fails for all flags (for example, the SDK is not ready or the user context is invalid), then it returns an empty map. If the method detects an error for a specific flag, it returns error messages in the reasons field of the decision for that flag.

Example decideForKeys

// Make a decisions for specific enabled flags
const keys = ['flag_1', 'flag_2'];
const decisions = user.decideForKeys(keys);
const decision1 = decisions['flag_1'];
const decision2 = decisions['flag_2'];

Side effects

Invokes the decision notification listener for each decision if this listener is enabled.

OptimizelyDecideOption

The following table lists the OptimizelyDecideOption enum with an explanation what happens if you set them. In addition to setting these options individually for a decide method, you can also set them as global defaults when you instantiate the Optimizely client. See Initialize JavaScript (Node) SDK.

The following code sample shows how to implement the OptimizelyDecideOption as a global default and locally in a decide method call.

const { createInstance, OptimizelyDecideOption } = require('@optimizely/optimizely-sdk');

// Set global default decide options when initializing the client
const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY', // Replace with your SDK key
  defaultDecideOptions: [OptimizelyDecideOption.DISABLE_DECISION_EVENT],
});

if (optimizely) {
  optimizely.onReady().then(({ success, reason }) => {
    if (!success) {
      throw new Error(reason);
    }

    const user = optimizely.createUserContext('user123');
    if (!user) {
      throw new Error('failed to create user context');
    }

    // Set additional options in a decide call
    const decisionResults = user.decideAll(
      [
        OptimizelyDecideOption.ENABLED_FLAGS_ONLY,
        OptimizelyDecideOption.IGNORE_USER_PROFILE_SERVICE,
      ]
    );

    console.log(decisionResults);
  }).catch((err) => {
    // Handle error
  });
} else {
  // Handle instantiation error
}

Source files

The language and platform source files containing the implementation for the JavaScript (Node) SDK are available on GitHub.