Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Initialize the Ruby SDK

How to initialize the Optimizely Feature Experimentation Ruby SDK in your application.

Use the new method to initialize the Ruby SDK and instantiate an instance of the Optimizely client class that exposes API methods like Decide methods. Each client corresponds to the datafile representing the state of a project for a certain environment.

Version

5.0.0

Description

The SDK provides a default implementation, but you may want to override the optional parameters for your production environments. For example, you can set up an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

Parameters

The table below lists the required and optional parameters for the new method:

ParameterTypeDescription
datafile
optional
stringThe JSON string representing the project.
event_dispatcher
optional
EventDispatcherAn event handler to manage network calls.
logger
optional
LoggerA logger implementation to log issues.
error_handler
optional
ErrorHandlerAn error handler object to handle errors.
user_profile_service
optional
UserProfileServiceA user profile service.
skip_json_validation
optional
booleanSpecifies whether the JSON should be validated. Set to true to skip JSON validation on the schema, or false to perform validation.
access_token
optional
string(Server-side only) An access token for Optimizely Feature Experimentation SDKs (in combination with an SDK key) to fetch the datafile from an authenticated endpoint. Find your datafile access token in the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token.
default_decide_options
optional
ArrayArrary of OptimizelyDecideOption enums. Constructing the Optimizely client with this parameter sets default decide options that apply to all Decide calls made during the lifetime of the Optimizely client. Passing options to individual Decide methods overrides these defaults.
For details on decide options, see OptimizelyDecideOption.
event_processor_options
optional
HashHash of event processor options passed to the default event processor. See BatchEventProcessor for more details.
settings
optional
OptimizelySdkSettingsInstance of OptimizelySdkSettings for configuring Advanced Audience Targeting.

The Ruby SDK enables the Advanced Audience Targeting methods by default. But, the methods do nothing unless you have enabled and configured the Advanced Audience Targeting integration .

To optionally disable Advanced Audience Targeting, see OdpManager.

Returns

Instantiates an instance of the Optimizely Feature Experimentation class.

Examples

Optimizely Feature Experimentation provides out-of-the-box functionality to dynamically manage datafiles (configuration files) on either the client or the server. The Ruby SDK provides default implementations of an ProjectConfigManager. The package also includes a factory class, OptimizelyFactory, which you can use to instantiate the Optimizely Feature Experimentation SDK with the default configuration of HttpProjectConfigManager.

Whenever the experiment configuration changes, the SDK uses automatic datafile management (ADM) to handle the change for you. You can provide either sdk_key,datafile, or both.

  • Initializing with the SDK key only polls for datafile changes in the background at regular intervals.
  • Initializing wit the datafile only does not poll for datafile changes in the background.
  • Initializing with the SDK key and datafile uses the given datafile to poll for changes in the background.

Instantiate using SDK Key (recommended)

In the Ruby SDK, you only need to pass the SDK key value to instantiate a client. Whenever the experiment configuration changes, the SDK handles the change for you.

Include sdk_key as a string property in the options object you pass to the default_instance method.

When you provide the sdk_key, the SDK instance downloads the datafile associated with that sdk_key. When the download completes, the SDK instance updates itself to use the downloaded datafile.

Basic example

The following code example shows basic Ruby ADM usage.

require 'optimizely'
require 'optimizely/optimizely_factory'

# Initialize an Optimizely client
optimizely_instance = Optimizely::Project.new(sdk_key: 'put_your_sdk_key_here')

Advanced examples

Here is a code example showing advanced configuration for Ruby ADM. See the sections below for advanced configuration properties.

This advanced example shows how to construct the individual components directly to override various configurations. This gives you full control over using implementations.

require 'optimizely'
require 'optimizely/optimizely_factory'
require 'optimizely/config_manager/http_project_config_manager'

sdk_key = '<YOUR_SDK_KEY>'
http_project_config_manager = Optimizely::HTTPProjectConfigManager.new(
  sdk_key: sdk_key,
  polling_interval: 10
)

optimizely_instance = Optimizely::OptimizelyFactory.default_instance_with_config_manager(http_project_config_manager)
# Starting in 5.0+ the client constructor uses keyword arguments
sdk_key = 'AWDj34sdlfklsdfks'
optimizely_client = Optimizely::Project.new(sdk_key: sdk_key, logger: logger)

