Ruby SDK

This guide provides detailed information about our Ruby SDK. All of our SDKs are open source. Go to our Ruby SDK GitHub repository to learn more.

Initialization

1. Import the SDK into your project

gem install splitclient-rb -v '~> 8.4.0'

gem install splitclient-rb -v '~> 8.4.0'

2. Instantiate the SDK and create a new Split client

When the SDK is instantiated, it starts background tasks to update an in-memory cache with small amounts of data fetched from Split servers. This process can take up to a few hundred milliseconds, depending on the size of data. If the SDK is asked to evaluate which treatment to show to a customer for a specific feature flag while its in this intermediate state, it may not have the data necessary to run the evaluation. In this case, the SDK does not fail, rather, it returns the control treatment.

To make sure the SDK is properly loaded before asking it for a treatment, block it until the SDK is ready. You can do this by using the block_until_ready method of the Split Client (or Manager) as part of the instantiation process of the SDK as shown below. Do this as a part of the startup sequence of your application.

We recommend instantiating the Split factory once as a singleton and reusing it throughout your application.

Configure the SDK with the SDK key for the Split environment that you would like to access. The SDK key is available in the Split user interface, on your Admin settings page, API keys section. Select a server-side SDK API key. See API keys to learn more.

require 'splitclient-rb'

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY')
split_client = split_factory.client

begin
  split_client.block_until_ready
rescue SplitIoClient::SDKBlockerTimeoutExpiredException
  puts 'SDK is not ready. Decide whether to continue or abort execution'
end

Configure the SDK for use with Rails

Our SDK is compatible with Ruby on Rails. There are a few extra steps for the initialization. You can configure the SDK to work with Rails with the code snippet below.

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY')
Rails.configuration.split_client = split_factory.client

To access the SDK client in your controllers, use the code snippet below:

Rails.application.config.split_client

Now you can start asking the SDK to evaluate treatments for your customers.

SDK Server Compatibility

The Split Ruby SDK has been tested as a standalone app using the following web servers:

• Puma
• Passenger
• Unicorn

For other setups, contact support@split.io.

Unicorn and Puma in cluster mode

Note: This is only applicable when using "memory storage".

During the start of your application, the SDK spawns multiple threads. Each thread has an infinite loop inside, which is used to fetch feature flags/segments or send impressions/events to the Split service continuously. When using Unicorn or Puma in cluster mode (i.e. with workers > 0) the application server will spawn multiple child processes, but they won't recreate the threads that existed in the parent process. So, if your application is running in Unicorn or Puma in cluster mode you need to make two small extra steps.

For both servers, you need to have the following line in your config/initializers/splitclient.rb:

Rails.configuration.split_factory = factory

Find below the specific setup for each one:

Unicorn

If you’re using Unicorn in cluster mode, you’ll need to include these lines in your Unicorn config (likely config/unicorn.rb):

before_fork do |server, worker|
  # keep your existing before_fork code if any
  Rails.configuration.split_factory.stop!
end
after_fork do |server, worker|
  # keep your existing after_fork code if any
  Rails.configuration.split_factory.resume!
end

Puma

If using Puma in cluster mode, add these lines to your Puma config (likely config/puma.rb):

before_fork do
  # keep your existing before_fork code if any
  Rails.configuration.split_factory.stop!
end
on_worker_boot do
  # keep your existing on_worker_boot code if any
  Rails.configuration.split_factory.resume!
end

