Ruby SDK

gem install kameleoon-client-ruby

# external settings file
require "kameleoon"

site_code = "a8st4f59bj"

kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code)

kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config_path: '/etc/kameleoon/client-ruby.yaml')

# internal KameleoonClientConfig object
require 'kameleoon'
require 'kameleoon/kameleoon_client_config'

kameleoon_config = Kameleoon::KameleoonClientConfig.new(
  'client_id', # required
  'client_secret', # required
  refresh_interval_minute: configuration_refresh_interval, # (in minutes) optional, default: 60 minutes
  session_duration_minute: session_duration, # (in minutes) optional, default: 30 minutes
  default_timeout_millisecond: default_timeout, # (in milliseconds) optional, default: 2000 milliseconds
  tracking_interval_millisecond: tracking_interval, # (in milliseconds) optional (1000 ms by default)
  environment: environment, # optional, possible values: "production" / "staging" / "development" / "staging", default: "production"
  top_level_domain: 'example.com',
  verbose_mode: verbose_mode, # optional, default: false
  network_domain: 'example.com' # optional
)
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)

require_relative 'boot'
require 'rails/all'
require 'kameleoon'
Bundler.require(*Rails.groups)

module App
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 6.1
	  if defined?(Rails::Server)
        config.after_initialize do
            site_code = 'a8st4f59bj'
            kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
	        config.kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)
        end
	  end
  end
end

class YourController < ApplicationController
  def index
    kameleoon_client = App::Application.config.kameleoon_client
    # Your controller code, using the kameleoon_client
  end
end

begin
  variation = kameleoon_client.get_variation(visitor_code, "new_checkout")
rescue Kameleoon::Exception::FeatureNotFound
  # The feature flag isn't in the SDK configuration: fall back to your default behavior.
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
  # The feature flag is disabled for the current environment.
rescue Kameleoon::Exception::KameleoonError => error
  # Any other SDK error.
  logger.warn("Kameleoon error: #{error.message}")
end

# In this example, `91` represents the Custom Data's index configured as a unique identifier in Kameleoon.
MAPPING_INDEX = 91
FEATURE_KEY = 'ff123'

# 1. Before the visitor is authenticated

# Retrieve the variation for an unauthenticated visitor.
# Assume `anonymous_visitor_code` is the randomly generated ID for that visitor.
anonymous_variation = kameleoon_client.get_variation(anonymous_visitor_code, FEATURE_KEY)

# 2. After the visitor is authenticated

# Assume `user_id` is the visitor code of the authenticated visitor.
kameleoon_client.add_data(anonymous_visitor_code, CustomData.new(MAPPING_INDEX, user_id))
kameleoon_client.flush(anonymous_visitor_code, instant: true)

# Indicate that `user_id` is a unique identifier.
kameleoon_client.add_data(user_id, UniqueIdentifier.new(True))

# 3. After the visitor has been authenticated

# Retrieve the variation for the `user_id`, which will match the anonymous visitor code's variation.
user_variation = kameleoon_client.get_variation(user_id, FEATURE_KEY)
is_same_variation = user_variation.key == anonymous_variation.key # true

# The `user_id` and `anonymous_visitor_code` are now linked and tracked as a single visitor.
kameleoon_client.track_conversion(user_id, 123, 10.0)

# Additionally, the linked visitors will share all fetched remote visitor data.
kameleoon_client.get_remote_visitor_data(user_id)

bucketing_key = Kameleoon::CustomData.new(index, 'new_visitor_code')

kameleoon_client.add_data(visitor_code, bucketing_key)

require 'kameleoon/logging/kameleoon_logger'

# The `NONE` log level does not allow logging.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::NONE

# The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::ERROR

# The `WARNING` log level allows logging issues which may require additional attention.
# It extends the `ERROR` log level.
# The `WARNING` log level is a default log level.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::WARNING

# The `INFO` log level allows logging general information on the SDK's internal processes.
# It extends the `WARNING` log level.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::INFO

# The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
# with more granular diagnostic output.
# This information is not intended for end-user interpretation but can be sent to our support team
# to assist with internal troubleshooting.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::DEBUG

require 'logger'
require 'kameleoon/logging/logger'