# Starting in 3.2+ there are convienence factory methods for instantiating clients
require 'optimizely/optimizely_factory'

# Instantiate with just the SDK key. The SDK will pull the datafile remotely.
optimizely_client = Optimizely::OptimizelyFactory.default_instance(sdk_key)

# You can optionally instantiate with a hard-coded datafile as well 
datafile = '{ revision: "42" }'
optimizely_client = Optimizely::OptimizelyFactory.default_instance(sdk_key, datafile)

Required SDK key with other optional arguments

require 'optimizely'

optimizely_instance = Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  datafile: datafile,
  event_dispatcher: event_dispatcher,
  logger: logger,
  error_handler: error_handler,
  skip_json_validation: skip_json_validation,
  user_profile_service: user_profile_service,
  config_manager: config_manager,
  notification_center: notification_center,
  event_processor: event_processor,
  default_decide_options: default_decide_options,
  event_processor_options: event_processor_options,
  settings: settings
)

# Prior to 5.0
optimizely_instance = Optimizely::OptimizelyFactory.custom_instance(
  'put_your_sdk_key_here',
  datafile,
  event_dispatcher,
  logger,
  error_handler,
  skip_json_validation,
  user_profile_service,
  config_manager,
  notification_center,
  settings
)

Instantiate using datafile

You can also instantiate with a hard-coded datafile. If you do not pass in an SDK key, the Optimizely Client does not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client.

To instantiate a client for simple applications, provide a datafile specifying the project configuration for a given environment. For most advanced implementations, you should customize the logger or error handler for your specific requirements.

# Instantiate with both SDK key and datafile. The SDK will use the hard-coded datafile and will start polling for new datafiles remotely.
datafile = '{ revision: "42" }'
optimizely_client = Optimizely::Project.new(
  sdk_key: sdk_key, 
  datafile: datafile
  error_handler: error_handler,
  logger: logger
)

# Prior to 5.0 you can use the OptimizelyFactory for a similar experience
optimizely_client = Optimizely::OptimizelyFactory.default_instance(sdk_key, datafile)

# You can also customize the various components of the SDK (i.e. logger, error handler)
optimizely_client = Optimizely::OptimizelyFactory.custom_instance(
  sdk_key, 
  datafile
  # event_dispatcher
  # logger
)

# Prior to 3.2 you can instantiate with just a JSON datafile string
optimizely_client = Optimizely::Project.new(datafile)

Initialize in a Rails application

To use the SDK in a Rails application, you can configure the SDK using the snippet below:

# initialize a client
Rails.configuration.optimizely_client = Optimizely::OptimizelyFactory.default_instance('SDK_KEY_HERE')

# you can access the client in your Rails controllers from the application config
Rails.application.config.optimizely_client

The SDK spawns multiple threads when initialized. These threads have infinite loops for fetching the datafile, as well as batching and dispatching events in the background. When using in a web server that spawn multiple child processes, you need to initialize the SDK after those child processes or workers have been spawned:

Unicorn

after_fork do |server, worker|
   Rails.configuration.optimizely_client = Optimizely::OptimizelyFactory.default_instance('SDK_KEY_HERE')
end

Puma

on_worker_boot do
   Rails.configuration.optimizely_client = Optimizely::OptimizelyFactory.default_instance('SDK_KEY_HERE')
end

Passenger

PhusionPassenger.on_event(:starting_worker_process) do |forked|
 if forked
   Rails.configuration.optimizely_client = Optimizely::OptimizelyFactory.default_instance('SDK_KEY_HERE')
 end
end

HttpProjectConfigManager

HttpProjectConfigManager is an implementation of ProjectConfigManager interface which polls for the datafile and updates DatafileProjectConfig based on an update interval. To maintain the asynchronous nature of requests, it uses an AsyncScheduler which makes an HTTP GET request to the configured URL to asynchronously download the project datafile and initialize an instance of the DatafileProjectConfig.

By default, HttpProjectConfigManager blocks until the first successful datafile retrieval, up to a configurable blocking timeout. Set the frequency of the polling method and the blocking timeout when initializing the config manager.

