Options
All
  • Public
  • Public/Protected
  • All
Menu

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

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

  • Associates two users for analytics purposes.

    This can be helpful in the situation where a person is represented by multiple LaunchDarkly users. This may happen, for example, when a person initially logs into an application-- the person might be represented by an anonymous user prior to logging in and a different user after logging in, as denoted by a different user key.

    Parameters

    • user: LDUser

      The newly identified user.

    • previousUser: LDUser

      The previously identified user.

    Returns void

  • Builds an object that encapsulates the state of all feature flags for a given user. 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(): 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(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.

  • Identifies a user to LaunchDarkly.

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

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

    Parameters

    • user: LDUser

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

    Returns void

  • 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(): boolean
  • Tests whether the client is configured in offline mode.

    Returns boolean

    True if the offline property is true in your LDOptions.

  • 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 user, 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(user: LDUser): string
  • Computes an HMAC signature of a user signed with the client's SDK key.

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

    Parameters

    • user: LDUser

      The user properties.

    Returns string

    The hash string.

  • track(key: string, user: LDUser, data?: any, metricValue?: number): void
  • Tracks that a user performed an event.

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

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

    If the user 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 goal in A/B tests.

    • user: LDUser

      The user 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(key: string, user: LDUser, defaultValue: any, callback?: (err: any, res: any) => void): Promise<any>
  • Determines the variation of a feature flag for a user.

    Parameters

    • key: string

      The unique key of the feature flag.

    • user: LDUser

      The end user requesting the flag. The client will generate an analytics event to register this user with LaunchDarkly if the user 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.

  • Determines the variation of a feature flag for a user, 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.

    • user: LDUser

      The end user requesting the flag. The client will generate an analytics event to register this user with LaunchDarkly if the user 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(): 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