/Docs

Ruby on Rails integration

This guide targets Ruby on Rails 7.1+ with Ruby 3.2 or later. The avsb gem ships a Railtie that auto-connects the SDK and a Rack middleware that scopes flag evaluation to each request. By the end you will be reading flags in controllers and views, tracking conversions, and shutting down cleanly on SIGTERM.

1

Install

Gemfile
ruby
1gem 'avsb'
terminal
bash
1bundle install
2

Obtain your SDK key

Open your A vs B project, go to Settings → Environments, and copy the Server SDK key. Store it in your credentials file or an environment variable — never commit it to source control.

terminal
bash
1# Using Rails credentials
2rails credentials:edit
3# Add:  avsb_sdk_key: sdk_production_...
4

5# Or use an environment variable
6export AVSB_SDK_KEY=sdk_production_...
3

Configure the SDK

Create an initialiser. The Railtie picks this up automatically — you do not need to register middleware manually; the gem inserts Avsb::Rack::Middleware into the Rack stack for you.

config/initializers/avsb.rb
ruby
1Avsb.configure do |config|
2  config.sdk_key = Rails.application.credentials.avsb_sdk_key ||
3                   ENV['AVSB_SDK_KEY']
4

5  # Optional: build the eval context from every Rack request.
6  # The proc receives the Rack env hash and must return a Hash.
7  config.context_from = lambda do |rack_env|
8    request = ActionDispatch::Request.new(rack_env)
9    {
10      kind: 'user',
11      key:  request.session[:user_id]&.to_s || 'anon',
12      plan: request.headers['X-User-Plan'] || 'free',
13    }
14  end
15end
4

Read a flag in a controller

The middleware makes a scoped client available via the Rails helper methodavsb_client inside controllers. You can also use the view helperavsb_flag in ERB templates.

app/controllers/checkout_controller.rb
ruby
1class CheckoutController < ApplicationController
2  def show
3    # avsb_client is a per-request scoped client
4    @show_new_checkout = avsb_client.get_bool_flag('checkout-v2', false)
5    @ui_theme          = avsb_client.get_string_flag('ui-theme', 'default')
6  end
7end
app/views/checkout/show.html.erb
ruby
1<%# In views, use the helper directly %>
2<% if avsb_flag('checkout-v2', default: false) %>
3  <%= render 'checkout/new' %>
4<% else %>
5  <%= render 'checkout/legacy' %>
6<% end %>
5

Track an event

app/controllers/checkout_controller.rb
ruby
1def complete
2  avsb_client.track('purchase', value: 149.99, properties: { currency: 'usd' })
3  redirect_to root_path
4end
6

Identify a user

After login you may want to re-scope to the authenticated user without relying on the middleware's context. Call Avsb.server.for_userdirectly:

ruby
1scoped = Avsb.server.for_user(
2  kind: 'user',
3  key:  current_user.id.to_s,
4  plan: current_user.plan,
5  org:  current_user.org_key,
6)
7show_new = scoped.get_bool_flag('checkout-v2', false)
Tip
For multi-context targeting — for example when you want to target by both user and organisation — use the kind: 'multi' shape described in the multi-context guide.

Graceful shutdown

Rails forwards SIGTERM to Puma, which waits for in-flight requests to complete before shutting down. Register an at_exit hook or a Puma plugin to flush the SDK before the process exits:

config/initializers/avsb.rb
ruby
1at_exit { Avsb.server&.close }

Testing

Use the Avsb::TestUtils module to stub flag values without network access. The with_flag helper scopes overrides to a single test.

spec/controllers/checkout_controller_spec.rb
ruby
1require 'rails_helper'
2require 'avsb/test_utils'
3

4RSpec.describe CheckoutController, type: :controller do
5  include Avsb::TestUtils
6

7  it 'renders new checkout when flag is on' do
8    with_flag('checkout-v2', true) do
9      get :show
10      expect(assigns(:show_new_checkout)).to be true
11    end
12  end
13

14  it 'renders legacy checkout by default' do
15    with_flag('checkout-v2', false) do
16      get :show
17      expect(assigns(:show_new_checkout)).to be false
18    end
19  end
20end

What's next