Skip to main content

Initialization

The Eppo Ruby SDK is easy to initialize while offering robust customization options, making it adaptable to various use cases such as offline mode, custom caching requirements, and ultra-low-latency initialization.

Initialize the SDK​

To complete basic initialization, you only need to provide an SDK key. Create an SDK key if you don't already have one.

require 'eppo_client'

config = EppoClient::Config.new('<SDK-KEY>')
EppoClient::init(config)

Use the SDK instance​

After initialization, you can get an instance of the client using Ruby's singleton pattern:

client = EppoClient::Client.instance

Advanced Configuration​

Basic initialization is great for most use cases, but the SDK provides options that you can use during initialization to customize the behavior of the SDK.

Initialization Options​

The Config class accepts the following options:

api_keyStringDefault: nil

Your SDK key from the Eppo dashboard. Required.

assignment_loggerAssignmentLoggerDefault: nil

A callback that sends each assignment to your data warehouse. Required only for experiment analysis.

poll_interval_secondsIntegerDefault: 30

The interval in seconds at which the SDK polls for configuration updates. If set to nil, polling is disabled.

poll_jitter_secondsIntegerDefault: 30

The jitter in seconds to add to the poll interval to prevent thundering herd problems.

is_graceful_modeBooleanDefault: true

When true, gracefully handles all exceptions within the assignment function and returns the default value.

initial_configurationConfigurationDefault: nil

If set, the client will use this configuration until it fetches a fresh one.

For example, to poll for changes every minute with jitter:

config = EppoClient::Config.new(
  '<SDK-KEY>',
  assignment_logger: MyLogger.new,
  poll_interval_seconds: 60,
  poll_jitter_seconds: 10
)
EppoClient::init(config)

Configuration Caching​

The SDK can cache previously loaded configurations for use in future sessions. This makes the SDK initialize faster and provides resilience against network issues.

Advanced Configuration Control​

The Ruby SDK exposes an API to allow manual control over configuration:

# Get current configuration
config = client.get_configuration

# Access specific parts of the configuration
flags_config = config.get_flags_configuration
flag_keys = config.get_flag_keys
bandit_keys = config.get_bandit_keys

This API can be used for debugging or advanced optimizations like:

  • Caching configuration
  • Faster client-side initialization from server configuration
  • Debugging flag assignments

Usage in Serverless Environments​

The default periodic polling setup is suitable for most cases but may not be efficient in short-lived serverless environments like AWS Lambda, where a new configuration is fetched on every function call.

For serverless environments, you can:

  1. Disable polling:
config = EppoClient::Config.new(
  '<SDK-KEY>',
  poll_interval_seconds: nil  # Disable polling
)
  1. Manually control configuration updates:
# Initialize with a cached configuration
cached_config = get_cached_configuration  # Your caching logic
config = EppoClient::Config.new(
  '<SDK-KEY>',
  poll_interval_seconds: nil,
  initial_configuration: cached_config
)
EppoClient::init(config)

# Later, update configuration manually if needed
client = EppoClient::Client.instance
new_config = fetch_new_configuration  # Your update logic
client.set_configuration(new_config)

Example Configurations​

Here are some common configuration patterns based on different needs:

Prioritize Flag Value Freshness​

If you want to always use the latest flag values:

config = EppoClient::Config.new(
  '<SDK-KEY>',
  poll_interval_seconds: 30,  # Poll frequently
  poll_jitter_seconds: 5,
  is_graceful_mode: false  # Fail fast if there are issues
)

Prioritize Fast Initialization​

If you want to optimize for quick initialization:

cached_config = get_cached_configuration  # Your caching logic
config = EppoClient::Config.new(
  '<SDK-KEY>',
  poll_interval_seconds: 300,  # Poll less frequently
  initial_configuration: cached_config,
  is_graceful_mode: true  # Use default values if there are issues
)

Offline Mode​

For completely offline operation:

offline_config = get_offline_configuration  # Your configuration source
config = EppoClient::Config.new(
  '<SDK-KEY>',
  poll_interval_seconds: nil,  # Disable polling
  initial_configuration: offline_config
)