Core Classes

The LDClient is the heart of the SDK, providing client apps running iOS, watchOS, macOS, or tvOS access to LaunchDarkly services. This singleton provides the ability to set a configuration (LDConfig) that controls how the LDClient talks to LaunchDarkly servers, and a contexts (LDContext) that provides finer control on the feature flag values delivered to LDClient. Once the LDClient has started, it connects to LaunchDarkly’s servers to get the feature flag values you set in the Dashboard.

Usage

Startup

1. To customize, configure a LDConfig and LDContext. The config is required, the context is optional. Both give you additional control over the feature flags delivered to the LDClient. See LDConfig & LDContext for more details.
   • The mobileKey set into the LDConfig comes from your LaunchDarkly Account settings. If you have multiple projects be sure to choose the correct Mobile key.
2. Call LDClient.start(config: context: completion:)
   • If you do not pass in a LDContext, LDClient will create a default for you.
   • The optional completion closure allows the LDClient to notify your app when it received flag values.
3. Because LDClient instances are stored statically, you do not have to keep a reference to it in your code. Get the primary instances with LDClient.get()

Getting Feature Flags

Once the LDClient has started, it makes your feature flags available using the variation and variationDetail methods. A variation is a specific flag value. For example a boolean feature flag has 2 variations, true and false. You can create feature flags with more than 2 variations using other feature flag types.

 let boolFlag = LDClient.get()?.boolVariation(forKey: "my-bool-flag", defaultValue: false)

If you need to know more information about why a given value is returned, use variationDetail.

See boolVariation(forKey: defaultValue:) or boolVariationDetail(forKey: defaultValue:) for details

Observing Feature Flags

You might need to know when a feature flag value changes. This is not required, you can check the flag’s value when you need it.

If you want to know when a feature flag value changes, you can check the flag’s value. You can also use one of several observe methods to have the LDClient notify you when a change occurs. There are several options–you can set up notificiations based on when a specific flag changes, when any flag in a collection changes, or when a flag doesn’t change. The flag change listener may be invoked multiple times per invocation of LDClient.identify as the SDK fetches up to date flag data from multiple sources (e.g. local cache, cloud services). In certain error cases, the SDK may not be able to retrieve flag data during an identify (e.g. no network connectivity). In those cases, the flag change listener may not be invoked.

 LDClient.get()?.observe("flag-key", owner: self, observer: { [weak self] (changedFlag) in
    self?.updateFlag(key: "flag-key", changedFlag: changedFlag)
 }

The changedFlag passed in to the closure contains the old and new value of the flag.

See more

public class LDClient

Use LDConfig to configure the LDClient. When initialized, a LDConfig contains the default values which can be changed as needed.

See more

public struct LDConfig

extension LDConfig: Equatable

LDContext is a collection of attributes that can be referenced in flag evaluations and analytics events.

To create an LDContext of a single kind, such as a user, you may use LDContextBuilder.

To create an LDContext with multiple kinds, use LDMultiContextBuilder.

See more

public struct LDContext : Encodable, Equatable

extension LDContext: Decodable

Contains methods for building a single kind LDContext with a specified key, defaulting to kind “user”.

You may use these methods to set additional attributes and/or change the kind before calling LDContextBuilder.build(). If you do not change any values, the defaults for the LDContext are that its kind is “user”, its key is set to whatever value you passed to LDContextBuilder.init(key:), its anonymous attribute is false, and it has no values for any other attributes.

To define a multi-context, see LDMultiContextBuilder.

See more

public struct LDContextBuilder

Represents an attribute name or path expression identifying a value within a Context.

This can be used to retrieve a value with LDContext.getValue(_:), or to identify an attribute or nested value that should be considered private with LDContextBuilder.addPrivateAttribute(_:) (the SDK configuration can also have a list of private attribute references).

This is represented as a separate type, rather than just a string, so that validation and parsing can be done ahead of time if an attribute reference will be used repeatedly later (such as in flag evaluations).

If the string starts with ‘/’, then this is treated as a slash-delimited path reference where the first component is the name of an attribute, and subsequent components are the names of nested JSON object properties. In this syntax, the escape sequences “~0” and “~1” represent ‘~’ and ‘/’ respectively within a path component.

If the string does not start with ‘/’, then it is treated as the literal name of an attribute.

For instance, if the JSON representation of a context is as follows–

{
  "kind": "user",
  "key": "123",
  "name": "xyz",
  "address": {
    "street": "99 Main St.",
    "city": "Westview"
  },
  "a/b": "ok"
}

– then

• Reference(“name”) or Reference(“/name”) would refer to the value “xyz”
• Reference(“/address/street”) would refer to the value “99 Main St.”
• Reference(“a/b”) or Reference(“/a~1b”) would refer to the value “ok”

See more

public struct Reference : Codable

extension Reference: Equatable

extension Reference: Hashable

Contains method for building a multi-context.

Use this type if you need to construct a LDContext that has multiple kind values, each with its own nested LDContext. To define a single-kind context, use LDContextBuilder instead.

Obtain an instance of LDMultiContextBuilder by calling LDMultiContextBuilder.init(); then, call LDMultiContextBuilder.addContext(_:) to specify the nested LDContext for each kind. LDMultiContextBuilder setters return a reference the same builder, so they can be chained together.

See more

public struct LDMultiContextBuilder

An object returned by the SDK’s variationDetail methods, combining the result of a flag evaluation with an explanation of how it is calculated.

See more

public final class LDEvaluationDetail<T>

An immutable instance of any data type that is allowed in JSON.

An LDValue can be a null (that is, an instance that represents a JSON null value), a boolean, a number (always encoded internally as double-precision floating-point), a string, an ordered list of LDValue values (a JSON array), or a map of strings to LDValue values (a JSON object).

This can be used to represent complex data in a context attribute, or to get a feature flag value that uses a complex type or does not always use the same type.

See more

public enum LDValue: Codable,
                     Equatable,
                     ExpressibleByNilLiteral,
                     ExpressibleByBooleanLiteral,
                     ExpressibleByIntegerLiteral,
                     ExpressibleByFloatLiteral,
                     ExpressibleByStringLiteral,
                     ExpressibleByArrayLiteral,
                     ExpressibleByDictionaryLiteral

extension LDValue: LDValueConvertible