Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface LDClient

The LaunchDarkly SDK client object.

Create this object with init. Applications should configure the client at startup time and continue to use it throughout the lifetime of the application, rather than creating instances on the fly.

Note that LDClient inherits from EventEmitter, so you can use the standard on(), once(), and off() methods to receive events. The standard EventEmitter methods are not documented here; see the Node API documentation. For a description of events you can listen for, see on.

see

SDK Reference Guide

Hierarchy

  • EventEmitter
    • LDClient

Index

Properties

Methods

Properties

Readonly bigSegmentStoreStatusProvider

bigSegmentStoreStatusProvider: BigSegmentStoreStatusProvider

A mechanism for tracking the status of a Big Segment store.

This object has methods for checking whether the Big Segment store is (as far as the SDK knows) currently operational and tracking changes in this status. See {@link interfaces.BigSegmentStoreStatusProvider} for more about this functionality.

Methods

allFlagsState

  • Builds an object that encapsulates the state of all feature flags for a given context. This includes the flag values and also metadata that can be used on the front end. This method does not send analytics events back to LaunchDarkly.

    The most common use case for this method is to bootstrap a set of client-side feature flags from a back-end service. Call the toJSON() method of the returned object to convert it to the data structure used by the client-side SDK.

    Parameters

    Returns Promise<LDFlagsState>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result as an LDFlagsState.

close

  • close(): void

  • Discards all network connections, background tasks, and other resources held by the client.

    Do not attempt to use the client after calling this method.

    Returns void

flush

  • flush(callback?: (err: Error, res: boolean) => void): Promise<void>

  • Flushes all pending analytics events.

    Normally, batches of events are delivered in the background at intervals determined by the flushInterval property of LDOptions. Calling flush() triggers an immediate delivery. However, like Node I/O in general, this is still an asynchronous operation so you must still use Promise chaining, a callback, or async/await to detect when it has finished or failed.

    Parameters

    • Optional callback: (err: Error, res: boolean) => void

      A function which will be called when the flush completes (meaning that all pending events have been delivered to LaunchDarkly). If omitted, you will receive a Promise instead.

        • (err: Error, res: boolean): void

        • Parameters

          • err: Error
          • res: boolean

          Returns void

    Returns Promise<void>

    If you provided a callback, then nothing. Otherwise, a Promise which resolves once flushing is finished. Note that the Promise will be rejected if the HTTP request fails, so be sure to attach a rejection handler to it.

identify

  • Identifies a context to LaunchDarkly.

    This simply creates an analytics event that will transmit the given user properties to LaunchDarkly, so that the context will be visible on your dashboard even if you have not evaluated any flags for that user. It has no other effect.

    If the context is omitted or has no key, the client will log a warning and will not send an event.

    Parameters

    • context: LDContext

      The context properties. Must contain at least the key property.

    Returns void

initialized

  • initialized(): boolean

  • Tests whether the client has completed initialization.

    If this returns false, it means that the client has not yet successfully connected to LaunchDarkly. It might still be in the process of starting up, or it might be attempting to reconnect after an unsuccessful attempt, or it might have received an unrecoverable error (such as an invalid SDK key) and given up.

    Returns boolean

    True if the client has successfully initialized.

isOffline

  • isOffline(): boolean

  • Tests whether the client is configured in offline mode.

    Returns boolean

    True if the offline property is true in your LDOptions.

