Ruby SDK for ABsmartly A/B testing platform.
The ABsmartly Ruby SDK is compatible with Ruby versions 2.7 and later. For the best performance and code readability, Ruby 3 or later is recommended. This SDK is being constantly tested with the nightly builds of Ruby, to ensure it is compatible with the latest Ruby version.
Install the gem and add to the application's Gemfile by executing:
bundle add absmartly-sdkIf bundler is not being used to manage dependencies, install the gem by executing:
gem install absmartly-sdkPlease follow the installation instructions before trying the following code.
This example assumes an API Key, an Application, and an Environment have been created in the ABsmartly web console.
The simplest and most idiomatic way to initialize the SDK in Ruby:
require 'absmartly'
sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development"
)sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development",
timeout: 5000, # Connection timeout in milliseconds (default: 3000)
retries: 3 # Max retry attempts (default: 5)
)For applications that need a single SDK instance shared globally:
require 'absmartly'
Absmartly.configure_client do |config|
config.endpoint = "https://your-company.absmartly.io/v1"
config.api_key = "YOUR-API-KEY"
config.application = "website"
config.environment = "development"
endFor use cases where you need custom providers, serializers, or other low-level configurations:
require 'absmartly'
client_config = ClientConfig.create
client_config.endpoint = "https://your-company.absmartly.io/v1"
client_config.api_key = "YOUR-API-KEY"
client_config.application = "website"
client_config.environment = "development"
client_config.connect_timeout = 3.0
client_config.connection_request_timeout = 3.0
client_config.retry_interval = 0.5
client_config.max_retries = 5
# Opt in to retrying HTTP statuses (none by default). Retrying a publish after
# a 5xx may duplicate events the collector already stored.
client_config.retry_statuses = [502, 503, 504]
# Opt in to retrying a refused connection on the context fetch (off by default).
# Each retry waits retry_interval, doubling each time.
client_config.retry_connection_failures = true
sdk_config = ABSmartlyConfig.create
sdk_config.client = Client.create(client_config)
sdk = ABSmartly.create(sdk_config)SDK Options
| Parameter | Type | Required? | Default | Description |
|---|---|---|---|---|
| endpoint | String |
✅ | nil |
The URL to your API endpoint. Most commonly "https://your-company.absmartly.io/v1" (first positional parameter) |
| api_key | String |
✅ | nil |
Your API key which can be found on the Web Console. |
| application | String |
✅ | nil |
The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| environment | String |
✅ | nil |
The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| timeout | Integer |
❌ | 3000 |
The connection and request timeout in milliseconds. Converted to seconds internally. |
| retries | Integer |
❌ | 5 |
The maximum number of retries before giving up. |
| context_event_logger | ContextEventLogger |
❌ | nil |
A ContextEventLogger instance implementing handle_event(event, data) to receive SDK events. See "Custom Event Logger" below. |
sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development"
)
context_config = ContextConfig.create
context_config.set_unit('session_id', '5ebf06d8cb5d8137290c4abb64155584fbdb64d8')
context = sdk.create_context(context_config)Or using the global configuration approach:
Absmartly.configure_client do |config|
config.endpoint = "https://your-company.absmartly.io/v1"
config.api_key = "YOUR-API-KEY"
config.application = "website"
config.environment = "development"
end
context_config = Absmartly.create_context_config
context_config.set_unit('session_id', '5ebf06d8cb5d8137290c4abb64155584fbdb64d8')
context = Absmartly.create_context(context_config)When you want to avoid blocking the current thread while fetching experiment data, use create_context_async. It returns a Context immediately and fetches data in a background thread.
sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development"
)
context_config = ContextConfig.create
context_config.set_unit('session_id', '5ebf06d8cb5d8137290c4abb64155584fbdb64d8')
context = sdk.create_context_async(context_config)
# Do other work while data is being fetched...
# Block until the context is ready (or use a timeout)
context.wait_until_ready
# context.wait_until_ready(5) # with a 5-second timeout
if context.ready?
treatment = context.treatment('exp_test_experiment')
endRead methods (treatment, peek_treatment, variable_value, peek_variable_value, variable_keys, experiments, custom_field_keys, custom_field_value) raise IllegalStateException ("ABSmartly Context is not yet ready") until the context is ready, and ("ABSmartly Context is closed") after close. Check ready? first. A context whose data fetch failed is ready and failed: reads return control (0) and the caller's defaults.
Or using the global configuration approach:
context = Absmartly.create_context_async(context_config)
context.wait_until_readyWhen doing full-stack experimentation with ABsmartly, we recommend creating a context only once on the server-side. Creating a context involves a round-trip to the ABsmartly event collector. We can avoid repeating the round-trip on the client-side by sending the server-side data embedded in the first document.
sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development"
)
context_config = ContextConfig.create
context_config.set_unit('session_id', '5ebf06d8cb5d8137290c4abb64155584fbdb64d8')
server_context = sdk.create_context(context_config)
client_context_config = ContextConfig.create
client_context_config.set_unit('session_id', '5ebf06d8cb5d8137290c4abb64155584fbdb64d8')
client_context = sdk.create_context_with(client_context_config, server_context.data)For long-running contexts, the context is usually created once when the application is first started. However, any experiments being tracked in your production code, but started after the context was created, will not be triggered.
The refresh method can be called manually. The refresh method pulls updated experiment data from the ABsmartly collector and will trigger recently started experiments when treatment is called again.
context.refreshYou can add additional units to a context by calling the set_unit or set_units methods. These methods may be used, for example, when a user logs in to your application and you want to use the new unit type in the context.
Note: You cannot override an already set unit type as that would be a change of identity and would throw an exception. In this case, you must create a new context instead. The
set_unitandset_unitsmethods can be called before the context is ready.
context_config.set_unit('session_id', 'bf06d8cb5d8137290c4abb64155584fbdb64d8')
context_config.set_unit('user_id', '123456')
context = Absmartly.create_context(context_config)or
context_config.set_units(
session_id: 'bf06d8cb5d8137290c4abb64155584fbdb64d8',
user_id: '123456'
)
context = Absmartly.create_context(context_config)treatment = context.treatment('exp_test_experiment')
if treatment.zero?
# user is in control group (variant 0)
else
# user is in treatment group
endVariables allow you to configure experiment variants dynamically:
default_button_color = 'red'
button_color = context.variable_value('button.color', default_button_color)Although generally not recommended, it is sometimes necessary to peek at a treatment or variable without triggering an exposure. The ABsmartly SDK provides peek_treatment and peek_variable_value methods for that.
treatment = context.peek_treatment('exp_test_experiment')button_color = context.peek_variable_value('button.color', 'red')During development, for example, it is useful to force a treatment for an experiment. This can be achieved with the set_override and/or set_overrides methods. These methods can be called before the context is ready.
context.set_override('exp_test_experiment', 1) # force variant 1 of treatment
context.set_overrides(
'exp_test_experiment' => 1,
'exp_another_experiment' => 0
)Attributes are used to pass meta-data about the user and/or the request. They can be used later in the Web Console to create segments or audiences. They can be set using the set_attribute or set_attributes methods, before or after the context is ready.
context.set_attribute('user_agent', request.user_agent)
context.set_attributes(
customer_age: 'new_customer',
account_type: 'premium'
)The application and environment configured on the client are available to audience filters and assignment rule conditions as application and environment. A name that is unset or empty is left out, so a filter on it sees no value. An attribute you set with the same name takes precedence. They are not added to published attributes, since the collector attaches them itself.
Experiments can define assignment rules on the Web Console. They are evaluated in order and the first matching rule decides the variant, taking precedence over audience targeting, traffic allocation and custom assignments; only set_override beats a rule. Rule-assigned exposures are flagged ruleOverride so they are excluded from analysis.
- An
assignrule gives a fixed variant. - A
splitrule randomizes the unit over its own percentages, e.g.20/30/50. While the experiment's unit is missing, it gives the full-on variant (0 for an experiment that is not full-on); once the unit is set, the rule is re-resolved unless that variant was already exposed.
Rule conditions are audience expressions, so they can use your attributes, application, environment and the semver_eq, semver_gt, semver_gte, semver_lt and semver_lte operators, e.g. {"semver_gte": [{"var": "app_version"}, {"value": "2.4.0"}]}.
Sometimes it may be necessary to override the automatic selection of a variant. For example, if you wish to have your variant chosen based on data from an API call. This can be accomplished using the set_custom_assignment method.
chosen_variant = 1
context.set_custom_assignment('experiment_name', chosen_variant)If you are running multiple experiments and need to choose different custom assignments for each one, you can do so using the set_custom_assignments method.
assignments = {
'experiment_name' => 1,
'another_experiment_name' => 0,
'a_third_experiment_name' => 2
}
context.set_custom_assignments(assignments)Goals are created in the ABsmartly web console.
context.track('payment', {
item_count: 1,
total_amount: 1999.99
})Sometimes it is necessary to ensure all events have been published to the ABsmartly collector, before proceeding. You can explicitly call the publish method.
context.publishThe close method will ensure all events have been published to the ABsmartly collector, like publish, and will also "seal" the context, throwing an error if any method that could generate an event is called.
If the final publish fails, close raises the failure, the context stays open and the events stay queued, so close can be called again to retry. The raised error is a StandardError, so it can be caught with an ordinary rescue.
context.closefinalize does the same as close, but logs the "finalize" event instead of "close".
The ABsmartly SDK can be instantiated with an event logger used for all contexts. In addition, an event logger can be specified when creating a particular context in the context config.
class CustomEventLogger < ContextEventLogger
def handle_event(event, data)
case event
when EVENT_TYPE::EXPOSURE
puts "Exposed to experiment: #{data.name}"
when EVENT_TYPE::GOAL
puts "Goal tracked: #{data.name}"
when EVENT_TYPE::ERROR
puts "Error: #{data}"
when EVENT_TYPE::PUBLISH
puts "Events published: #{data.length} events"
when EVENT_TYPE::READY
puts "Context ready with #{data.experiments.length} experiments"
when EVENT_TYPE::REFRESH
puts "Context refreshed with #{data.experiments.length} experiments"
when EVENT_TYPE::CLOSE, EVENT_TYPE::FINALIZE
puts "Context closed"
end
end
end
sdk = ABSmartly.new(
"https://your-company.absmartly.io/v1",
api_key: "YOUR-API-KEY",
application: "website",
environment: "development",
context_event_logger: CustomEventLogger.new
)Or using the global configuration approach:
Absmartly.configure_client do |config|
config.endpoint = "https://your-company.absmartly.io/v1"
config.api_key = "YOUR-API-KEY"
config.application = "website"
config.environment = "development"
config.event_logger = CustomEventLogger.new
endThe data parameter depends on the type of event. Currently, the SDK logs the following events:
Event Types
| Event | When | Data |
|---|---|---|
Error |
Context receives an error |
Error object thrown |
Ready |
Context turns ready |
ContextData used to initialize the context |
Refresh |
Context.refresh() method succeeds |
ContextData used to refresh the context |
Publish |
Context.publish() method succeeds |
PublishEvent sent to the collector |
Exposure |
Context.treatment() method succeeds on first exposure |
Exposure data enqueued for publishing |
Goal |
Context.track() method succeeds |
GoalAchievement enqueued for publishing |
Close |
Context.close() method succeeds the first time |
nil |
Finalize |
Context.finalize() method succeeds the first time |
nil |
# config/initializers/absmartly.rb
require 'absmartly'
Absmartly.configure_client do |config|
config.endpoint = ENV['ABSMARTLY_ENDPOINT']
config.api_key = ENV['ABSMARTLY_API_KEY']
config.application = "website"
config.environment = Rails.env
end
# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
before_action :setup_absmartly_context
after_action :close_absmartly_context
private
def setup_absmartly_context
context_config = Absmartly.create_context_config
context_config.set_unit('session_id', session.id.to_s)
context_config.set_unit('user_id', current_user&.id&.to_s) if current_user
@absmartly_context = Absmartly.create_context(context_config)
rescue => e
Rails.logger.error "ABsmartly context creation failed: #{e.message}"
@absmartly_context = nil
end
def close_absmartly_context
@absmartly_context&.close
end
end
# app/controllers/products_controller.rb
class ProductsController < ApplicationController
def show
treatment = @absmartly_context&.treatment('exp_product_layout') || 0
if treatment == 0
render 'show_control'
else
render 'show_treatment'
end
end
endrequire 'sinatra'
require 'absmartly'
configure do
Absmartly.configure_client do |config|
config.endpoint = ENV['ABSMARTLY_ENDPOINT']
config.api_key = ENV['ABSMARTLY_API_KEY']
config.application = "website"
config.environment = ENV['RACK_ENV']
end
end
use Rack::Session::Cookie, secret: ENV['SESSION_SECRET']
before do
context_config = Absmartly.create_context_config
context_config.set_unit('session_id', session[:session_id] ||= SecureRandom.uuid)
@absmartly_context = Absmartly.create_context(context_config)
end
after do
@absmartly_context&.close
end
get '/' do
treatment = @absmartly_context.treatment('exp_test_experiment')
if treatment == 0
erb :control
else
erb :treatment
end
end# config.ru
require 'absmartly'
class ABsmartlyMiddleware
def initialize(app)
@app = app
Absmartly.configure_client do |config|
config.endpoint = ENV['ABSMARTLY_ENDPOINT']
config.api_key = ENV['ABSMARTLY_API_KEY']
config.application = "website"
config.environment = ENV['RACK_ENV']
end
end
def call(env)
request = Rack::Request.new(env)
context_config = Absmartly.create_context_config
context_config.set_unit('session_id', request.session['session_id'])
context = Absmartly.create_context(context_config)
env['absmartly.context'] = context
begin
@app.call(env)
ensure
context.close
end
end
end
use ABsmartlyMiddleware
run MyAppA/B Smartly is the leading provider of state-of-the-art, on-premises, full-stack experimentation platforms for engineering and product teams that want to confidently deploy features as fast as they can develop them. A/B Smartly's real-time analytics helps engineering and product teams ensure that new features will improve the customer experience without breaking or degrading performance and/or business metrics.