Class: LaunchDarkly::LDClient
- Inherits:
-
Object
- Object
- LaunchDarkly::LDClient
- Defined in:
- lib/ldclient-rb/ldclient.rb
Overview
A client for LaunchDarkly. Client instances are thread-safe. Users should create a single client instance for the lifetime of the application.
Instance Method Summary collapse
-
#all_flags(user) ⇒ Hash
deprecated
Deprecated.
Please use #all_flags_state instead. Current versions of the client-side SDK will not generate analytics events correctly if you pass the result of
all_flags
. -
#all_flags_state(user, options = {}) ⇒ FeatureFlagsState
Returns a FeatureFlagsState object that encapsulates the state of all feature flags for a given user, including the flag values and also metadata that can be used on the front end.
-
#close ⇒ void
Releases all network connections and other resources held by the client, making it no longer usable.
-
#flush ⇒ Object
Tells the client that all pending analytics events should be delivered as soon as possible.
-
#identify(user) ⇒ void
Registers the user.
-
#initialize(sdk_key, config = Config.default, wait_for_sec = 5) ⇒ LDClient
constructor
Creates a new client instance that connects to LaunchDarkly.
-
#initialized? ⇒ Boolean
Returns whether the client has been initialized and is ready to serve feature flag requests.
-
#secure_mode_hash(user) ⇒ String
Creates a hash string that can be used by the JavaScript SDK to identify a user.
-
#toggle?(key, user, default = false) ⇒ Boolean
deprecated
Deprecated.
Use #variation instead.
-
#track(event_name, user, data = nil, metric_value = nil) ⇒ void
Tracks that a user performed an event.
-
#variation(key, user, default) ⇒ Object
Determines the variation of a feature flag to present to a user.
-
#variation_detail(key, user, default) ⇒ EvaluationDetail
Determines the variation of a feature flag for a user, like #variation, but also provides additional information about how this value was calculated.
Constructor Details
#initialize(sdk_key, config = Config.default, wait_for_sec = 5) ⇒ LDClient
Creates a new client instance that connects to LaunchDarkly. A custom configuration parameter can also supplied to specify advanced options, but for most use cases, the default configuration is appropriate.
The client will immediately attempt to connect to LaunchDarkly and retrieve
your feature flag data. If it cannot successfully do so within the time limit
specified by wait_for_sec
, the constructor will return a client that is in
an uninitialized state. See #initialized? for more details.
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 |
# File 'lib/ldclient-rb/ldclient.rb', line 35 def initialize(sdk_key, config = Config.default, wait_for_sec = 5) # Note that sdk_key is normally a required parameter, and a nil value would cause the SDK to # fail in most configurations. However, there are some configurations where it would be OK # (offline = true, *or* we are using LDD mode or the file data source and events are disabled # so we're not connecting to any LD services) so rather than try to check for all of those # up front, we will let the constructors for the data source implementations implement this # fail-fast as appropriate, and just check here for the part regarding events. if !config.offline? && config.send_events raise ArgumentError, "sdk_key must not be nil" if sdk_key.nil? end @sdk_key = sdk_key @event_factory_default = EventFactory.new(false) @event_factory_with_reasons = EventFactory.new(true) # We need to wrap the feature store object with a FeatureStoreClientWrapper in order to add # some necessary logic around updates. Unfortunately, we have code elsewhere that accesses # the feature store through the Config object, so we need to make a new Config that uses # the wrapped store. @store = Impl::FeatureStoreClientWrapper.new(config.feature_store) updated_config = config.clone updated_config.instance_variable_set(:@feature_store, @store) @config = updated_config if !@config.offline? && @config.send_events && !@config.diagnostic_opt_out? diagnostic_accumulator = Impl::DiagnosticAccumulator.new(Impl::DiagnosticAccumulator.create_diagnostic_id(sdk_key)) else diagnostic_accumulator = nil end if @config.offline? || !@config.send_events @event_processor = NullEventProcessor.new else @event_processor = EventProcessor.new(sdk_key, config, nil, diagnostic_accumulator) end if @config.use_ldd? @config.logger.info { "[LDClient] Started LaunchDarkly Client in LDD mode" } return # requestor and update processor are not used in this mode end data_source_or_factory = @config.data_source || self.method(:create_default_data_source) if data_source_or_factory.respond_to? :call # Currently, data source factories take two parameters unless they need to be aware of diagnostic_accumulator, in # which case they take three parameters. This will be changed in the future to use a less awkware mechanism. if data_source_or_factory.arity == 3 @data_source = data_source_or_factory.call(sdk_key, @config, diagnostic_accumulator) else @data_source = data_source_or_factory.call(sdk_key, @config) end else @data_source = data_source_or_factory end ready = @data_source.start if wait_for_sec > 0 ok = ready.wait(wait_for_sec) if !ok @config.logger.error { "[LDClient] Timeout encountered waiting for LaunchDarkly client initialization" } elsif !@data_source.initialized? @config.logger.error { "[LDClient] LaunchDarkly client initialization failed" } end end end |
Instance Method Details
#all_flags(user) ⇒ Hash
Please use #all_flags_state instead. Current versions of the
client-side SDK will not generate analytics events correctly if you pass the
result of all_flags
.
Returns all feature flag values for the given user.
291 292 293 |
# File 'lib/ldclient-rb/ldclient.rb', line 291 def all_flags(user) all_flags_state(user).values_map end |
#all_flags_state(user, options = {}) ⇒ FeatureFlagsState
Returns a FeatureFlagsState object that encapsulates the state of all feature flags for a given user, including the flag values and also metadata that can be used on the front end. This method does not send analytics events back to LaunchDarkly.
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 |
# File 'lib/ldclient-rb/ldclient.rb', line 312 def all_flags_state(user, ={}) return FeatureFlagsState.new(false) if @config.offline? unless user && !user[:key].nil? @config.logger.error { "[LDClient] User and user key must be specified in all_flags_state" } return FeatureFlagsState.new(false) end begin features = @store.all(FEATURES) rescue => exn Util.log_exception(@config.logger, "Unable to read flags for all_flags_state", exn) return FeatureFlagsState.new(false) end state = FeatureFlagsState.new(true) client_only = [:client_side_only] || false with_reasons = [:with_reasons] || false details_only_if_tracked = [:details_only_for_tracked_flags] || false features.each do |k, f| if client_only && !f[:clientSide] next end begin result = evaluate(f, user, @store, @config.logger, @event_factory_default) state.add_flag(f, result.detail.value, result.detail.variation_index, with_reasons ? result.detail.reason : nil, details_only_if_tracked) rescue => exn Util.log_exception(@config.logger, "Error evaluating flag \"#{k}\" in all_flags_state", exn) state.add_flag(f, nil, nil, with_reasons ? { kind: 'ERROR', errorKind: 'EXCEPTION' } : nil, details_only_if_tracked) end end state end |
#close ⇒ void
This method returns an undefined value.
Releases all network connections and other resources held by the client, making it no longer usable.
352 353 354 355 356 357 |
# File 'lib/ldclient-rb/ldclient.rb', line 352 def close @config.logger.info { "[LDClient] Closing LaunchDarkly client..." } @data_source.stop @event_processor.stop @store.stop end |
#flush ⇒ Object
Tells the client that all pending analytics events should be delivered as soon as possible.
When the LaunchDarkly client generates analytics events (from #variation, #variation_detail,
#identify, or #track), they are queued on a worker thread. The event thread normally
sends all queued events to LaunchDarkly at regular intervals, controlled by the
Config#flush_interval option. Calling flush
triggers a send without waiting for the
next interval.
Flushing is asynchronous, so this method will return before it is complete. However, if you call #close, events are guaranteed to be sent before that method returns.
113 114 115 |
# File 'lib/ldclient-rb/ldclient.rb', line 113 def flush @event_processor.flush end |
#identify(user) ⇒ void
This method returns an undefined value.
Registers the user. This method simply creates an analytics event containing the user properties, so that LaunchDarkly will know about that user if it does not already.
Calling #variation or #variation_detail also sends the user information to LaunchDarkly (if events are enabled), so you only need to use #identify if you want to identify the user without evaluating a flag.
Note that event delivery is asynchronous, so the event may not actually be sent until later; see #flush.
241 242 243 244 245 246 247 248 |
# File 'lib/ldclient-rb/ldclient.rb', line 241 def identify(user) if !user || user[:key].nil? @config.logger.warn("Identify called with nil user or nil user key!") return end sanitize_user(user) @event_processor.add_event(@event_factory_default.new_identify_event(user)) end |
#initialized? ⇒ Boolean
Returns whether the client has been initialized and is ready to serve feature flag requests.
If this returns false, it means that the client did not succeed in connecting to LaunchDarkly within the time limit that you specified in the constructor. It could still succeed in connecting at a later time (on another thread), or it could have given up permanently (for instance, if your SDK key is invalid). In the meantime, any call to #variation or #variation_detail will behave as follows:
It will check whether the feature store already contains data (that is, you are using a database-backed store and it was populated by a previous run of this application). If so, it will use the last known feature flag data.
Failing that, it will return the value that you specified for the
default
parameter of #variation or #variation_detail.
158 159 160 |
# File 'lib/ldclient-rb/ldclient.rb', line 158 def initialized? @config.offline? || @config.use_ldd? || @data_source.initialized? end |
#secure_mode_hash(user) ⇒ String
Creates a hash string that can be used by the JavaScript SDK to identify a user. For more information, see Secure mode.
136 137 138 |
# File 'lib/ldclient-rb/ldclient.rb', line 136 def secure_mode_hash(user) OpenSSL::HMAC.hexdigest("sha256", @sdk_key, user[:key].to_s) end |
#toggle?(key, user, default = false) ⇒ Boolean
Use #variation instead.
Returns the flag value.
124 125 126 127 |
# File 'lib/ldclient-rb/ldclient.rb', line 124 def toggle?(key, user, default = false) @config.logger.warn { "[LDClient] toggle? is deprecated. Use variation instead" } variation(key, user, default) end |
#track(event_name, user, data = nil, metric_value = nil) ⇒ void
This method returns an undefined value.
Tracks that a user performed an event. This method creates a "custom" analytics event containing the specified event name (key), user properties, and optional data.
Note that event delivery is asynchronous, so the event may not actually be sent until later; see #flush.
As of this version’s release date, the LaunchDarkly service does not support the metricValue
parameter. As a result, specifying metricValue
will not yet produce any different behavior
from omitting it. Refer to the SDK reference guide
for the latest status.
272 273 274 275 276 277 278 279 |
# File 'lib/ldclient-rb/ldclient.rb', line 272 def track(event_name, user, data = nil, metric_value = nil) if !user || user[:key].nil? @config.logger.warn("Track called with nil user or nil user key!") return end sanitize_user(user) @event_processor.add_event(@event_factory_default.new_custom_event(event_name, user, data, metric_value)) end |
#variation(key, user, default) ⇒ Object
Determines the variation of a feature flag to present to a user.
At a minimum, the user hash should contain a :key
, which should be the unique
identifier for your user (or, for an anonymous user, a session identifier or
cookie).
Other supported user attributes include IP address, country code, and an arbitrary hash of custom attributes. For more about the supported user properties and how they work in LaunchDarkly, see Targeting users.
The optional :privateAttributeNames
user property allows you to specify a list of
attribute names that should not be sent back to LaunchDarkly.
Private attributes
can also be configured globally in Config.
195 196 197 |
# File 'lib/ldclient-rb/ldclient.rb', line 195 def variation(key, user, default) evaluate_internal(key, user, default, @event_factory_default).value end |
#variation_detail(key, user, default) ⇒ EvaluationDetail
Determines the variation of a feature flag for a user, like #variation, but also provides additional information about how this value was calculated.
The return value of variation_detail
is an EvaluationDetail object, which has
three properties: the result value, the positional index of this value in the flag's
list of variations, and an object describing the main reason why this value was
selected. See EvaluationDetail for more on these properties.
Calling variation_detail
instead of variation
also causes the "reason" data to
be included in analytics events, if you are capturing detailed event data for this flag.
For more information, see the reference guide on Evaluation reasons.
222 223 224 |
# File 'lib/ldclient-rb/ldclient.rb', line 222 def variation_detail(key, user, default) evaluate_internal(key, user, default, @event_factory_with_reasons) end |