http_project_config_manager = Optimizely::HTTPProjectConfigManager.new(
  datafile: datafile
  sdk_key: sdk_key,
  polling_interval: 10,
  blocking_timeout: 15
)

SDK key

The SDK key composes the outbound HTTP request to the default datafile location on the Optimizely CDN.

Polling interval

The polling interval specifies a fixed delay between consecutive HTTP requests for the datafile.

Initial datafile

You can provide an initial datafile while initializing the Config Manager to bootstrap the ProjectConfigManager so that it can be used immediately without blocking execution. The initial datafile also serves as a fallback datafile if HTTP connection cannot be established. This is useful in mobile environments, where internet connectivity is not guaranteed.

The SDK discards the initial datafile after the first successful datafile poll.

Advanced configurations

You can use the following properties to customize the HttpProjectConfigManager configuration.

PropertyDefault valueDescription
datafilenullInitial datafile, typically sourced from a local cached source.
urlnullURL override location used to specify custom HTTP source for the datafile.
url_templatenullParameterized datafile URL by SDK key.
polling_interval5 minutesFixed delay between fetches for the datafile. Valid duration is between 1 and 2592000 seconds. Otherwise, default is used.
blocking_timeout15 secondsThe blocking timeout period is used to specify a maximum time to wait for initial bootstrapping. Valid blocking timeout period is between 1 and 2592000 seconds. Otherwise, default is used.
sdk_keynullOptimizely Feature Experimentation project SDK key; required unless source URL is overridden.
auto_updatetrueBoolean flag to specify if callback for datafile polling needs to execute infinitely or only once.
start_by_defaulttrueBoolean flag to specify if datafile polling should start right away, as soon as the HTTPConfigManager is initialized.

Update config notifications

The SDK triggers a notification signal when fetching a new datafile or updating a corresponding project. To subscribe to these notifications, use method notification_center.add_notification_listener().

notification_center.add_notification_listener(Optimizely::NotificationCenter::NOTIFICATION_TYPES[:OPTIMIZELY_CONFIG_UPDATE], @callback
)

OptimizelyFactory

OptimizelyFactory provides basic utility to instantiate the Optimizely Feature Experimentation SDK with a minimal number of configuration options.

OptimizelyFactory does not capture all configuration and initialization options. For more use cases, build the resources with their constructors.

You must provide the SDK key at runtime, directly using the factory method:

optimizely_instance = Optimizely::OptimizelyFactory.default_instance(
  '123456'
)

Enable JSON schema validation

Skipping JSON schema validation enhances performance during instantiation. In the Ruby SDK, you can control whether to validate the JSON schema of the datafile when instantiating the client. This example shows how to skip JSON schema validation:

# Skip JSON schema validation (SDK versions 0.1.1 and above)
optimizely_client = Optimizely::Project.new(datafile: datafile, skip_json_validation: true)

OdpManager

👍

Beta

The Advanced Audience Targeting integration are in beta. Apply on the Optimizely beta signup page or contact your Customer Success Manager.

OdpManager contains the logic supporting the Advanced Audience Targeting-related features in Optimizely Feature Experimentation, including audience segments.

The Ruby SDK enables the Advanced Audience Targeting methods by default. But, the methods do nothing unless you have enabled and configured the Advanced Audience Targeting integration.

If necessary, to disable Advanced Audience Targeting altogether, set disable_odp: true. See the following sample code for more information.

OdpSegmentManager

This module provides an interface to the remote ODP server for audience segment mappings.

It fetches all qualified segments for the given user context and returns them as a string array in the completion handler.

It also manages a segment's cache shared for all user contexts. Because the cache is in memory (not persistent), rebooting the device or terminating the app resets it.

OdpEventManager

This module provides an interface to the remote ODP server for events.

It queues all pending events (persistent) and sends them (in batches of up to 10) to the ODP server when all resources are available, including network connection and ODP public key (in the SDK's datafile).

📘

Note

The Ruby SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors) but does not guarantee completion.

require 'optimizely'
require 'optimizely/optimizely_factory'

event_manager = Optimizely::OdpEventManager.new()