on

  • on(event: string | symbol, listener: (...args: any[]) => void): LDClient

  • Registers an event listener that will be called when the client triggers some type of event.

    This is the standard on method inherited from Node's EventEmitter; see the Node API docs for more details on how to manage event listeners. Here is a description of the event types defined by LDClient.

    • "ready": Sent only once, when the client has successfully connected to LaunchDarkly. Alternately, you can detect this with waitForInitialization.
    • "failed": Sent only once, if the client has permanently failed to connect to LaunchDarkly. Alternately, you can detect this with waitForInitialization.
    • "error": Contains an error object describing some abnormal condition that the client has detected (such as a network error).
    • "update": The client has received a change to a feature flag. The event parameter is an object containing a single property, key, the flag key. Note that this does not necessarily mean the flag's value has changed for any particular context, only that some part of the flag configuration was changed.
    • "update:KEY": The client has received a change to the feature flag whose key is KEY. This is the same as "update" but allows you to listen for a specific flag.

    Parameters

    • event: string | symbol

      the name of the event to listen for

    • listener: (...args: any[]) => void

      the function to call when the event happens

        • (...args: any[]): void

        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns LDClient

secureModeHash

  • Computes an HMAC signature of a context signed with the client's SDK key.

    For more information, see the JavaScript SDK Reference Guide on Secure mode.

    Parameters

    Returns string

    The hash string.

track

  • track(key: string, context: LDContext, data?: any, metricValue?: number): void

  • Tracks that a context performed an event.

    LaunchDarkly automatically tracks pageviews and clicks that are specified in the Metrics section of the dashboard. This can be used to track custom metrics (goals) or other events that do not currently have metrics.

    Note that event delivery is asynchronous, so the event may not actually be sent until later; see flush.

    If the context is omitted or has no key, the client will log a warning and will not send an event.

    Parameters

    • key: string

      The name of the event, which may correspond to a metric in experiments.

    • context: LDContext

      The context to track.

    • Optional data: any

      Optional additional information to associate with the event.

    • Optional metricValue: number

      A numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be returned as part of the custom event for Data Export.

    Returns void

variation

  • variation(key: string, context: LDContext, defaultValue: any, callback?: (err: any, res: any) => void): Promise<any>

  • Determines the variation of a feature flag for a context.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: any

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    • Optional callback: (err: any, res: any) => void

      A Node-style callback to receive the result value. If omitted, you will receive a Promise instead.

        • (err: any, res: any): void

        • Parameters

          • err: any
          • res: any

          Returns void

    Returns Promise<any>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result value.

variationDetail

  • Determines the variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: any

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    • Optional callback: (err: any, res: LDEvaluationDetail) => void

      A Node-style callback to receive the result (as an LDEvaluationDetail). If omitted, you will receive a Promise instead.

    Returns Promise<LDEvaluationDetail>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result (as an LDEvaluationDetail).

waitForInitialization

  • waitForInitialization(): Promise<LDClient>

  • Returns a Promise that tracks the client's initialization state.

    The Promise will be resolved if the client successfully initializes, or rejected if client initialization has failed unrecoverably (for instance, if it detects that the SDK key is invalid). Keep in mind that unhandled Promise rejections can be fatal in Node, so if you call this method, be sure to attach a rejection handler to it (or, if using async/await, a catch block).

    Note that you can also use event listeners (on) for the same purpose: the event "ready" indicates success, and "failed" indicates failure.

    There is no built-in timeout for this method. If you want your code to stop waiting on the Promise after some amount of time, you could use Promise.race() or one of the several NPM helper packages that provides a standard mechanism for this. Regardless of whether you continue to wait, the SDK will still retry all connection failures indefinitely unless it gets an unrecoverable error as described above.

    example

    This example shows use of Promise chaining methods for specifying handlers:

      client.waitForInitialization().then(() => {
        // do whatever is appropriate if initialization has succeeded
      }).catch(err => {
        // do whatever is appropriate if initialization has failed
      })
    example

    This example shows use of async/await syntax for specifying handlers:

      try {
        await client.waitForInitialization();
        // do whatever is appropriate if initialization has succeeded
      } catch (err) {
        // do whatever is appropriate if initialization has failed
      }

    Returns Promise<LDClient>

    A Promise that will be resolved if the client initializes successfully, or rejected if it fails. If successful, the result is the same client object.

Generated using TypeDoc