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

Implements fetching variants for a user via remote evaluation.

Install

Install the Ruby Server SDK with bundler or gem directly.

1gem 'amplitude-experiment'

1gem install amplitude-experiment

 1require 'amplitude-experiment'
 2 
 3# (1) Initialize the experiment client
 4experiment = AmplitudeExperiment.initialize_remote('<DEPLOYMENT_KEY>', AmplitudeExperiment::RemoteEvaluationConfig.new)
 5 
 6# (2) Fetch variants for a user
 7user = AmplitudeExperiment::User.new(
 8  user_id: 'user@company.com',
 9  device_id: 'abcdefg',
10  user_properties: {
11    'premium' => true
12  }
13)
14variants = experiment.fetch(user)
15 
16# (3) Access a flag's variant
17variant = variants['YOUR-FLAG-KEY']
18unless variant.nil?
19    if variant.value == 'on'
20        # Flag is on
21    else
22        # Flag is off
23    end
24end

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.

1initialize_remote(apiKey, config = nil) : Client

1experiment = 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.

1fetch(user: AmplitudeExperiment::User) : Variants

1user = AmplitudeExperiment::User.new(
2    user_id: 'user@company.com',
3    device_id: 'abcdefg',
4    user_properties: {
5        'premium' => true
6    }
7)
8variants = experiment.fetch(user)

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

1variant = variants['YOUR-FLAG-KEY']
2unless variant.nil?
3  if variant.value == 'on'
4    # Flag is on
5  else
6    # Flag is off
7  end
8end

Fetch async

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

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

 1experiment.fetch_async(user) do |_, variants|
 2  variant = variants['sdk-ci-test']
 3  unless variant.nil?
 4    if variant.value == 'on'
 5      # Flag is on
 6    else
 7      # Flag is off
 8    end
 9  end
10end

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.

1gem 'amplitude-experiment'

1gem install amplitude-experiment

 1require 'amplitude-experiment'
 2 
 3# (1) Initialize the local evaluation client with a server deployment key.
 4experiment = AmplitudeExperiment.initialize_local('DEPLOYMENT_KEY',
 5  # (Recommended) Enable local evaluation cohort targeting.
 6  AmplitudeExperiment::LocalEvaluationConfig.new(
 7    cohort_sync_config: AmplitudeExperiment::CohortSyncConfig.new(
 8      api_key: 'API_KEY',
 9      secret_key: 'SECRET_KEY'
10    )
11  )
12)
13 
14# (2) Start the local evaluation
15experiment.start
16 
17# (3) Evaluate a user
18user = AmplitudeExperiment::User.new(
19  user_id: 'user@company.com',
20  device_id: 'abcdefg',
21  user_properties: {
22    'premium' => true
23  }
24)
25variants = experiment.evaluate(user)
26variant = variants['YOUR-FLAG-KEY']
27unless variant.nil?
28    if variant.value == 'on'
29        # Flag is on
30    else
31        # Flag is off
32    end
33end

Initialize

Initializes a local evaluation client.

1AmplitudeExperiment.initialize_local(api_key)

Configuration

You can configure the SDK client on initialization.

LocalEvaluationConfig

AssignmentConfig

CohortSyncConfig

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.

1start

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

1experiment.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.

1evaluate(user, flag_keys)

 1# The user to evaluate
 2user = AmplitudeExperiment::User.new(user_id: 'test-user')
 3# Evaluate all flag variants
 4all_variants = experiment.evaluate(user)
 5# Evaluate a specific subset of flag variants
 6specific_variants = experiment.evaluate(user, ["<FLAG_KEY_1>", "<FLAG_KEY_2>"])
 7# Access a variant
 8variant = all_variants["<FLAG_KEY>"]
 9if variant.value == 'on':
10    # Flag is on
11else:
12    # Flag is off
13end

Local evaluation cohort targeting

Since version 1.5.0, the local evaluation SDK client supports downloading cohorts for local evaluation targeting. You must configure the cohort_sync_config option with the analytics api_key and secret_key on initialization to enable this support.

1experiment = AmplitudeExperiment.initialize_local('DEPLOYMENT_KEY',
2  # (Recommended) Enable local evaluation cohort targeting.
3  AmplitudeExperiment::LocalEvaluationConfig.new(
4    cohort_sync_config: AmplitudeExperiment::CohortSyncConfig.new(
5      api_key: 'API_KEY',
6      secret_key: 'SECRET_KEY'
7    )
8  )
9)

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.

 1require 'amplitude-experiment'
 2 
 3# grab amp device id if present
 4amp_cookie_name = AmplitudeExperiment::AmplitudeCookie.cookie_name('amplitude-api-key')
 5device_id = nil
 6unless cookies[amp_cookie_name].nil?
 7  device_id = AmplitudeExperiment::AmplitudeCookie.parse(cookies[amp_cookie_name]).device_id
 8end
 9 
10if device_id.nil?
11  # deviceId doesn't exist, set the Amplitude Cookie
12  device_id = SecureRandom.uuid
13  amp_cookie_value = AmplitudeExperiment::AmplitudeCookie.generate(device_id)
14  cookies[amp_cookie_name] = {
15    value: amp_cookie_value,
16    domain: '.your-domain.com', # this should be the same domain used by the Amplitude JS SDK
17    httponly: false,
18    secure: false
19  }
20end