Skip to content
Featureflip Docs

Ruby Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in a Ruby application. The SDK is thread-safe and has zero runtime dependencies.

Prerequisites

Section titled “Prerequisites”
  • A Featureflip account with at least one feature flag created
  • An SDK key from your environment settings
  • Ruby 3.2+

Install

Section titled “Install”

Add to your Gemfile:

gem "featureflip"

Then run:

Terminal window
bundle install

Initialize the client

Section titled “Initialize the client”
require "featureflip"


config = Featureflip::Config.new(base_url: "https://eval.featureflip.io")


client = Featureflip::Client.new(sdk_key: "your-sdk-key", config: config)

The client fetches your flag configuration on startup and blocks until initialization completes. If you prefer, set the FEATUREFLIP_SDK_KEY environment variable and omit the sdk_key parameter:

client = Featureflip::Client.new(config: config)

Evaluate a flag

Section titled “Evaluate a flag”
show_banner = client.bool_variation("new-banner", { user_id: "user-123" }, false)


if show_banner
  puts "Showing the new banner"
else
  puts "Using the default experience"
end

The SDK provides typed methods for each flag type. The default_value argument is returned when the flag is not found or evaluation fails.

color = client.string_variation("banner-color", { user_id: "user-123" }, "blue")
limit = client.number_variation("rate-limit", { user_id: "user-123" }, 100)

Clean up

Section titled “Clean up”

Close the client when your application shuts down to flush pending analytics events and stop background connections:

client.close

For Rails applications, use the singleton API with an initializer:

config/initializers/featureflip.rb
Featureflip.configure do |c|
  c.sdk_key = ENV["FEATUREFLIP_SDK_KEY"]
  c.streaming = true
end


# In your application code
enabled = Featureflip.bool_variation("new-banner", { user_id: "user-123" }, false)


# On shutdown
Featureflip.close

How it works

Section titled “How it works”

The Ruby SDK uses a singleton pattern — Featureflip.configure initializes one shared client for your entire process. This matches how most Ruby web frameworks operate: Puma and Unicorn fork worker processes, and each worker holds its own SDK instance with its own flag store and streaming connection.

On initialization, the client fetches the full flag configuration over HTTPS, then spawns a background thread that maintains an SSE streaming connection for near-real-time updates. Polling every 30 seconds is available as a fallback. The internal flag store is protected by a Mutex, so bool_variation and other variation calls are thread-safe — important for Puma’s multi-threaded workers where concurrent requests share the same process.

Call Featureflip.close during shutdown (e.g., in an at_exit hook or Rails initializer teardown) to stop the background thread and flush pending analytics events. If the streaming connection drops, the SDK keeps returning the last known flag values until it reconnects.

Troubleshooting

Section titled “Troubleshooting”

Client initialization hangs or times out

Verify your SDK key matches the target environment and that your application can reach eval.featureflip.io over HTTPS. If you use Bundler behind a corporate proxy, the SDK’s HTTP client also needs proxy access — check your HTTP_PROXY / HTTPS_PROXY environment variables.

Flags return default values after successful init

Flag keys are case-sensitive. Verify the key matches the dashboard exactly, and confirm the flag is enabled in the environment matching your SDK key.

LoadError when requiring featureflip

Make sure the gem is installed: run gem list featureflip to check. If you are using Bundler, ensure gem "featureflip" is in your Gemfile and you have run bundle install. Run your script with bundle exec to use the Bundler-managed gem.

Next steps

Section titled “Next steps”