By doing the above, the SDK recreates the threads for each new worker and prevents the master process (that doesn't handle requests) from needlessly querying the Split service.

Using the SDK

Basic use

After you instantiate the SDK client, you can start using the get_Treatment method of the SDK client to decide what version of your features your customers are served. The method requires the FEATURE_FLAG_NAME attribute that you want to ask for a treatment and a unique KEY attribute that corresponds to the end user that you want to serve the feature to.

From there, you simply need to use an if-else-if block as shown below and insert the code for the different treatments that you defined in the Split user interface. Remember the final else branch in your code to handle the client returning the control treatment.

# The key here represents the ID of the user, account, etc. you're trying to evaluate a treatment for
treatment = split_client.get_treatment('KEY', 'FEATURE_FLAG_NAME');

if treatment == 'on'
  # insert code here to show on treatment
elsif treatment == 'off'
  # insert code here to show off treatment
else
  # insert your control treatment code here
end

Attribute syntax

To target based on custom attributes, the SDK's get_treatment method needs to be passed an attribute map at runtime.

In the example below, we are rolling out a feature flag to users. The provided attributes plan_type, registered_date, permissions, paying_customer, and deal_size are passed to the get_treatment call. These attributes are compared and evaluated against the attributes used in the rollout plan as defined in the Split user interface to decide whether to show the on or off treatment to this account.

The get_treatment method supports five types of attributes: strings, numbers, dates, booleans, and sets. The proper data type and syntax for each are:

• Strings: Use type String.
• Numbers: Use type long or int.
• Dates: Express the value as seconds since epoch and as objects of class DateTime.
• Booleans: Use type Boolean.
• Sets: Use type List<string>.

attributes = {}
attributes[:deal_size] = 10000
attributes[:registered_date] = Time.now.to_i # any time as seconds since epoch
attributes[:plan_type] = "growth"
attributes[:permissions] = ['read', 'write']
attributes[:paying_customer] = true

treatment = split_client.get_treatment("KEY",
                                       "FEATURE_FLAG_NAME",
                                       attributes)

if treatment == 'on'
    # insert on code here
 elsif treatment == 'off'
    # insert off code here
 else
    # insert control code here
end

Multiple evaluations at once

In some instances, you may want to evaluate treatments for multiple feature flag at once. Use the different variations of get_treatments method from the split client to do this.

• get_treatments': Pass a list of the feature flag names you want treatments for.
• get_treatments_by_flag_set: Evaluate all flags that are part of the provided set name and are cached on the SDK instance.
• get_treatments_by_flag_sets: Evaluate all flags that are part of the provided set names and are cached on the SDK instance.

attributes = {}
split_client.get_treatments('key', ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'], attributes)

attributes = {}
treatments = split.get_treatments_by_flag_set('key', 'backend', attributes)

attributes = {}
treatments = split.get_treatments_by_flag_sets('key', ['backend', 'server_side'], attributes)

You can also use the Split Manager if you want to get all of your treatments at once.

Get Treatments with Configurations

To leverage dynamic configurations with your treatments, you should use the get_treatment_with_config method.

This method will return an object containing the treatment and associated configuration.

The config element will be a stringified version of the configuration JSON defined in the Split user interface. If there are no configs defined for a treatment, the SDK returns None for the config parameter.

This method takes the exact same set of arguments as the standard get_treatment method. See below for examples on proper usage:

result = client.get_treatment_with_config('key', 'new_boxes', attributes)
configs = JSON.parse(result[:config])
treatment = result[:treatment]

If you need to get multiple evaluations at once, you can also use the get_treatments_with_config methods.
These methods take the exact same arguments as the get_treatments methods but return a mapping of feature flag names to SplitResult objects instead of strings. Example usage below.

feature_flag_names = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2']
feature_flag_results = client.get_treatments_with_config('KEY', feature_flag_names)

 # feature_flag_results will have the following format:
 # {
 #   'FEATURE_FLAG_NAME_1': ('on', '{"color": "red"}'),
 #   'FEATURE_FLAG_NAME_2': ('v2', '{"copy": "better copy"}')
 # }

attributes = {}
result = split.get_treatments_with_config_by_flag_set('key', 'backend', attributes)
result.each do |feature_flag, treatment_with_config|
 configs = JSON.parse(treatment_with_config[:config])
 treatment = treatment_with_config[:treatment]
 puts "Feature: #{feature_flag}, Treatment: #{treatment}, Config: #{configs}"
end

attributes = {}
result = split.get_treatments_with_config_by_flag_sets('key', ['backend', 'server_side'], attributes)
result.each do |feature_flag, treatment_with_config|
 configs = JSON.parse(treatment_with_config[:config])
 treatment = treatment_with_config[:treatment]
 puts "Feature: #{feature_flag}, Treatment: #{treatment}, Config: #{configs}"
end

Shutdown

Call the .destroy method before letting a process using the SDK exit, as this method gracefully shuts down the Split SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions.

client.destroy

Note: Within multi-threaded setups like using Ruby with Rails and Puma, to fully destroy the factory, you need to set it to nil as follows: Rails.configuration.split_factory = nil

Track

Use the track method to record any actions your customers perform. Each action is known as an event and corresponds to an event type. Calling track through one of our SDKs or via the API is the first step to getting experimentation data into Split and allows you to measure the impact of your feature flags on your users’ actions and metrics.

Learn more about using track events in feature flags.

In the examples below, you can see that the .track() method can take up to four arguments. The proper data type and syntax for each are:

• key: The key variable used in the get_treatment call and firing this track event. The expected data type is String.
• TRAFFIC_TYPE: The traffic type of the key in the track call. The expected data type is String. You can only pass values that match the names of traffic types that you have defined in your instance of Split.
• EVENT_TYPE: The event type that this event should correspond to. The expected data type is String. Full requirements on this argument are:
  • Contains 63 characters or fewer.
  • Starts with a letter or number.
  • Contains only letters, numbers, hyphen, underscore, or period.
  • This is the regular expression we use to validate the value: [a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}
• VALUE: (Optional) The value used in creating the metric. This field can be sent in as nil or 0 if you intend to only use the count function when creating a metric. The expected data type is Integer or Float.
• PROPERTIES: (Optional) A Hash of key value pairs that can be used to filter your metrics. Learn more about event property capture in the Events guide. Split currently supports three types of properties: strings, numbers, and booleans.

The track method returns a boolean value of true or false to indicate whether or not the SDK successfully queued the event to be sent back to Split's servers on the next event post. The SDK returns false if the current queue size is equal to the config set by events_queue_size or if an incorrect input to the track method is provided.

In the case that a bad input has been provided, refer to the Events guide for more information about our SDK's expected behavior.

# If you would like to send an event without a value
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE')

# Example
track_event = split_client.track('john@doe.com', 'user', 'page_load_time')

# If you would like to associate a value to an event
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', VALUE)

# Example
track_event = split_client.track('john@doe.com', 'user', 'page_load_time', 83.334)

# If you would like to associate just properties to an event
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', nil, { PROPERTIES })

# If you would like to associate a value and properties to an event
track_event = split_client.track('KEY', 'TRAFFIC_TYPE', 'EVENT_TYPE', VALUE, { PROPERTIES })

# Example
properties = {
  package: 'premium',
  admin: true,
  discount: 50
}

track_event = split_client.track('john@doe.com', 'user', 'page_load_time', nil, properties)

Configuration

The SDK has a number of knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override the value while instantiating the SDK. The parameters available for configuration are described below:

options = {connection_timeout: 10,
           read_timeout: 5,
           impressions_refresh_rate: 360,
           logger: Logger.new('logfile.log')}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Sharing state: Redis integration

Configuring this Redis integration section is optional for most setups. Read the information below to determine if it might be useful for your project.

By default, the Split client stores the state it needs to compute treatments (rollout plans, segments, and so on) in memory. As a result, it is easy to get set up with Split by instantiating a client and starting to use it. Configuring this Redis integration section is optional for most setups.

This simplicity hides one important detail that is worth exploring. Because each Split client downloads and stores state separately, a change in a feature flag is picked up by every client on its own schedule. Thus, if a customer issues back-to-back requests that are served by two different machines behind a load balancer, the customer can see different treatments for the same feature flag because one Split client may not have picked up the latest change. This drift in clients is natural and usually ignorable as long as each client sets an aggressive value for features_refresh_rate and segments_refresh_rate. You can learn more about setting these rates in the Configuration section.

However, if your application requires a total guarantee that Split clients across your entire infrastructure pick up a change in a feature flag at the exact same time, the only way to ensure that is to externalize the state of the Split client in a data store hosted on your infrastructure.

We currently support Redis for this external data store.

To use the Ruby SDK with Redis, set up the Split Synchronizer and instantiate the SDK in consumer mode.

Split Synchronizer

Follow the steps in our Split Synchronizer document to get everything set to sync data to your Redis cache. After you do that, you can set up the SDK in consumer mode.

Consumer Mode

In consumer mode, a client can be embedded in your application code and respond to calls to get_treatment by retrieving state from the data store (Redis in this case).

Here is how to configure and get treatments for a Split client in consumer mode.

options = {
  # Other options here
  cache_adapter: :redis,
  mode: :consumer,
  redis_url: 'redis://127.0.0.1:6379/0'
}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Configure Redis using Sentinel

Use the syntax below to configure Redis using Sentinel:

SENTINELS = [{host: '127.0.0.1', port: 26380},
             {host: '127.0.0.1', port: 26381}]

redis_connection = {
  url: 'redis://mymaster',
  sentinels: SENTINELS,
  role: :master
}

options = {
  # Other options here
  redis_url: redis_connection
}

split_factory = SplitIoClient::SplitFactory.new('YOUR_SDK_KEY', options)
split_client = split_factory.client

Redis Cluster

This functionality is currently not supported for this SDK, but is coming in a future release! Subscribe to our release notes for updates.

Localhost mode

Features start their life on one developer's machine. A developer should be able to put code behind feature flags on their development machine without the SDK requiring network connectivity. To achieve this, the Split SDK can be started in localhost mode (aka off-the-grid mode). In this mode, the SDK neither polls nor updates Split servers. Instead, it uses an in-memory data structure to determine what treatments to show to the logged in customer for each of the features.

To use the SDK in localhost mode, replace the SDK Key with "localhost", as shown in the example below:

require 'splitclient-rb'
split_file = File.expand_path(File.join(File.dirname(__FILE__), '../test_data/local_treatments/split.yaml'))

split_client = split_factory = SplitIoClient::SplitFactory.new('localhost', split_file: split_file).client

In this mode, the SDK loads a .yaml file containing a simple depiction of a feature flag. eg:

In the example given, a call to get_treatment passing john_doe as the key renders the on treatment, while as any other key receives off. Note that configs can be added to test the _with_config versions of get_treatment and get_treatments. Also, you can set multiple keys for the same treatment using an array:

Any feature that is not provided in the split_file markup map returns the control treatment if the SDK is asked to evaluate them.

By default, changes in the file are not automatically picked up without restarting the client. To have the client automatically pick up changes to the file, specify reload_rate as the interval in seconds at which changes are picked up. Here is an example of specifying both split_file and reload_rate.

factory = SplitIoClient::SplitFactoryBuilder.build('localhost', split_file: '/where/to-look-for/<file_name>', reload_rate: 3)

Manager

Use the Split Manager to get a list of feature flags available to the Split client. To instantiate a Manager in your code base, use the same factory that you used for your client.

# Reusing the split_factory created originally.
split_manager = split_factory.manager

The SplitView object referenced above has the following structure.

# returns a List of SplitViews or empty.
list_of_feature_flags = split_manager.splits

# Array of String representing feature flag names
list_of_feature_flag_names = split_manager.split_names

# returns a SplitView of the 'name' specified or empty.
feature_flag = split_manager.split(name)

The feature_flag object referenced above has the following structure.

{
 :name=>"new_reporting",
 :traffic_type_name=>"user",
 :killed=>false,
 :treatments=>["v1", "v2", "v3"],
 :change_number=>1469134003507
 :configs=>{:on=>"{\"size\":15,\"test\":20}"}
 :default_treatment=>"off"
 :sets>=["backend"]
}

Listener

Split SDKs send impression data back to Split servers periodically when evaluating feature flags. To send this information to a location of your choice, define and attach an impression listener.

The SDK sends the generated impressions to the impression listener right away. However, to avoid blocking the caller thread, use the second parameter to specify the size of the queue acting as a buffer. Refer to the followoing snippet:

If the impression listener is slow at processing the incoming data, the queue fills up and any subsequent impressions are dropped.

class MyImpressionListener
  def log(impression)
    Logger.new($stdout).info(impression)
  end
end

options = {
  # other options
  impression_listener: MyImpressionListener.new # do remember to initialize your class here
  # other options
}

factory = SplitIoClient::SplitFactoryBuilder.build(sdk_key, options)

Logging

Our Ruby SDK makes use of Ruby’s stdlib Logger class to log errors/events. The default option is shown below:

Logger.new($stdout)

You can configure the following options in the config file.

{
  # ...
  # you can specify your own Logger class instance here:
  logger: Logger.new('logfile.log'),
  # to enable more verbose logging, including more debug information (false is the default) use:
  debug_enabled: true,
  # to log transport data (mostly http requests, false is the default) use:
  transport_debug_enabled: true
  # ...
}

Proxy

Ruby SDK respects the HTTP_PROXY environment variable. To use a proxy, assign a proxy address to that variable.

http_proxy=http://username:password@hostname:port

Troubleshooting

I am seeing the following certificate error: OpenSSL::SSL::SSLError

On OSX, if you see an SSL issue that looks similar to the example below, refer to this post for troubleshooting.

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed