> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getunleash.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getunleash.io/_mcp/server.

# Ruby OpenFeature provider

> Set up the Unleash OpenFeature provider for Ruby to evaluate feature flags through the OpenFeature API.

The Unleash OpenFeature Ruby provider lets Ruby applications evaluate Unleash feature flags through the [OpenFeature](https://openfeature.dev/) API.

The provider wraps the [Unleash Ruby SDK](/sdks/ruby) and uses the same backend SDK behavior for polling, local evaluation, caching, metrics, and shutdown.

## Requirements

* Ruby 3.4 or later

## Installation

Add the provider to your application's Gemfile. The provider declares the OpenFeature SDK and the [Unleash Ruby SDK](/sdks/ruby) as dependencies, so you don't need to add them separately.

```ruby
gem 'unleash-openfeature-provider'
```

Then install your dependencies:

```bash
bundle install
```

## Configuration

Create an `Unleash::OpenFeature::Provider::UnleashFlagProvider` with the same [options](/sdks/ruby#configuration) you would pass to the Unleash Ruby SDK client, then register it with OpenFeature.

```ruby
require 'open_feature/sdk'
require 'unleash-openfeature-provider'

provider = Unleash::OpenFeature::Provider::UnleashFlagProvider.new(
  app_name: 'my-ruby-app',
  url: '<YOUR_UNLEASH_URL>/api',
  custom_http_headers: {
    Authorization: '<YOUR_API_TOKEN>'
  }
)

OpenFeature::SDK.configure do |config|
  config.set_provider(provider)
end
```

## Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

```ruby
client = OpenFeature::SDK.build_client

context = OpenFeature::SDK::EvaluationContext.new(
  targeting_key: 'user-123'
)

enabled = client.fetch_boolean_value(
  flag_key: 'my-feature',
  default_value: false,
  evaluation_context: context
)
```

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag's enabled state. All other types resolve from the payload of the flag's [variant](/concepts/feature-flag-variants):

* String values accept `string` and `csv` payloads.
* Number, integer, and float values accept `number` payloads.
* Object values accept `json` payloads.

If the flag is disabled, or the variant payload is missing or has a different type, the evaluation returns the default value.

## Context mapping

The provider maps the OpenFeature evaluation context to an [Unleash context](/concepts/unleash-context) before each evaluation.

The following OpenFeature fields map directly to top-level Unleash context fields:

* `currentTime`
* `userId`
* `sessionId`
* `remoteAddress`
* `environment`
* `appName`

If you set `targeting_key`, the provider maps it to `userId`. The `targeting_key` takes precedence over a `userId` field set on the evaluation context.

The provider adds all other scalar fields, such as strings, numbers, booleans, and time values, to the Unleash context [properties](/concepts/unleash-context#the-properties-field). It discards nested values, such as arrays and hashes.

## Shutdown

Shut down the provider when your application exits. This also shuts down the underlying Unleash client.

```ruby
provider.shutdown
```

## Example

To try the provider against your Unleash instance, clone the [provider repository](https://github.com/Unleash/unleash-openfeature-ruby-provider) and run the [boolean flag example](https://github.com/Unleash/unleash-openfeature-ruby-provider/blob/main/examples/boolean_flag.rb) with your Unleash URL and API token:

```bash
bundle exec ruby examples/boolean_flag.rb \
  --url '<YOUR_UNLEASH_URL>/api' \
  --api-key "$UNLEASH_API_KEY" \
  --flag-key my-feature \
  --targeting-key user-123
```