Experiment Ruby SDK

Official documentation for Amplitude Experiment's server-side Ruby SDK implementation.

This documentation is split into two sections for remote and local evaluation:

• Remote evaluation
• Local evaluation

Remote evaluation¶

Implements fetching variants for a user via remote evaluation.

Install¶

Install the Ruby Server SDK with bundler or gem directly.

gem 'amplitude-experiment'

gem install amplitude-experiment

require 'amplitude-experiment'

# (1) Initialize the experiment client
experiment = AmplitudeExperiment.initialize_remote('<DEPLOYMENT_KEY>', AmplitudeExperiment::RemoteEvaluationConfig.new)

# (2) Fetch variants for a user
user = AmplitudeExperiment::User.new(
  user_id: 'user@company.com',
  device_id: 'abcdefg',
  user_properties: {
    'premium' => true
  }
)
variants = experiment.fetch(user)

# (3) Access a flag's variant
variant = variants['YOUR-FLAG-KEY']
unless variant.nil?
    if variant.value == 'on'
        # Flag is on
    else
        # Flag is off
    end
end

Initialize¶

The SDK client should be initialized in your server on startup. The deployment key argument passed into the apiKey parameter must live within the same project that you are sending analytics events to.

initialize_remote(apiKey, config = nil) : Client

experiment = AmplitudeExperiment.initialize_remote('<DEPLOYMENT_KEY>', AmplitudeExperiment::RemoteEvaluationConfig.new)

Configuration¶

You can configure the SDK client on initialization.

Fetch¶

Fetches variants for a user and returns the results. This function remote evaluates the user for flags associated with the deployment used to initialize the SDK client.

fetch(user: AmplitudeExperiment::User) : Variants

user = AmplitudeExperiment::User.new(
    user_id: 'user@company.com',
    device_id: 'abcdefg',
    user_properties: {
        'premium' => true
    }
)
variants = experiment.fetch(user)

After fetching variants for a user, you may to access the variant for a specific flag.

variant = variants['YOUR-FLAG-KEY']
unless variant.nil?
  if variant.value == 'on'
    # Flag is on
  else
    # Flag is off
  end
end

Fetch async¶

The fetch method is synchronous. To fetch asynchronously, you can use fetch_async method

fetch_async(user: AmplitudeExperiment::User, &callback)

experiment.fetch_async(user) do |_, variants|
  variant = variants['sdk-ci-test']
  unless variant.nil?
    if variant.value == 'on'
      # Flag is on
    else
      # Flag is off
    end
  end
end

Local evaluation¶

Implements evaluating variants for a user via local evaluation. If you plan on using local evaluation, you should understand the tradeoffs.

Install¶

Install the Ruby Server SDK's local evaluation.

Install the Ruby Server SDK with bundler or gem directly.

gem 'amplitude-experiment'

gem install amplitude-experiment

require 'amplitude-experiment'

# (1) Initialize the local evaluation client with a server deployment key.
experiment = AmplitudeExperiment.initialize_local('<DEPLOYMENT_KEY>', AmplitudeExperiment::LocalEvaluationConfig.new)

# (2) Start the local evaluation
experiment.start

# (3) Evaluate a user
user = AmplitudeExperiment::User.new(
  user_id: 'user@company.com',
  device_id: 'abcdefg',
  user_properties: {
    'premium' => true
  }
)
variants = experiment.evaluate(user)
variant = variants['YOUR-FLAG-KEY']
unless variant.nil?
    if variant.value == 'on'
        # Flag is on
    else
        # Flag is off
    end
end

Initialize¶

Initializes a local evaluation client.

AmplitudeExperiment.initialize_local(api_key)

Configuration¶

You can configure the SDK client on initialization.

Start¶

Start the local evaluation client, pre-fetching local evaluation mode flag configs for evaluation and starting the flag config poller at the configured interval.

start

You should await the result of start to ensure that flag configs are ready to be used before calling evaluate()

experiment.start

Evaluate¶

Executes the evaluation logic using the flags pre-fetched on start. You must give evaluate a user object argument, and can you can optionally pass it an array of flag keys if only a specific subset of required flag variants are required.

evaluate(user, flag_keys)

# The user to evaluate
user = AmplitudeExperiment::User.new(user_id: 'test-user')
# Evaluate all flag variants
all_variants = experiment.evaluate(user)
# Evaluate a specific subset of flag variants
specific_variants = experiment.evaluate(user, ["<FLAG_KEY_1>", "<FLAG_KEY_2>"])
# Access a variant
variant = all_variants["<FLAG_KEY>"]
if variant.value == 'on':
    # Flag is on
else:
    # Flag is off
end

Access Amplitude cookies¶

If you're using the Amplitude Analytics SDK on the client-side, the Ruby server SDK provides an AmplitudeCookie class with convenience functions for parsing and interacting with the Amplitude identity cookie. This is useful for ensuring that the Device ID on the server matches the Device ID set on the client, especially if the client hasn't yet generated a Device ID.

require 'amplitude-experiment'

# grab amp device id if present
amp_cookie_name = AmplitudeExperiment::AmplitudeCookie.cookie_name('amplitude-api-key')
device_id = nil
unless cookies[amp_cookie_name].nil?
  device_id = AmplitudeExperiment::AmplitudeCookie.parse(cookies[amp_cookie_name]).device_id
end

if device_id.nil?
  # deviceId doesn't exist, set the Amplitude Cookie
  device_id = SecureRandom.uuid
  amp_cookie_value = AmplitudeExperiment::AmplitudeCookie.generate(device_id)
  cookies[amp_cookie_name] = {
    value: amp_cookie_value,
    domain: '.your-domain.com', # this should be the same domain used by the Amplitude JS SDK
    httponly: false,
    secure: false
  }
end