Package com.launchdarkly.sdk.android

Interface LDClientInterface

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
LDClient
public interface LDClientInterface extends Closeable
The interface for the LaunchDarkly SDK client.

To obtain a client instance, use LDClient methods such as LDClient.init(Application, LDConfig, LDContext).

  • Method Details

    • isInitialized

      boolean isInitialized()
      Checks whether the client is ready to return feature flag values. This is true if either the client has successfully connected to LaunchDarkly and received feature flags, or the client has been put into offline mode (in which case it will return only default flag values).
      Returns:
      true if the client is initialized or offline

    • isOffline

      boolean isOffline()
      Checks whether the client has been put into offline mode. This is true only if setOffline() was called, or if the configuration had LDConfig.Builder.offline(boolean) set to true, not if the client is simply offline due to a loss of network connectivity.
      Returns:
      true if the client is in offline mode

    • setOffline

      void setOffline()
      Shuts down any network connections maintained by the client and puts the client in offline mode, preventing the client from opening new network connections until setOnline() is called.

      Note: The client automatically monitors the device's network connectivity and app foreground status, so calling setOffline() or setOnline() is normally unnecessary in most situations.

    • setOnline

      void setOnline()
      Restores network connectivity for the client, if the client was previously in offline mode. This operation may be throttled if it is called too frequently.

      Note: The client automatically monitors the device's network connectivity and app foreground status, so calling setOffline() or setOnline() is normally unnecessary in most situations.

    • trackMetric

      void trackMetric(String eventName, LDValue data, double metricValue)
      Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.

      This method creates a "custom" analytics event containing the specified event name (key) the current evaluation context, optional custom data, and a numeric metric value.

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

      Parameters:
      eventName - the name of the event
      data - an LDValue containing additional data associated with the event; if not applicable, you may pass either null or LDValue.ofNull()
      metricValue - a numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics; this field will also be returned as part of the custom event for Data Export
      See Also:

    • trackData

      void trackData(String eventName, LDValue data)
      Tracks that an application-defined event occurred, and provides additional custom data.

      This method creates a "custom" analytics event containing the specified event name (key) the current evaluation context, and optional custom data. To specify a numeric metric, use trackMetric(String, LDValue, double) instead.

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

      Parameters:
      eventName - the name of the event
      data - an LDValue containing additional data associated with the event; if not applicable, you may pass either null or LDValue.ofNull()
      See Also:

    • track

      void track(String eventName)
      Tracks that an application-defined event occurred.

      This method creates a "custom" analytics event containing the specified event name (key) and the current evaluation context. You may attach other data to the event by calling trackData(String, LDValue) or trackMetric(String, LDValue, double) instead.

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

      Parameters:
      eventName - the name of the event
      See Also:

    • identify

      Future<Void> identify(LDContext context)
      Changes the current evaluation context, requests flags for that context from LaunchDarkly if we are online, and generates an analytics event to tell LaunchDarkly about the context.

      If the SDK is online, the returned Future is completed once the SDK has received feature flag values for the new context from LaunchDarkly, or received an unrecoverable error. If the SDK is offline, the returned Future is completed immediately.

      The SDK normally caches flag settings for recently used evaluation contexts; this behavior can be configured with LDConfig.Builder.maxCachedContexts(int).

      Parameters:
      context - the new evaluation context; see LDClient for more about setting the context and optionally requesting a unique key for it
      Returns:
      a Future whose success indicates the flag values for the new evaluation context have been stored locally and are ready for use
      Since:
      3.0.0

    • flush

      void flush()
      Sends all pending events to LaunchDarkly.

    • allFlags

      Map<String,LDValue> allFlags()
      Returns a map of all feature flags for the current evaluation context. No events are sent to LaunchDarkly.
      Returns:
      a map of all feature flags

    • boolVariation

      boolean boolVariation(String flagKey, boolean defaultValue)
      Returns the boolean value of a feature flag for the current evaluation context.

      If the flag variation does not have a boolean value, or if an error makes it impossible to evaluate the flag (for instance, if flagKey does not match any existing flag), defaultValue is returned.

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag
      Returns:
      value of the flag or the default value

    • boolVariationDetail

      EvaluationDetail<Boolean> boolVariationDetail(String flagKey, boolean defaultValue)
      Returns the boolean value of a feature flag for the current evaluation context, along with information about how it was calculated.

      Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

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

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag (see boolVariation(String, boolean))
      Returns:
      an EvaluationDetail object containing the value and other information
      Since:
      2.7.0

    • intVariation

      int intVariation(String flagKey, int defaultValue)
      Returns the integer value of a feature flag for the current evaluation context.

      If the flag variation has a numeric value that is not an integer, it is rounded toward zero.

      If the flag variation does not have a numeric value, or if an error makes it impossible to evaluate the flag (for instance, if flagKey does not match any existing flag), defaultValue is returned.

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag
      Returns:
      value of the flag or the default value

    • intVariationDetail

      EvaluationDetail<Integer> intVariationDetail(String flagKey, int defaultValue)
      Returns the integer value of a feature flag for the current evaluation context, along with information about how it was calculated.

      Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

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

      The behavior is otherwise identical to intVariation(java.lang.String, int).

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag (see intVariation(String, int))
      Returns:
      an EvaluationDetail object containing the value and other information
      Since:
      2.7.0

    • doubleVariation

      double doubleVariation(String flagKey, double defaultValue)
      Returns the double-precision floating-point numeric value of a feature flag for the current evaluation context.

      If the flag variation does not have a numeric value, or if an error makes it impossible to evaluate the flag (for instance, if flagKey does not match any existing flag), defaultValue is returned.

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag
      Returns:
      value of the flag or the default value

    • doubleVariationDetail

      EvaluationDetail<Double> doubleVariationDetail(String flagKey, double defaultValue)
      Returns the double-precision floating-point numeric value of a feature flag for the current evaluation context, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

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

      The behavior is otherwise identical to doubleVariation(java.lang.String, double).

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag (see doubleVariation(String, double))
      Returns:
      an EvaluationDetail object containing the value and other information.

    • stringVariation

      String stringVariation(String flagKey, String defaultValue)
      Returns the string value of a feature flag for the current evaluation context.

      If the flag variation does not have a string value, or if an error makes it impossible to evaluate the flag (for instance, if flagKey does not match any existing flag), defaultValue is returned.

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag
      Returns:
      value of the flag or the default value

    • stringVariationDetail

      EvaluationDetail<String> stringVariationDetail(String flagKey, String defaultValue)
      Returns the string value of a feature flag for the current evaluation context, along with information about how it was calculated.

      Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

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

      The behavior is otherwise identical to stringVariation(java.lang.String, java.lang.String).

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag (see stringVariation(String, String))
      Returns:
      an EvaluationDetail object containing the value and other information.
      Since:
      2.7.0

    • registerFeatureFlagListener

      void registerFeatureFlagListener(String flagKey, FeatureFlagChangeListener listener)
      Registers a FeatureFlagChangeListener to be called when the flagKey changes from its current value. If the feature flag is deleted, the listener will be unregistered.
      Parameters:
      flagKey - the flag key to attach the listener to
      listener - the listener to attach to the flag key
      See Also:

    • jsonValueVariation

      LDValue jsonValueVariation(String flagKey, LDValue defaultValue)
      Returns the value of a feature flag for the current evaluation context, which may be of any type.

      The type LDValue is used to represent any of the value types that can exist in JSON. Use LDValue methods to examine its type and value.

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag
      Returns:
      value of the flag or the default value. Result will never be null, but may be LDValue#ofNull()

    • jsonValueVariationDetail

      EvaluationDetail<LDValue> jsonValueVariationDetail(String flagKey, LDValue defaultValue)
      Returns the value of a feature flag for the current evaluation context, which may be of any type, along with information about how it was calculated.

      The type LDValue is used to represent any of the value types that can exist in JSON. Use LDValue methods to examine its type and value.

      Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

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

      The behavior is otherwise identical to jsonValueVariation(java.lang.String, com.launchdarkly.sdk.LDValue).

      Parameters:
      flagKey - key for the flag to evaluate
      defaultValue - default value in case of errors evaluating the flag (see jsonValueVariation(String, LDValue))
      Returns:
      an EvaluationDetail object containing the value and other information.

    • unregisterFeatureFlagListener

      void unregisterFeatureFlagListener(String flagKey, FeatureFlagChangeListener listener)
      Unregisters a FeatureFlagChangeListener for the flagKey.
      Parameters:
      flagKey - the flag key to remove the listener from
      listener - the listener to remove from the flag key
      See Also:

    • getConnectionInformation

      ConnectionInformation getConnectionInformation()
      Gets a ConnectionInformation object from the client representing the current state of the clients connection.
      Returns:
      An object representing the status of the connection to LaunchDarkly.

    • unregisterStatusListener

      void unregisterStatusListener(LDStatusListener LDStatusListener)
      Unregisters a LDStatusListener so it will no longer be called on connection status updates.
      Parameters:
      LDStatusListener - the listener to be removed

    • registerStatusListener

      void registerStatusListener(LDStatusListener LDStatusListener)
      Registers a LDStatusListener to be called on connection status updates.
      Parameters:
      LDStatusListener - the listener to be called on a connection status update

    • registerAllFlagsListener

      void registerAllFlagsListener(LDAllFlagsListener allFlagsListener)
      Registers a LDAllFlagsListener to be called when a flag update is processed by the SDK.
      Parameters:
      allFlagsListener - the listener to be called with a list of flag keys on a flag update

    • unregisterAllFlagsListener

      void unregisterAllFlagsListener(LDAllFlagsListener allFlagsListener)
      Unregisters a LDAllFlagsListener so it will no longer be called on flag updates.
      Parameters:
      allFlagsListener - the listener to be removed

    • isDisableBackgroundPolling

      boolean isDisableBackgroundPolling()
      Checks whether LDConfig.Builder.disableBackgroundUpdating(boolean) was set to true in the configuration.
      Returns:
      true if background polling is disabled

    • getVersion

      String getVersion()
      Returns the version of the SDK, for instance "2.7.0".
      Returns:
      the version string
      Since:
      2.7.0