com.optimizely.ab

Class Optimizely

java.lang.Object

com.optimizely.ab.Optimizely

All Implemented Interfaces:

java.lang.AutoCloseable

@ThreadSafe
public class Optimizely
extends java.lang.Object
implements java.lang.AutoCloseable

Top-level container class for Optimizely functionality. Thread-safe, so can be created as a singleton and safely passed around. Example instantiation:

     Optimizely optimizely = Optimizely.builder(projectWatcher, eventHandler).build();
 

To activate an experiment and perform variation specific processing:

     Variation variation = optimizely.activate(experimentKey, userId, attributes);
     if (variation.is("ALGORITHM_A")) {
         // execute code for algorithm A
     } else if (variation.is("ALGORITHM_B")) {
         // execute code for algorithm B
     } else {
         // execute code for default algorithm
     }
 

NOTE: by default, all exceptions originating from Optimizely calls are suppressed. For example, attempting to activate an experiment that does not exist in the project config will cause an error to be logged, and for the "control" variation to be returned.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Optimizely.Builder Optimizely instance builder.

Field Summary

Fields

Modifier and Type	Field and Description
java.util.List<OptimizelyDecideOption>	defaultDecideOptions
NotificationCenter	notificationCenter

Method Summary

Modifier and Type	Method and Description
Variation	activate(Experiment experiment, java.lang.String userId)
Variation	activate(Experiment experiment, java.lang.String userId, java.util.Map<java.lang.String,?> attributes)
Variation	activate(java.lang.String experimentKey, java.lang.String userId)
Variation	activate(java.lang.String experimentKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes)
int	addDecisionNotificationHandler(NotificationHandler<DecisionNotification> handler) Convenience method for adding DecisionNotification Handlers
int	addLogEventNotificationHandler(NotificationHandler<LogEvent> handler) Convenience method for adding LogEvent Notification Handlers
<T> int	addNotificationHandler(java.lang.Class<T> clazz, NotificationHandler<T> handler) Convenience method for adding NotificationHandlers
int	addTrackNotificationHandler(NotificationHandler<TrackNotification> handler) Convenience method for adding TrackNotification Handlers
int	addUpdateConfigNotificationHandler(NotificationHandler<UpdateConfigNotification> handler) Convenience method for adding UpdateConfigNotification Handlers
static Optimizely.Builder	builder()
static Optimizely.Builder	builder(java.lang.String datafile, EventHandler eventHandler) Deprecated.
void	close() Checks if eventHandler EventHandler and projectConfigManager ProjectConfigManager are Closeable Closeable and calls close on them.
OptimizelyUserContext	createUserContext(java.lang.String userId)
OptimizelyUserContext	createUserContext(java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Create a context of the user for which decision APIs will be called.
java.util.List<java.lang.String>	fetchQualifiedSegments(java.lang.String userId, java.util.List<ODPSegmentOption> segmentOptions)
void	fetchQualifiedSegments(java.lang.String userId, ODPSegmentManager.ODPSegmentFetchCallback callback, java.util.List<ODPSegmentOption> segmentOptions)
OptimizelyJSON	getAllFeatureVariables(java.lang.String featureKey, java.lang.String userId) Get the values of all variables in the feature.
OptimizelyJSON	getAllFeatureVariables(java.lang.String featureKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the values of all variables in the feature.
java.util.List<java.lang.String>	getEnabledFeatures(java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the list of features that are enabled for the user.
java.lang.Boolean	getFeatureVariableBoolean(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId) Get the Boolean value of the specified variable in the feature.
java.lang.Boolean	getFeatureVariableBoolean(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the Boolean value of the specified variable in the feature.
java.lang.Double	getFeatureVariableDouble(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId) Get the Double value of the specified variable in the feature.
java.lang.Double	getFeatureVariableDouble(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the Double value of the specified variable in the feature.
java.lang.Integer	getFeatureVariableInteger(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId) Get the Integer value of the specified variable in the feature.
java.lang.Integer	getFeatureVariableInteger(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the Integer value of the specified variable in the feature.
OptimizelyJSON	getFeatureVariableJSON(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId) Get the JSON value of the specified variable in the feature.
OptimizelyJSON	getFeatureVariableJSON(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the JSON value of the specified variable in the feature.
java.lang.String	getFeatureVariableString(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId) Get the String value of the specified variable in the feature.
java.lang.String	getFeatureVariableString(java.lang.String featureKey, java.lang.String variableKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Get the String value of the specified variable in the feature.
Variation	getForcedVariation(java.lang.String experimentKey, java.lang.String userId) Gets the forced variation for a given user and experiment.
NotificationCenter	getNotificationCenter()
ODPManager	getODPManager()
OptimizelyConfig	getOptimizelyConfig() Get OptimizelyConfig containing experiments and features map
ProjectConfig	getProjectConfig()
UserProfileService	getUserProfileService()
Variation	getVariation(Experiment experiment, java.lang.String userId)
Variation	getVariation(Experiment experiment, java.lang.String userId, java.util.Map<java.lang.String,?> attributes)
Variation	getVariation(java.lang.String experimentKey, java.lang.String userId)
Variation	getVariation(java.lang.String experimentKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes)
void	identifyUser(java.lang.String userId)
java.lang.Boolean	isFeatureEnabled(java.lang.String featureKey, java.lang.String userId) Determine whether a boolean feature is enabled.
java.lang.Boolean	isFeatureEnabled(java.lang.String featureKey, java.lang.String userId, java.util.Map<java.lang.String,?> attributes) Determine whether a boolean feature is enabled.
boolean	isValid() Determine if the instance of the Optimizely client is valid.
void	sendODPEvent(java.lang.String type, java.lang.String action, java.util.Map<java.lang.String,java.lang.String> identifiers, java.util.Map<java.lang.String,java.lang.Object> data) Send an event to the ODP server.
boolean	setForcedVariation(java.lang.String experimentKey, java.lang.String userId, java.lang.String variationKey) Force a user into a variation for a given experiment.
void	track(java.lang.String eventName, java.lang.String userId)
void	track(java.lang.String eventName, java.lang.String userId, java.util.Map<java.lang.String,?> attributes)
void	track(java.lang.String eventName, java.lang.String userId, java.util.Map<java.lang.String,?> attributes, java.util.Map<java.lang.String,?> eventTags)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultDecideOptions

public final java.util.List<OptimizelyDecideOption> defaultDecideOptions

notificationCenter

public final NotificationCenter notificationCenter

Method Detail

isValid

public boolean isValid()

Determine if the instance of the Optimizely client is valid. An instance can be deemed invalid if it was not initialized properly due to an invalid datafile being passed in.

Returns:

True if the Optimizely instance is valid. False if the Optimizely instance is not valid.

close

public void close()

Checks if eventHandler EventHandler and projectConfigManager ProjectConfigManager are Closeable Closeable and calls close on them. NOTE: There is a chance that this could be long running if the implementations of close are long running.

Specified by:

close in interface java.lang.AutoCloseable

activate

@Nullable
public Variation activate(@Nonnull
                                    java.lang.String experimentKey,
                                    @Nonnull
                                    java.lang.String userId)
                             throws UnknownExperimentException

Throws:

UnknownExperimentException

activate

@Nullable
public Variation activate(@Nonnull
                                    java.lang.String experimentKey,
                                    @Nonnull
                                    java.lang.String userId,
                                    @Nonnull
                                    java.util.Map<java.lang.String,?> attributes)
                             throws UnknownExperimentException

Throws:

UnknownExperimentException

activate

@Nullable
public Variation activate(@Nonnull
                                    Experiment experiment,
                                    @Nonnull
                                    java.lang.String userId)

activate

@Nullable
public Variation activate(@Nonnull
                                    Experiment experiment,
                                    @Nonnull
                                    java.lang.String userId,
                                    @Nonnull
                                    java.util.Map<java.lang.String,?> attributes)

track

public void track(@Nonnull
                  java.lang.String eventName,
                  @Nonnull
                  java.lang.String userId)
           throws UnknownEventTypeException

Throws:

UnknownEventTypeException

track

public void track(@Nonnull
                  java.lang.String eventName,
                  @Nonnull
                  java.lang.String userId,
                  @Nonnull
                  java.util.Map<java.lang.String,?> attributes)
           throws UnknownEventTypeException

Throws:

UnknownEventTypeException

track

public void track(@Nonnull
                  java.lang.String eventName,
                  @Nonnull
                  java.lang.String userId,
                  @Nonnull
                  java.util.Map<java.lang.String,?> attributes,
                  @Nonnull
                  java.util.Map<java.lang.String,?> eventTags)
           throws UnknownEventTypeException

Throws:

UnknownEventTypeException

isFeatureEnabled

@Nonnull
public java.lang.Boolean isFeatureEnabled(@Nonnull
                                                   java.lang.String featureKey,
                                                   @Nonnull
                                                   java.lang.String userId)

Determine whether a boolean feature is enabled. Send an impression event if the user is bucketed into an experiment using the feature.

Parameters:

featureKey - The unique key of the feature.

userId - The ID of the user.

Returns:

True if the feature is enabled. False if the feature is disabled. False if the feature is not found.

isFeatureEnabled

@Nonnull
public java.lang.Boolean isFeatureEnabled(@Nonnull
                                                   java.lang.String featureKey,
                                                   @Nonnull
                                                   java.lang.String userId,
                                                   @Nonnull
                                                   java.util.Map<java.lang.String,?> attributes)

Determine whether a boolean feature is enabled. Send an impression event if the user is bucketed into an experiment using the feature.

Parameters:

featureKey - The unique key of the feature.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

True if the feature is enabled. False if the feature is disabled. False if the feature is not found.

getFeatureVariableBoolean

@Nullable
public java.lang.Boolean getFeatureVariableBoolean(@Nonnull
                                                             java.lang.String featureKey,
                                                             @Nonnull
                                                             java.lang.String variableKey,
                                                             @Nonnull
                                                             java.lang.String userId)

Get the Boolean value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

Returns:

The Boolean value of the boolean single variable feature. Null if the feature could not be found.

getFeatureVariableBoolean

@Nullable
public java.lang.Boolean getFeatureVariableBoolean(@Nonnull
                                                             java.lang.String featureKey,
                                                             @Nonnull
                                                             java.lang.String variableKey,
                                                             @Nonnull
                                                             java.lang.String userId,
                                                             @Nonnull
                                                             java.util.Map<java.lang.String,?> attributes)

Get the Boolean value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

The Boolean value of the boolean single variable feature. Null if the feature or variable could not be found.

getFeatureVariableDouble

@Nullable
public java.lang.Double getFeatureVariableDouble(@Nonnull
                                                           java.lang.String featureKey,
                                                           @Nonnull
                                                           java.lang.String variableKey,
                                                           @Nonnull
                                                           java.lang.String userId)

Get the Double value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

Returns:

The Double value of the double single variable feature. Null if the feature or variable could not be found.

getFeatureVariableDouble

@Nullable
public java.lang.Double getFeatureVariableDouble(@Nonnull
                                                           java.lang.String featureKey,
                                                           @Nonnull
                                                           java.lang.String variableKey,
                                                           @Nonnull
                                                           java.lang.String userId,
                                                           @Nonnull
                                                           java.util.Map<java.lang.String,?> attributes)

Get the Double value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

The Double value of the double single variable feature. Null if the feature or variable could not be found.

getFeatureVariableInteger

@Nullable
public java.lang.Integer getFeatureVariableInteger(@Nonnull
                                                             java.lang.String featureKey,
                                                             @Nonnull
                                                             java.lang.String variableKey,
                                                             @Nonnull
                                                             java.lang.String userId)

Get the Integer value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

Returns:

The Integer value of the integer single variable feature. Null if the feature or variable could not be found.

getFeatureVariableInteger

@Nullable
public java.lang.Integer getFeatureVariableInteger(@Nonnull
                                                             java.lang.String featureKey,
                                                             @Nonnull
                                                             java.lang.String variableKey,
                                                             @Nonnull
                                                             java.lang.String userId,
                                                             @Nonnull
                                                             java.util.Map<java.lang.String,?> attributes)

Get the Integer value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

The Integer value of the integer single variable feature. Null if the feature or variable could not be found.

getFeatureVariableString

@Nullable
public java.lang.String getFeatureVariableString(@Nonnull
                                                           java.lang.String featureKey,
                                                           @Nonnull
                                                           java.lang.String variableKey,
                                                           @Nonnull
                                                           java.lang.String userId)

Get the String value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

Returns:

The String value of the string single variable feature. Null if the feature or variable could not be found.

getFeatureVariableString

@Nullable
public java.lang.String getFeatureVariableString(@Nonnull
                                                           java.lang.String featureKey,
                                                           @Nonnull
                                                           java.lang.String variableKey,
                                                           @Nonnull
                                                           java.lang.String userId,
                                                           @Nonnull
                                                           java.util.Map<java.lang.String,?> attributes)

Get the String value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

The String value of the string single variable feature. Null if the feature or variable could not be found.

getFeatureVariableJSON

@Nullable
public OptimizelyJSON getFeatureVariableJSON(@Nonnull
                                                       java.lang.String featureKey,
                                                       @Nonnull
                                                       java.lang.String variableKey,
                                                       @Nonnull
                                                       java.lang.String userId)

Get the JSON value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

Returns:

An OptimizelyJSON instance for the JSON variable value. Null if the feature or variable could not be found.

getFeatureVariableJSON

@Nullable
public OptimizelyJSON getFeatureVariableJSON(@Nonnull
                                                       java.lang.String featureKey,
                                                       @Nonnull
                                                       java.lang.String variableKey,
                                                       @Nonnull
                                                       java.lang.String userId,
                                                       @Nonnull
                                                       java.util.Map<java.lang.String,?> attributes)

Get the JSON value of the specified variable in the feature.

Parameters:

featureKey - The unique key of the feature.

variableKey - The unique key of the variable.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

An OptimizelyJSON instance for the JSON variable value. Null if the feature or variable could not be found.

getAllFeatureVariables

@Nullable
public OptimizelyJSON getAllFeatureVariables(@Nonnull
                                                       java.lang.String featureKey,
                                                       @Nonnull
                                                       java.lang.String userId)

Get the values of all variables in the feature.

Parameters:

featureKey - The unique key of the feature.

userId - The ID of the user.

Returns:

An OptimizelyJSON instance for all variable values. Null if the feature could not be found.

getAllFeatureVariables

@Nullable
public OptimizelyJSON getAllFeatureVariables(@Nonnull
                                                       java.lang.String featureKey,
                                                       @Nonnull
                                                       java.lang.String userId,
                                                       @Nonnull
                                                       java.util.Map<java.lang.String,?> attributes)

Get the values of all variables in the feature.

Parameters:

featureKey - The unique key of the feature.

userId - The ID of the user.

attributes - The user's attributes.

Returns:

An OptimizelyJSON instance for all variable values. Null if the feature could not be found.

getEnabledFeatures

public java.util.List<java.lang.String> getEnabledFeatures(@Nonnull
                                                           java.lang.String userId,
                                                           @Nonnull
                                                           java.util.Map<java.lang.String,?> attributes)

Get the list of features that are enabled for the user. TODO revisit this method. Calling this as-is can dramatically increase visitor impression counts.

Parameters:

userId - The ID of the user.

attributes - The user's attributes.

Returns:

List of the feature keys that are enabled for the user if the userId is empty it will return Empty List.

getVariation

@Nullable
public Variation getVariation(@Nonnull
                                        Experiment experiment,
                                        @Nonnull
                                        java.lang.String userId)
                                 throws UnknownExperimentException

Throws:

UnknownExperimentException

getVariation

@Nullable
public Variation getVariation(@Nonnull
                                        Experiment experiment,
                                        @Nonnull
                                        java.lang.String userId,
                                        @Nonnull
                                        java.util.Map<java.lang.String,?> attributes)
                                 throws UnknownExperimentException

Throws:

UnknownExperimentException

getVariation

@Nullable
public Variation getVariation(@Nonnull
                                        java.lang.String experimentKey,
                                        @Nonnull
                                        java.lang.String userId)
                                 throws UnknownExperimentException

Throws:

UnknownExperimentException

getVariation

@Nullable
public Variation getVariation(@Nonnull
                                        java.lang.String experimentKey,
                                        @Nonnull
                                        java.lang.String userId,
                                        @Nonnull
                                        java.util.Map<java.lang.String,?> attributes)

setForcedVariation

public boolean setForcedVariation(@Nonnull
                                  java.lang.String experimentKey,
                                  @Nonnull
                                  java.lang.String userId,
                                  @Nullable
                                  java.lang.String variationKey)

Force a user into a variation for a given experiment. The forced variation value does not persist across application launches. If the experiment key is not in the project file, this call fails and returns false. If the variationKey is not in the experiment, this call fails.

Parameters:

experimentKey - The key for the experiment.

userId - The user ID to be used for bucketing.

variationKey - The variation key to force the user into. If the variation key is null then the forcedVariation for that experiment is removed.

Returns:

boolean A boolean value that indicates if the set completed successfully.

getForcedVariation

@Nullable
public Variation getForcedVariation(@Nonnull
                                              java.lang.String experimentKey,
                                              @Nonnull
                                              java.lang.String userId)

Gets the forced variation for a given user and experiment. This method just calls into the DecisionService.getForcedVariation(Experiment, String) method of the same signature.

Parameters:

experimentKey - The key for the experiment.

userId - The user ID to be used for bucketing.

Returns:

The variation the user was bucketed into. This value can be null if the forced variation fails.

getProjectConfig

@Nullable
public ProjectConfig getProjectConfig()

Returns:

the current ProjectConfig instance.

getUserProfileService

@Nullable
public UserProfileService getUserProfileService()

getOptimizelyConfig

public OptimizelyConfig getOptimizelyConfig()

Get OptimizelyConfig containing experiments and features map

Returns:

OptimizelyConfig

createUserContext

public OptimizelyUserContext createUserContext(@Nonnull
                                               java.lang.String userId,
                                               @Nonnull
                                               java.util.Map<java.lang.String,?> attributes)

Create a context of the user for which decision APIs will be called. A user context will be created successfully even when the SDK is not fully configured yet.

Parameters:

userId - The user ID to be used for bucketing.

attributes: - A map of attribute names to current user attribute values.

Returns:

An OptimizelyUserContext associated with this OptimizelyClient.

createUserContext

public OptimizelyUserContext createUserContext(@Nonnull
                                               java.lang.String userId)

getNotificationCenter

public NotificationCenter getNotificationCenter()

addDecisionNotificationHandler

public int addDecisionNotificationHandler(NotificationHandler<DecisionNotification> handler)

Convenience method for adding DecisionNotification Handlers

Parameters:

handler - DicisionNotification handler

Returns:

A handler Id (greater than 0 if succeeded)

addTrackNotificationHandler

public int addTrackNotificationHandler(NotificationHandler<TrackNotification> handler)

Convenience method for adding TrackNotification Handlers

Parameters:

handler - TrackNotification handler

Returns:

A handler Id (greater than 0 if succeeded)

addUpdateConfigNotificationHandler

public int addUpdateConfigNotificationHandler(NotificationHandler<UpdateConfigNotification> handler)

Convenience method for adding UpdateConfigNotification Handlers

Parameters:

handler - UpdateConfigNotification handler

Returns:

A handler Id (greater than 0 if succeeded)

addLogEventNotificationHandler

public int addLogEventNotificationHandler(NotificationHandler<LogEvent> handler)

Convenience method for adding LogEvent Notification Handlers

Parameters:

handler - NotificationHandler handler

Returns:

A handler Id (greater than 0 if succeeded)

addNotificationHandler

public <T> int addNotificationHandler(java.lang.Class<T> clazz,
                                      NotificationHandler<T> handler)

Convenience method for adding NotificationHandlers

Type Parameters:

T - This is the type parameter

Parameters:

clazz - The class of NotificationHandler

handler - NotificationHandler handler

Returns:

A handler Id (greater than 0 if succeeded)

fetchQualifiedSegments

public java.util.List<java.lang.String> fetchQualifiedSegments(java.lang.String userId,
                                                               @Nonnull
                                                               java.util.List<ODPSegmentOption> segmentOptions)

fetchQualifiedSegments

public void fetchQualifiedSegments(java.lang.String userId,
                                   ODPSegmentManager.ODPSegmentFetchCallback callback,
                                   java.util.List<ODPSegmentOption> segmentOptions)

getODPManager

@Nullable
public ODPManager getODPManager()

sendODPEvent

public void sendODPEvent(@Nullable
                         java.lang.String type,
                         @Nonnull
                         java.lang.String action,
                         @Nullable
                         java.util.Map<java.lang.String,java.lang.String> identifiers,
                         @Nullable
                         java.util.Map<java.lang.String,java.lang.Object> data)

Send an event to the ODP server.

Parameters:

type - the event type (default = "fullstack").

action - the event action name.

identifiers - a dictionary for identifiers. The caller must provide at least one key-value pair unless non-empty common identifiers have been set already with ODPManager.Builder#withUserCommonIdentifiers(Map) .

data - a dictionary for associated data. The default event data will be added to this data before sending to the ODP server.

identifyUser

public void identifyUser(@Nonnull
                         java.lang.String userId)

builder

@Deprecated
public static Optimizely.Builder builder(@Nonnull
                                                     java.lang.String datafile,
                                                     @Nonnull
                                                     EventHandler eventHandler)

Deprecated.

This overloaded factory method is deprecated in favor of pure builder methods. Please use builder() along with Optimizely.Builder.withDatafile(java.lang.String) and Optimizely.Builder.withEventHandler(com.optimizely.ab.event.EventHandler) respectively. Example:

     Optimizely optimizely = Optimizely.builder()
         .withDatafile(datafile)
         .withEventHandler(eventHandler)
         .build();
 

Parameters:

datafile - A datafile

eventHandler - An EventHandler

Returns:

An Optimizely builder

builder

public static Optimizely.Builder builder()