Class: LaunchDarkly::LDClient

Inherits:
Object
  • Object
show all
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

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.

Parameters:

  • sdk_key (String) —

    the SDK key for your LaunchDarkly account

  • config (Config) (defaults to: Config.default) —

    an optional client configuration object

  • wait_for_sec (Float) (defaults to: 5) —

    maximum time (in seconds) to wait for initialization



32
33
34
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
 
# File 'lib/ldclient-rb/ldclient.rb', line 32

def initialize(sdk_key, config = Config.default, wait_for_sec = 5)
  @sdk_key = sdk_key

  # 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
    @event_processor = NullEventProcessor.new
  else
    @event_processor = EventProcessor.new(sdk_key, config)
  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
    @data_source = data_source_or_factory.call(sdk_key, @config)
  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

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.

Returns all feature flag values for the given user.

Parameters:

  • user (Hash) —

    The end user requesting the feature flags

Returns:

  • (Hash) —

    a hash of feature flag keys to values



252
253
254
 
# File 'lib/ldclient-rb/ldclient.rb', line 252

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.

Parameters:

  • user (Hash) —

    The end user requesting the feature flags

  • options (Hash) (defaults to: {}) —

    Optional parameters to control how the state is generated

Options Hash (options):

  • :client_side_only (Boolean) — default: false —

    True if only flags marked for use with the client-side SDK should be included in the state. By default, all flags are included.

  • :with_reasons (Boolean) — default: false —

    True if evaluation reasons should be included in the state (see #variation_detail). By default, they are not included.

  • :details_only_for_tracked_flags (Boolean) — default: false —

    True if any flag metadata that is normally only used for event generation - such as flag versions and evaluation reasons - should be omitted for any flag that does not have event tracking or debugging turned on. This reduces the size of the JSON data if you are passing the flag state to the front end.

Returns:



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/ldclient-rb/ldclient.rb', line 273

def all_flags_state(user, options={})
  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 = options[:client_side_only] || false
  with_reasons = options[:with_reasons] || false
  details_only_if_tracked = options[: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)
      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.



313
314
315
316
317
318
 
# File 'lib/ldclient-rb/ldclient.rb', line 313

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.



85
86
87
 
# File 'lib/ldclient-rb/ldclient.rb', line 85

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.

Parameters:

  • user (Hash) —

    The user to register; this can have all the same user properties described in #variation



213
214
215
216
217
218
219
 
# File 'lib/ldclient-rb/ldclient.rb', line 213

def identify(user)
  if !user || user[:key].nil?
    @config.logger.warn("Identify called with nil user or nil user key!")
    return
  end
  @event_processor.add_event(kind: "identify", key: user[:key], user: 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:

  1. 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.

  2. Failing that, it will return the value that you specified for the default parameter of #variation or #variation_detail.

Returns:

  • (Boolean) —

    true if the client has been initialized



130
131
132
 
# File 'lib/ldclient-rb/ldclient.rb', line 130

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.

Parameters:

  • user (Hash) —

    the user properties

Returns:

  • (String) —

    a hash string



108
109
110
 
# File 'lib/ldclient-rb/ldclient.rb', line 108

def secure_mode_hash(user)
  OpenSSL::HMAC.hexdigest("sha256", @sdk_key, user[:key].to_s)
end

#toggle?(key, user, default = false) ⇒ Boolean

Deprecated.

Use #variation instead.

Returns the flag value.

Parameters:

  • key (String) —

    the feature flag key

  • user (Hash) —

    the user properties

  • default (Boolean) (defaults to: false) —

    (false) the value to use if the flag cannot be evaluated

Returns:

  • (Boolean) —

    the flag value



96
97
98
99
 
# File 'lib/ldclient-rb/ldclient.rb', line 96

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) ⇒ 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.

Parameters:

  • event_name (String) —

    The name of the event

  • user (Hash) —

    The user to register; this can have all the same user properties described in #variation

  • data (Hash) —

    A hash containing any additional data associated with the event



234
235
236
237
238
239
240
 
# File 'lib/ldclient-rb/ldclient.rb', line 234

def track(event_name, user, data)
  if !user || user[:key].nil?
    @config.logger.warn("Track called with nil user or nil user key!")
    return
  end
  @event_processor.add_event(kind: "custom", key: event_name, user: user, data: data)
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.

Examples:

Basic user hash

{key: "my-user-id"}

More complete user hash

{key: "my-user-id", ip: "127.0.0.1", country: "US", custom: {customer_rank: 1000}}

User with a private attribute

{key: "my-user-id", email: "[email protected]", privateAttributeNames: ["email"]}

Parameters:

  • key (String) —

    the unique feature key for the feature flag, as shown on the LaunchDarkly dashboard

  • user (Hash) —

    a hash containing parameters for the end user requesting the flag

  • default —

    the default value of the flag; this is used if there is an error condition making it impossible to find or evaluate the flag

Returns:

  • the variation to show the user, or the default value if there's an an error



167
168
169
 
# File 'lib/ldclient-rb/ldclient.rb', line 167

def variation(key, user, default)
  evaluate_internal(key, user, default, false).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.

Parameters:

  • key (String) —

    the unique feature key for the feature flag, as shown on the LaunchDarkly dashboard

  • user (Hash) —

    a hash containing parameters for the end user requesting the flag

  • default —

    the default value of the flag; this is used if there is an error condition making it impossible to find or evaluate the flag

Returns:



194
195
196
 
# File 'lib/ldclient-rb/ldclient.rb', line 194

def variation_detail(key, user, default)
  evaluate_internal(key, user, default, true)
end