module Kameleoon
  class CustomLogger < Kameleoon::Logging::Logger
    def initialize
      @internal_logger = Logger.new(STDOUT)
    end

    def log(level, message)
      case level
      when Kameleoon::Logging::LogLevel::ERROR
        @internal_logger.error(message)
      when Kameleoon::Logging::LogLevel::WARNING
        @internal_logger.warn(message)
      when Kameleoon::Logging::LogLevel::INFO
        @internal_logger.info(message)
      when Kameleoon::Logging::LogLevel::DEBUG
        @internal_logger.debug(message)
      end
    end
  end
end


# Log level filtering is applied separately from log handling logic.
# The custom logger will only accept logs that meet or exceed the specified log level.
# Ensure the log level is set correctly.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::DEBUG # Optional, defaults to `Kameleoon::Logging::LogLevel::WARNING`.
Kameleoon::Logging::KameleoonLogger.logger = CustomLogger.new

kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config: kameleoon_config)

kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config_path: '/etc/kameleoon/client-ruby.yaml')

# Waits up to the default timeout of the client configuration
if kameleoon_client.wait_init
  # The SDK has been initialized
end

# Waits no longer than the specified timeout
if kameleoon_client.wait_init(1000)
  # The SDK has been initialized
end

ready = kameleoon_client.is_ready?

visitor_code = kameleoon_client.get_visitor_code(cookies)

feature_key = "new_checkout"
has_new_checkout = false

begin
	has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key)
	# disabling tracking
	has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
	# The user will not be counted in the experiment, but should see the reference variation.
	has_new_checkout = false
end

if has_new_checkout
	# Implement new checkout code here
end

feature_key = "new_checkout"

begin
  variation = kameleoon_client.get_variation(visitor_code, feature_key)
  # disabling tracking
  variation = kameleoon_client.get_variation(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
  # The error has occurred; the feature flag isn't found in the current configuration.
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
  # The feature flag is disabled for the environment
rescue Kameleoon::Exception::VisitorCodeInvalid
  # The visitor code you passed to the method is invalid and can't be accepted by SDK
end

# Fetch a variable value for the assigned variation
title = variation.variables['title'].value

case variation.key
when 'on'
  # Main variation key is selected for visitorCode
when 'alternative_variation'
  # Alternative variation key
else
  # Default variation key
end

begin
  variations = kameleoon_client.get_variations(visitor_code)
  # only active variations
  variations = kameleoon_client.get_variations(visitor_code, only_active: true)
  # disable tracking
  variations = kameleoon_client.get_variations(visitor_code, track: false)
rescue Kameleoon::Exception::VisitorCodeInvalid
  # Handle exception
end

experiment_id = 9516
begin
  # Forcing the variation "on" for the experiment 9516 for the visitor
  kameleoon_client.set_forced_variation(visitor_code, experiment_id, 'on')

  # Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
  kameleoon_client.set_forced_variation(visitor_code, experiment_id, 'on', force_targeting: false)

  # Resetting the forced variation for the experiment 9516 for the visitor
  kameleoon_client.set_forced_variation(visitor_code, experiment_id, nil)
rescue Kameleoon::Exception::KameleoonError => ex
  # Handling the exception
end

begin
  kameleoon_client.evaluate_audiences(visitor_code)
rescue Kameleoon::Exception::KameleoonError => ex
  # Handling the exception
end

begin
  datafile = kameleoon_client.get_data_file
rescue StandardError => e
  # Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
end

visitor_code = kameleoon_client.get_visitor_code(cookies)

visitor_code = kameleoon_client.get_visitor_code(cookies, default_visitor_code)

require "kameleoon"
require "kameleoon/data"

# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))

# Add multiple data items (tracked by default)
kameleoon_client.add_data(
  visitor_code,
  Kameleoon::PageView.new("https://url.com", "title", [3]),
  Kameleoon::UserAgent("UserAgent")
)

# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
  visitor_code,
  Kameleoon::Data::PageView.new("https://url.com", "title", [3]),
  Kameleoon::Data::UserAgent.new("UserAgent"),
  track: false
)

require "kameleoon"
require "kameleoon/data"

