Objective-C Core Interfaces

  • 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 user (LDUser) 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.

    Objc Classes

    The SDK creates an Objective-C native style API by wrapping Swift specific classes, properties, and methods into Objective-C wrapper classes prefixed by Objc. By defining Objective-C specific names, client apps written in Objective-C can use a native coding style, including using familiar LaunchDarkly SDK names like LDClient, LDConfig, and LDUser. Objective-C developers should refer to the Objc documentation by following the Objc specific links following type, property, and method names.

    Usage

    Startup

    1. To customize, configure a LDConfig (ObjcLDConfig) and LDUser (ObjcLDUser). The config is required, the user is optional. Both give you additional control over the feature flags delivered to the LDClient. See ObjcLDConfig & ObjcLDUser for more details.
    2. The mobileKey set into the LDConfig comes from your LaunchDarkly Account settings (on the left, at the bottom). If you have multiple projects be sure to choose the correct Mobile key.
    3. Call [ObjcLDClient startWithConfig: user: completion:] (ObjcLDClient.startWithConfig(_:config:user:completion:))
    4. If you do not pass in a LDUser, LDCLient will create a default for you.
    5. The optional completion closure allows the LDClient to notify your app when it has gone online.
    6. Because the LDClient is a singleton, you do not have to keep a reference to it in your code.

    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, YES and NO. You can create feature flags with more than 2 variations using other feature flag types. See LDFlagValue for the available types.

    BOOL boolFlag = [ldClientInstance boolVariationForKey:@"my-bool-flag" defaultValue:NO];
    

    If you need to know more information about why a given value is returned, the typed variationDetail methods return an LD<T>EvaluationDetail with an detail about the evaluation.

    LDBoolEvaluationDetail *boolVariationDetail = [ldClientInstance boolVariationDetail:@"my-bool-flag" defaultValue:NO];
    BOOL boolFlagValue = boolVariationDetail.value;
    NSInteger boolFlagVariation = boolVariationDetail.variationIndex
    NSDictionary boolFlagReason = boolVariationValue.reason;
    

    See the typed -[LDCLient variationForKey: defaultValue:] or -[LDClient variationDetailForKey: defaultValue:] methods in the section Feature Flag values for details.

    Observing Feature Flags

    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 setup notifications based on when a specific flag changes, when any flag in a collection changes, or when a flag doesn’t change.

    __weak typeof(self) weakSelf = self;
    [ldClientInstance observeBool:@"my-bool-flag" owner:self handler:^(LDBoolChangedFlag *changedFlag) {
       __strong typeof(weakSelf) strongSelf = weakSelf;
       [strongSelf updateFlagWithKey:@"my-bool-flag" changedFlag:changedFlag];
    }];
    

    The changedFlag passed in to the block contains the old and new value. See the typed LDChangedFlag classes in the Obj-C Changed Flags.

    See more

    Declaration

    Swift

    @objc(LDClient)
    public final class ObjcLDClient : NSObject
  • Use LDConfig to configure the LDClient. When initialized, a LDConfig contains the default values which can be changed as needed.

    The client app can change the LDConfig by getting the config from LDClient (ObjcLDClient), adjusting the values, and setting it back into the LDClient (ObjcLDClient).

    See more

    Declaration

    Swift

    @objc(LDConfig)
    public final class ObjcLDConfig : NSObject
  • LDUser allows clients to collect information about users in order to refine the feature flag values sent to the SDK. For example, the client app may launch with the SDK defined anonymous user. As the user works with the client app, information may be collected as needed and sent to LaunchDarkly. The client app controls the information collected, which LaunchDarkly does not use except as the client directs to refine feature flags. Client apps should follow Apple’s Privacy Policy when collecting user information.

    The SDK caches last known feature flags for use on app startup to provide continuity with the last app run. Provided the LDClient is online and can establish a connection with LaunchDarkly servers, cached information will only be used a very short time. Once the latest feature flags arrive at the SDK, the SDK no longer uses cached feature flags. The SDK retains feature flags on the last 5 client defined users. The SDK will retain feature flags until they are overwritten by a different user’s feature flags, or until the user removes the app from the device.

    The SDK does not cache user information collected, except for the user key. The user key is used to identify the cached feature flags for that user. Client app developers should use caution not to use sensitive user information as the user-key.

    See more

    Declaration

    Swift

    @objc(LDUser)
    public final class ObjcLDUser : NSObject
  • Collects the elements of a feature flag that changed as a result of a clientstream update or feature flag request. The SDK will pass a typed ObjcLDChangedFlag or a collection of ObjcLDChangedFlags into feature flag observer blocks. This is the base type for the typed ObjcLDChangedFlags passed into observer blocks. The client app will have to convert the ObjcLDChangedFlag into the expected typed ObjcLDChangedFlag type.

    See the typed ObjcLDClient observeWithKey:owner:handler:, observeWithKeys:owner:handler:, and observeAllWithOwner:handler: for more details.

    See more

    Declaration

    Swift

    @objc(LDChangedFlag)
    public class ObjcLDChangedFlag : NSObject