segments_cache = YourCustomCache.new()
segments_manager = Optimizely::OdpSegmentManager.new(segments_cache)

sdk_settings = Optimizely::Helpers::OptimizelySdkSettings.new(
  disable_odp: false, #set to true to disable Advanced Audience Targeting
  segments_cache_size: 10_000,
  segments_cache_timeout_in_secs: 600,
  odp_segments_cache: segments_cache,
  odp_segment_manager: segments_manager,
  odp_event_manager: event_manager,
  odp_segment_request_timeout: 10,
  odp_event_request_timeout: 10,
  odp_event_flush_interval: 1
)
optimizely = Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  settings: sdk_settings
)

Customize OdpEventApiManager

OdpEventApiManager is an interface, and its implementation requires the user to provide the functionality of the following methods:

require 'optimizely'
require 'optimizely/optimizely_factory'

event_api_manager = Optimizely::OdpEventApiManager.new(timeout: 10)
odp_event_manager = Optimizely::OdpEventManager.new(api_manager: event_api_manager, flush_interval: 1)
sdk_settings = Optimizely::Helpers::OptimizelySdkSettings.new(odp_event_manager: odp_event_manager)

optimizely = Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  settings: sdk_settings
)

Customize OdpEventManager

You can provide custom queue_size and flush_interval in the constructor. If set to zero, batch_size is 1; otherwise, batch_size is the default of 10.

require 'optimizely'
require 'optimizely/optimizely_factory'

event_api_manager = Optimizely::OdpEventApiManager.new(timeout: 10)
odp_event_manager = Optimizely::OdpEventManager.new(api_manager: event_api_manager, flush_interval: 1)
sdk_settings = Optimizely::Helpers::OptimizelySdkSettings.new(odp_event_manager: odp_event_manager)

optimizely = Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  settings: sdk_settings
)

Customize OdpSegmentManager

By default, OdpSegmentManager uses the LRUCache.

require 'optimizely'
require 'optimizely/optimizely_factory'

cache = Optimizely::LRUCache.new(10_000, 600)

odp_segment_manager = Optimizely::OdpSegmentManager.new(cache, 10)
sdk_settings = Optimizely::Helpers::OptimizelySdkSettings.new(odp_segment_manager: odp_segment_manager)

optimizely = Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  settings: sdk_settings
)

Custom cache

You can provide a custom cache to store the fetch_qualified_segments results by implementing the following interface:

class OptimizelySegmentsCache
  def save(key, value); end
  def lookup(key); end
  def reset; end
end

Here is an example of custom cache implementation:

class CustomCache
  def initialize
    @mutex = Mutex.new
    @map = {}
  end

  def save(key, value)
    @mutex.synchronize { @map[key] = value }
    nil
  end

  def lookup(key)
    @mutex.synchronize { @map[key] }
  end

  def reset
    @mutex.synchronize { @map.clear }
    nil
  end
end

Pass this CustomCache within OptimizelySdkSettings when instantiating the Optimizely client:

require 'optimizely/optimizely_factory'

segments_cache = CustomCache.new
sdk_settings = Optimizely::Helpers::OptimizelySdkSettings.new(odp_segments_cache: segments_cache)
Optimizely::Project.new(
  sdk_key: 'put_your_sdk_key_here',
  settings: sdk_settings
)

Use authenticated datafiles in secure environments

You can fetch the Optimizely datafile from an authenticated endpoint using a server-side (only) Optimizely Feature Experimentation SDK, like the Ruby SDK.

To use an authenticated datafile, download your environment's access token from the app at Settings > Environment. Select your secure environment, and copy the Datafile access token The example below shows how to initialize the Optimizely client using an access token and sdk_key, enabling the client to fetch the authenticated datafile and complete initialization.

# fetch the datafile from an authenticated endpoint
require 'optimizely'

sdk_key = '<YOUR_SDK_KEY>'
datafile_access_token = '<YOUR_DATAFILE_ACCESS_TOKEN>'

config_manager = Optimizely::HTTPProjectConfigManager.new(
  sdk_key: sdk_key,
  datafile_access_token: datafile_access_token
)

Optimizely::Project.new(config_manager:, config_manager)

Source files

The language and platform source files containing the implementation for Ruby are available on GitHub.