visitor_code = kameleoon_client.get_visitor_code(cookies)

kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))
kameleoon_client.add_data(
  visitor_code,
  Kameleoon::PageView.new("https://url.com", "title", [3]),
  Kameleoon::Interest.new(0)
)
kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10, false))

kameleoon_client.flush(visitor_code) # Interval tracking (most performant way for tracking)

kameleoon_client.flush(visitor_code, instant: true) # Instant tracking

# if you operate with unique ID
kameleoon_client.add_data(Kameleoon::UniqueIdentifier.new(true))
kameleoon_client.flush(visitor_code)

kameleoon_client.get_remote_data('test') # default timeout
kameleoon_client.get_remote_data('test', 1000) # 1000 milliseconds timeout
begin
	kameleoon_client.get_remote_data('test')
rescue => e
	#catch error
end

visitor_code = 'visitorCode'

# Visitor data will be fetched and automatically added for `visitor_code`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code)  # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000)  # 1 second timeout

# If you only want to fetch data and add it yourself manually, set `add_data` to `false`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, add_data: false)  # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000, add_data: false)  # 1 second timeout

# If you want to fetch custom list of data types
filter = RemoteVisitorDataFilter(25, customData: false, conversions: true, experiments: true)
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, filter: filter)

# If you want to the SDK to link the extracted data with the visitor associated with the specified identifier
kameleoon_client.add_data(Kameleoon::UniqueIdentifier.new(true))
data_array = kameleoon_client.get_remote_visitor_data(visitor_code)

begin
	warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index)  # default timeout
	warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, 1000)  # 1 second timeout

	warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key: warehouse_key)  # default timeout
	warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, 1000, warehouse_key: warehouse_key)  # 1 second timeout

	# Your custom code
rescue => e
	# Handle exception
end

visitor_code = kameleoon_client.get_visitor_code(cookies)
kameleoon_client.set_legal_consent(visitor_code, true, cookies)

require "kameleoon"
require "kameleoon/data/page_view"
require "kameleoon/data/browser"
require "kameleoon/data/conversion"

visitor_code = kameleoon_client.get_visitor_code(cookies)
goal_id = 83023

kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)

# Add metadata
cd = Kameleoon::CustomData.new(1, "metadata");
kameleoon_client.track_conversion(visitorCode, goalId, metadata: [cd])

engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)

kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))

kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::SAFARI, 10.0))

kameleoon_client.add_data(visitor_code, Kameleoon::PageView.new("https://url.com", "title", [3]))

kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10))

kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(33, 0, true))

kameleoon_client.add_data(
  visitor_code,
  Kameleoon::Conversion.new(34, metadata: [
    Kameleoon::CustomData.new(3, 'metadata1', 'md2'),
    Kameleoon::CustomData.new(5, 'md3'),
  ])
)

custom_data = Kameleoon::CustomData.new(1, 'value')

# With several values
custom_data = Kameleoon::CustomData.new(1, 'value1', 'value2')

# To set the 'overwrite' flag to false
custom_data = Kameleoon::CustomData.new(1, 'value', overwrite: false)

# To use a name instead of the index
custom_data = Kameleoon::CustomData.new('my-custom-data', 'value')

# From hash
custom_data = Kameleoon::CustomData.new({ 'id' => 1, 'values' => ['value1', 'value2'] })

# From hash with the 'overwrite' flag set to false
custom_data = Kameleoon::CustomData.new({ 'id' => 1, 'values' => ['value'], 'overwrite' => false })

# From hash with a name instead of the index
custom_data = Kameleoon::CustomData.new({ 'name' => 'my-custom-data', 'values' => ['value'] })

kameleoon_client.add_data(visitor_code, custom_data)

kameleoon_client.add_data(visitor_code, Kameleoon::Device.new(Kameleoon::DeviceType::DESKTOP))

kameleoon_client.add_data(visitor_code, Kameleoon::UserAgent.new("Your User Agent"))

kameleoon_client.add_data(visitorCode, Kameleoon::UniqueIdentifier.new(true))

kameleoon_client.add_data(visitor_code, Kameleoon::OperatingSystem.new(Kameleoon::OperatingSystemType::ANDROID))

