Options
All
  • Public
  • Public/Protected
  • All
Menu

The LaunchDarkly SDK client object.

Applications should configure the client at page load time and reuse the same instance.

For more information, see the SDK Reference Guide.

Hierarchy

  • LDClientBase
    • LDClient

Index

Methods

allFlags

  • Returns a map of all available flags to the current user's values.

    Returns LDFlagSet

    An object in which each key is a feature flag key and each value is the flag value. Note that there is no way to specify a default value for each flag as there is with variation, so any flag that cannot be evaluated will have a null value.

close

  • close(onDone?: undefined | (() => void)): Promise<void>
  • Shuts down the client and releases its resources, after delivering any pending analytics events. After the client is closed, all calls to variation will return default values, and it will not make any requests to LaunchDarkly.

    Parameters

    • Optional onDone: undefined | (() => void)

      A function which will be called when the operation completes. If omitted, you will receive a Promise instead.

    Returns Promise<void>

    If you provided a callback, then nothing. Otherwise, a Promise which resolves once closing is finished. It will never be rejected.

flush

  • flush(onDone?: undefined | (() => 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.

    Parameters

    • Optional onDone: undefined | (() => void)

      A function which will be called when the flush completes. If omitted, you will receive a Promise instead.

    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.

getUser

  • Returns the client's current user.

    This is the user that was most recently passed to identify, or, if identify has never been called, the initial user specified when the client was created.

    Returns LDUser

identify

  • Identifies a user to LaunchDarkly.

    Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current user state, which is set at initialization time. You only need to call identify() if the user has changed since then.

    Changing the current user also causes all feature flag values to be reloaded. Until that has finished, calls to variation will still return flag values for the previous user. You can use a callback or a Promise to determine when the new flag values are available.

    Parameters

    • user: LDUser

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

    • Optional hash: undefined | string

      The signed user key if you are using Secure Mode.

    • Optional onDone: undefined | ((err: Error | null, flags: LDFlagSet | null) => void)

      A function which will be called as soon as the flag values for the new user are available, with two parameters: an error value (if any), and an LDFlagSet containing the new values (which can also be obtained by calling variation). If the callback is omitted, you will receive a Promise instead.

    Returns Promise<LDFlagSet>

    If you provided a callback, then nothing. Otherwise, a Promise which resolve once the flag values for the new user are available, providing an LDFlagSet containing the new values (which can also be obtained by calling variation).

off

  • off(key: string, callback: (...args: any[]) => void, context?: any): void
  • Deregisters an event listener. See on for the available event types.

    Parameters

    • key: string

      The name of the event for which to stop listening.

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

      The function to deregister.

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

          • Rest ...args: any[]

          Returns void

    • Optional context: any

      The this context for the callback, if one was specified for on.

    Returns void

on

  • on(key: string, callback: (...args: any[]) => void, context?: any): void
  • Registers an event listener.

    The following event names (keys) are used by the cliet:

    • "ready": The client has finished starting up. This event will be sent regardless of whether it successfully connected to LaunchDarkly, or encountered an error and had to give up; to distinguish between these cases, see below.
    • "initialized": The client successfully started up and has valid feature flag data. This will always be accompanied by "ready".
    • "failed": The client encountered an error that prevented it from connecting to LaunchDarkly, such as an invalid environment ID. All flag evaluations will therefore receive default values. This will always be accompanied by "ready".
    • "error": General event for any kind of error condition during client operation. The callback parameter is an Error object. If you do not listen for "error" events, then the errors will be logged with console.log().
    • "change": The client has received new feature flag data. This can happen either because you have switched users with identify, or because the client has a stream connection and has received a live change to a flag value (see below). The callback parameter is an LDFlagChangeset.
    • "change:FLAG-KEY": The client has received a new value for a specific flag whose key is FLAG-KEY. The callback receives two parameters: the current (new) flag value, and the previous value. This is always accompanied by a general "change" event as described above; you can listen for either or both.

    The "change" and "change:FLAG-KEY" events have special behavior: by default, the client will open a streaming connection to receive live changes if and only if you are listening for one of these events. This behavior can be overridden by setting streaming in LDOptions or calling LDClient.setStreaming.

    Parameters

    • key: string

      The name of the event for which to listen.

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

      The function to execute when the event fires. The callback may or may not receive parameters, depending on the type of event; see [[LDEventSignature]].

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

          • Rest ...args: any[]

          Returns void

    • Optional context: any

      The this context to use for the callback.

    Returns void

setStreaming

  • setStreaming(value?: undefined | false | true): void
  • Specifies whether or not to open a streaming connection to LaunchDarkly for live flag updates.

    If this is true, the client will always attempt to maintain a streaming connection; if false, it never will. If you leave the value undefined (the default), the client will open a streaming connection if you subscribe to "change" or "change:flag-key" events (see LDClient.on).

    This can also be set as the streaming property of LDOptions.

    Parameters

    • Optional value: undefined | false | true

    Returns void

track

  • track(key: string, data?: any): void
  • Track page events to use in goals or A/B tests.

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

    Parameters

    • key: string

      The name of the event, which may correspond to a goal in A/B tests.

    • Optional data: any

      Additional information to associate with the event.

    Returns void

variation

  • Determines the variation of a feature flag for the current user.

    In the client-side JavaScript SDKs, this is always a fast synchronous operation because all of the feature flag values for the current user have already been loaded into memory.

    Parameters

    • key: string

      The unique key of the feature flag.

    • Optional defaultValue: LDFlagValue

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

    Returns LDFlagValue

    The flag's value.

variationDetail

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

    Note that this will only work if you have set evaluationExplanations to true in LDOptions. Otherwise, the reason property of the result will be null.

    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.

    • Optional defaultValue: LDFlagValue

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

    Returns LDEvaluationDetail

    An LDEvaluationDetail object containing the value and explanation.

waitForInitialization

  • waitForInitialization(): Promise<void>
  • 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 irrevocably failed (for instance, if it detects that the SDK key is invalid).

        // using Promise then() and catch() handlers
        client.waitForInitialization().then(() => {
            doSomethingWithSuccessfullyInitializedClient();
        }).catch(err => {
            doSomethingForFailedStartup(err);
        });
    
        // using async/await
        try {
            await client.waitForInitialization();
            doSomethingWithSuccessfullyInitializedClient();
        } catch (err) {
            doSomethingForFailedStartup(err);
        }

    It is important that you handle the rejection case; otherwise it will become an unhandled Promise rejection, which is a serious error on some platforms. The Promise is not created unless you request it, so if you never call waitForInitialization() then you do not have to worry about unhandled rejections.

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

    Returns Promise<void>

    A Promise that will be resolved if the client initializes successfully, or rejected if it fails.

waitUntilGoalsReady

  • waitUntilGoalsReady(): Promise<void>
  • Allows you to wait until the client has received goals data from LaunchDarkly.

    This is only relevant if you are using A/B testing features like click events and pageview events; until the client has received the configuration for these (which happens immediately after the initial request for feature flags), click events and pageview events will not work, so you may wish to wait using this method before doing anything that you expect to generate those events.

    The returned Promise will be resolved once the client has received goals data. If you prefer to use event handlers rather than Promises, you can listen on the client for a "goalsReady" event instead.

    Returns Promise<void>

    A Promise containing the initialization state of the client.

waitUntilReady

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

    The returned Promise will be resolved once the client has either successfully initialized or failed to initialize (e.g. due to an invalid environment key or a server error). It will never be rejected.

        // using a Promise then() handler
        client.waitUntilReady().then(() => {
            doSomethingWithClient();
        });
    
        // using async/await
        await client.waitUntilReady();
        doSomethingWithClient();

    If you want to distinguish between these success and failure conditions, use waitForInitialization instead.

    If you prefer to use event listeners (on) rather than Promises, you can listen on the client for a "ready" event, which will be fired in either case.

    Returns Promise<void>

    A Promise that will be resolved once the client is no longer trying to initialize.

Generated using TypeDoc