cookie = Kameleoon::Cookie.new({ "k1" => "v1", "k2" => "v2" })
kameleoon_client.add_data(visitor_code, cookie)

kameleoon_client.add_data(visitor_code, Kameleoon::Geolocation.new("France", "Île-de-France", "Paris"))

kameleoon_client_sdk.add_data(visitorCode, Kameleoon::ApplicationVersion.new("10")) # major

kameleoon_client_sdk.add_data(visitorCode, Kameleoon::ApplicationVersion.new("10.20")) # major.minor

kameleoon_client_sdk.add_data(visitorCode, Kameleoon::ApplicationVersion.new("10.20.30")) # major.minor.patch

# Retrieves the hash of feature flags from the DataFile.
# The hash is keyed by feature flag identifiers, with each value being a FeatureFlag object.
feature_flags = datafile.feature_flags

# Retrieves the last modification timestamp of the DataFile.
# The value is an Integer representing milliseconds since the Unix epoch.
date_modified = datafile.date_modified

# Check whether the feature flag is enabled in the current environment
is_environment_enabled = feature_flag.environment_enabled

# Retrieve the key of the default variation
default_variation_key = feature_flag.default_variation_key

# Retrieve the default variation object
default_variation = feature_flag.default_variation

# Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
variations = feature_flag.variations

# Retrieve all targeting rules associated with the feature flag
rules = feature_flag.rules

# Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
variations = rule.variations

# Retrieving the variation name
variation_name = variation.name

# Retrieving the variation key
variation_key = variation.key

# Retrieving the variation id
variation_id = variation.id

# Retrieving the experiment id
experiment_id = variation.experiment_id

# Retrieving the variables map
variables = variation.variables

# Retrieving the variables map
variables = variation.variables

# Variable type can be retrieved for further processing
type = variables["isDiscount"].type

# Retrieving the variable value by key
is_discount = variables["isDiscount"].value

# Variable value can be of different types (e.g., String)
title = variables["title"].value

visitor_code = kameleoon_client.get_visitor_code(cookies)

feature_key = "feature_key"
variation_key = ""

begin
	variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
	case variation_key
	when 'on'
		# main variation key is selected for visitorCode
	when 'alternative_variation'
		# alternative variation key
	else
		# default variation key
	end
rescue Kameleoon::Exception::FeatureNotFound
	# The user will not be counted in the experiment, but should see the reference variation.
rescue Kameleoon::Exception::VisitorCodeInvalid
	# The visitor code you passed to the method isn't valid and can't be accepted by SDK.
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
	# The feature is disabled for the environment.
end

active_feature_flag_list = kameleoon_client.get_active_feature_list_for_visitor(visitor_code)

active_features = kameleoon_client.get_active_features(visitor_code)

visitor_code = kameleoon_client.get_visitor_code(cookies)

feature_key = "feature_key"
variation_key = ""
variable_name = "variable_name"

begin
	variable_value = kameleoon_client.get_feature_variable(visitor_code, feature_key, variable_name)
	# your custom code depending of variable_value, e.g.
	case variable_value
	when 'value-1'
		# your custom code if variable == 'value-1'
	when 'value-2'
		# your custom code if variable == 'value-2'
	end
rescue Kameleoon::Exception::FeatureNotFound
	# The user will not be counted in the experiment, but should see the reference variation.
rescue Kameleoon::Exception::FeatureVariableNotFound
	# Requested variable not defined in Kameleoon
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
	# The feature is disabled for the environment.
rescue Kameleoon::Exception::VisitorCodeInvalid
	# The visitor code you passed to the method isn't valid and can't be accepted by SDK.
end

feature_key = "test_feature_variables"
variation_key = "on"

begin
	data = kameleoon_client.get_feature_variation_variables(feature_key, variation_key)
rescue Kameleoon::Exception::FeatureNotFound
	# The feature is not activated in Kameleoon
rescue Kameleoon::Exception::FeatureVariationNotFound
	# Requested variation not defined in Kameleoon
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
	# The feature is disabled for the environment.
end

feature_list = kameleoon_client.get_feature_list

kameleoon_client.on_update_configuration(
  # configuration was updated
)