LaunchDarkly SDK for iOS
Supported iOS and Xcode versions
This version of the LaunchDarkly SDK has been tested with iOS 13.5 and across mobile, desktop, watch, and tv devices. The SDK is built with Xcode 12.0. The minimum platform versions are:
| Platform | Version | | -------- | ------- | | iOS | 10.0 | | watchOS | 3.0 | | tvOS | 10.0 | | macOS | 10.12 |
LaunchDarkly supports multiple methods for installing the library in a project. Once installed, head over to the SDK documentation for complete instructions on getting started with using the SDK.
Swift Package Manager
The Swift Package Manager is a dependency manager integrated into the
swift compiler and Xcode.
To integrate LaunchDarkly into an Xcode project, go to the project editor, and select
Swift Packages. From here hit the
+ button and follow the prompts using
https://github.com/launchdarkly/ios-client-sdk.git as the URL.
To include LaunchDarkly in a Swift package, simply add it to the dependencies section of your
Package.swift file. And add the product "LaunchDarkly" as a dependency for your targets.
dependencies: [ .package(url: "https://github.com/launchdarkly/ios-client-sdk.git", .upToNextMinor(from: "5.2.0")) ]
To use the CocoaPods dependency manager to integrate LaunchDarkly into your Xcode project, specify it in your
use_frameworks! target 'YourTargetName' do pod 'LaunchDarkly', '~> 5.2' end
To use the Carthage dependency manager to integrate LaunchDarkly into your Xcode project, specify it in your
To integrate LaunchDarkly into your Xcode project using Carthage, specify it in your
github "launchdarkly/ios-client-sdk" ~> 5.2
If you prefer not to use the aforementioned dependency managers, it is possible to integrate the SDK manually.
- On the root folder of the project retreive the SDK by either:
- Adding the SDK as a git submodule with
git submodule add https://github.com/launchdarkly/ios-client-sdk.git.
- OR cloning the SDK with
git clone https://github.com/launchdarkly/ios-client-sdk.git.
- Adding the SDK as a git submodule with
- Open the new
ios-client-sdkfolder and drag
LaunchDarkly.xcodeprojinto the project navigator of your application's Xcode project. It should appear nested within your application's blue project icon.
- Select your application project in the project navigator (blue icon) and select your application target under the "Targets" heading in the sidebar. If you have multiple targets, perform the following steps for each target.
- Select the "General" tab, and if necessary expand the subsection "Frameworks, Libraries, and Embedded Content".
- Click the "+" button in the expanded subsection. Under "LaunchDarkly" within the dialog you will see 4 frameworks, select
LaunchDarkly.frameworkfor iOS, or
LaunchDarkly_<platform>for other platforms.
We run integration tests for all our SDKs using a centralized test harness. This approach gives us the ability to test for consistency across SDKs, as well as test networking behavior in a long-running application. These tests cover each method in the SDK, and verify that event sending, flag evaluation, stream reconnection, and other aspects of the SDK all behave correctly.
We encourage pull requests and other contributions from the community. Check out our contributing guidelines for instructions on how to contribute to this SDK.
- LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
- Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
- Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
- Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
- Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline.
- LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Check out our documentation for a complete list.
- Explore LaunchDarkly
You may find interesting
[5.2.0] - 2020-10-09 - 2020-10-09 12:46:09
LDUsernow has an optional
secondaryattribute to match other LaunchDarkly SDKs. For more on the behavior of this attribute see the documentation on targeting users.
- Corrected a bug preventing private custom attribute names being recorded in events when all custom attributes are set to be private by including "custom" in the
- Update Nimble to 9.0 and Quick to 3.0 to fix tests when run with Swift 5.3.
- Fixes build warnings in Xcode 12.0.0.
[5.1.0] - 2020-08-04 - 2020-08-04 22:12:44
- The ability to specify additional headers to be included on HTTP requests to LaunchDarkly services using
LDConfig.additionalHeaders. This feature is to enable certain proxy configurations, and is not needed for normal use.
- Support for building docs with jazzy. These docs will be available through GitHub Pages.
- SDK causing nested bundles in archived product when including the SDK through Carthage. This caused rejections when submitted to the App Store. Thanks to @spr for reporting (#217).
- SDK causing application to expect LDSwiftEventSource dynamic framework when built with SwiftPM, which does not include the dynamic framework in the resulting application. This causes the application to be rejected when submitted to the App Store. Thanks to @spr for reporting (#216).
[5.0.1] - 2020-07-23 - 2020-07-23 18:42:06
Note that this release contains the notes for the 5.0.0 release, which should not be used.
This major version has an accompanying Migration Guide. Please see the guide for more information on updating to this version of the SDK, as the following is just a summary of the changes.
- Support for multiple LaunchDarkly projects or environments. Each set of feature flags associated with a mobile key is called an environment. This adds:
LDConfig.getSecondaryMobileKeyswhich allows configuring a mapping of names to the SDK keys for each additional environment.
LDConfig.mobileKeyis still required, and represents the primary environment.
LDClient.get(environment: )which allows retrieving an LDClient instance for a given environment after the SDK has been initialized.
- Equivalent methods have been added to the Objective-C bindings for
- The SDK now periodically sends diagnostic data to LaunchDarkly, describing the version and configuration of the SDK, the operating system the SDK is running on, the device type (such as "iPad"), and performance statistics. No credentials, device IDs, or other identifiable values are included. This behavior can be disabled or configured with the new
- The SDK can now be configured with
LDConfig.wrapperVersionto send an additional header (
X-LaunchDarkly-Wrapper) in requests to LaunchDarkly. This was added so that the usage of wrapper libraries (such as the React Native SDK) could be recorded independently.
- Added the
evaluationReasonsfield to the Objective-C bindings for
LDConfigto allow configuring the SDK to request evaluation reasons when the application is written in Objective-C.
- The SDK now supports using the Swift Package Manager to include the SDK as a dependency.
LDInvalidArgumentErrorthat is thrown on incorrect API usage.
ObjcLD<T>ChangedFlagclasses (bound to
LD<T>ChangedFlagin Objective-C) that is
YESwhen the flag value did not match the registered observer.
- Minimum deployment targets have been changed as follows:
- iOS 8.0 -> 10.0
- macOS 10.10 -> 10.12
- tvOS 9.0 -> 10.0
- watchOS 2.0 -> 3.0
- The SDK has replaced the internal dependency on the Objective-C eventsource implementation DarklyEventSource with a pure Swift implementation LDSwiftEventSource. Build configurations that manually specify the DarklyEventSource dependency framework may require additional upgrade steps. See the Migration Guide for more information.
- Internally, the SDK no longer includes its dependencies using CocoaPods and Carthage. This simplifies including the SDK as a subproject of your application for integrating the SDK without a package manager.
starthas been replaced with a static method
LDClient.startfor initializing all configured environments.
LDChangedFlagno longer includes the
- The following were renamed for consistency internally and with other SDKs:
LDClient.reportEvents()has been renamed to
LDClient.stop()has been renamed to
LDClient.trackEvent(key: data: )method have been renamed to
LDClient.track(key: data: )
LDClient.allFlagValueshas been renamed to
EvaluationDetailhas been renamed to
ObjC<T>EvaluationDetailclasses have been renamed to corresponding
ObjcLD<T>EvaluationDetail. The names when exposed in Objective-C have been updated to replace the
LDClient.trackno longer throws
JSONErrorand instead throws
fallbackparameter of all
ObjcLDClientvariation methods has been renamed to
defaultValueto help distinguish it from
fallbackvalues in rules specified in the LaunchDarkly dashboard.
- The maximum backoff delay between failed streaming connections has been reduced from an hour to 30 seconds. This is to prevent being unable to receive new flag values for up to an hour if the SDK has reached its maximum backoff due to a period of network connectivity loss.
- The backoff on streaming connections will not be reset after just a successful connection, rather waiting for a healthy connection for one minute after receiving flags. This is to reduce congestion in poor network conditions or if extreme load prevents the LaunchDarkly service from maintaining an active streaming connection.
- When sending events to LaunchDarkly, the SDK will now retry the request after a one second delay if it fails.
- When events fail to be sent to LaunchDarkly, the SDK will no longer retain the events. This prevents double recording events when the LaunchDarkly service received the event but the SDK failed to receive the acknowledgement.
LDClient.closeinstance methods now operate on all configured environments. Any completion arguments will complete when the operation has completed for all configured environments.
LDClient.sharedstatic property and its
ObjcLDClient.sharedInstancewrapper property has been removed. After calling
LDClient.start, the initialized instances can be retrieved with
ObjcLDClient.configwrapper property has been removed, configuration of the SDK should be done with
ObjcLDClient.userwrapper property has been removed. The initial user should be configured with
LDClient.start, and updates to the user should be performed with
ObjcLDFlagValueSourcewere removed in favor of using
- The Objective-C wrapper classes
ObjcLD<T>VariationValue(bound in Objective-C to
LD<T>VariationValue), which wrapped a flag value and its source, have been removed.
variationAndSourcemethods were removed from
ObjcLDClientwrapper in favor of
LDUser.init?(object: )and corresponding
ObjcLDUserfailable initializers were removed.
Array, this was only intended for internal SDK use.
Optional<[String: Any]>(note that this was not declared as
Equatableconformance). This extension was only intended for internal SDK use.
LDFlagValueenum and the
ObjcLDFlagValuewrapper which were exposed but not used in any public APIs.
Sysctlstruct (only available on macOS) which was only intended for internal SDK use.
[5.0.0] - 2020-07-23 - 2020-07-23 17:55:07
Please use the 5.0.1 instead. This release incorrectly specifies its version and is unavailable on CocoaPods.
[4.7.0] - 2020-06-03 - 2020-06-04 22:33:07
- Added a new method signature for
startCompleteWhenFlagsReceivedthat accepts an additional argument specifying a maximum time to wait for flags to be received before calling the completion closure. The completion closure on this method will be passed a
Boolon completion indication whether the operation timed out.
[4.6.0] - 2020-05-26 - 2020-05-27 01:18:19
LDConfig. You can now specify the number of users to be cached or use
-1for unlimited cached users.
FlagStoreproperly synchronizes reads and writes to prevent a potential race condition.
[4.5.0] - 2020-03-26 - 2020-03-27 04:22:01
- Updated SDK code to build, run, and test on Xcode 11.4.
[4.4.1] - 2020-02-04 - 2020-02-13 20:01:20
- The SDK will now retry an event send once when the initial request fails.
[4.4.0] - 2019-12-19 - 2020-01-15 21:31:46
startCompleteWhenFlagsReceivedfunction which contains modified completion behavior. This new function's completion will only return after flag values are received. Previously the
startcompletion returned when the SDK went online.
- The SDK now specifies a uniquely identifiable request header when sending events to LaunchDarkly to ensure that events are only processed once, even if the SDK sends them two times due to a failed initial attempt.
[4.3.2] - 2019-12-19 - 2019-12-20 00:08:43
- Flag change listeners will now be called when a flag value changes but a variation number does not change. Previously, flag listeners were not called when a value assigned to a variation was manually edited in the dashboard or via the API.
[4.3.1] - 2019-12-12 - 2019-12-13 01:02:14
- Updated to
4.1.0. This negates the need to
use_frameworks!when using the React Native SDK. This change does not affect the iOS SDK.
[4.3.0] - 2019-12-3 - 2019-12-03 23:24:37
variationDetailwhich returns an Evaluation Reason giving developers greater insight into why a value was returned.
- Added support for the latest Experimentation features allowing increased value from A/B/n testing. The
trackmethod now supports an additional
[4.2.1] - 2019-11-15 - 2019-11-15 19:37:09
[4.2.0] - 2019-10-25 - 2019-10-25 20:47:24
identifyfunction allows a completion to be called after a user is updated.
- The Connection Status API allows greater introspection into the current LaunchDarkly connection and the health of local flags.
• This feature adds a new class called
ConnectionInformationthat contains properties that keep track of the current connection mode e.g. streaming or polling, when and how a connection failed, and the last time flags were updated. This class can be accessed from
LDClient.shared.getConnectionInformation. • Additionally, a new observer function called
observeCurrentConnectionModeallows your application to listen to changes in the SDK's connection to LaunchDarkly.
userproperty is now deprecated in favor of the
[4.1.2] - 2019-07-11 - 2019-07-11 17:17:03
- WatchKit is now conditionally imported in WatchOS only to fix an error in Xcode 11.
- Comparing two nil objects of type [String: Any]? no longer causes a crash.
[3.0.4] - 2019-07-09 - 2019-07-09 23:04:20
- Updated to
4.0.2. This fixes a potential hang on LDClient start.
[4.1.1] - 2019-07-09 - 2019-07-09 23:03:02
- Updated to
4.0.2. This fixes a potential hang on LDClient start.
[4.1.0] - 2019-06-19 - 2019-06-19 23:18:02
- Installs new
EnvironmentReporterand renames old
- Updated MacOS model detection to use
- Fixed a concurrency bug that caused crashes in FlagStore.swift. This bug could surface during rapid updates to local flags.
3.0.3 - 2019-05-31 00:02:03
[3.0.3] - 2019-05-30
featureKeyparameters on exposed variation methods.
- Added length check to
flagConfigValueForKeyto prevent dictionary access when key is nil.
3.0.2 - 2019-05-15 19:53:21
[3.0.2] - 2019-05-15
- Moved the timer that limits how often a client app can set the SDK online onto the main run loop.
4.0.0 - 2019-05-10 18:16:54
[4.0.0] - 2019-04-18
This is the first non-beta release of the Swift SDK. It follows the beta.3 release from 2019-03-07. Unlike previous Swift SDK releases, this release does not have a
3.0.0 companion tag.
- Changes Feature Flag caching so that cached feature flags are associated with a user key and mobile key.
- Clears new warnings that appear with Xcode 10.2
- Implements URL caching for REPORT requests.
- Installs the ability to read cached data in all cached data schemas from
3.0.1and store the feature flags in the
4.0.0cached data schema.
- Retains prior cached data for 90 days following upgrade to
4.0.0. Does not keep older cached data up-to-date. Downgrading to a prior version within 90 days allows the downgraded app to read the last cached data from the downgraded version.
- Prevents a log message that incorrectly reported a network error on watchOS
3.0.1 - 2019-05-02 18:39:23
[3.0.1] - 2019-04-30
- Deployed Carthage built DarklyEventSource frameworks as part of the Darkly project.
3.0.0 - 2019-04-18 12:11:07
[3.0.0] - 2019-04-17
- Renamed the non-iOS Darkly frameworks to include the platform name. e.g. Darkly_watchOS. Because non-CocoaPods apps will need to update imports for the new modules, advanced to the next major version.
- Removed DarklyEventSource as a CocoaPods dependency in the podfile. DarklyEventSource remains a dependency in the podspec.
2.14.4 - 2019-02-26 22:27:02
[2.14.4] - 2019-02-26
- Changed the following to repair macOS builds:
- Removed extraneous framework reference from Darkly_macOS target
Autocreate schemesin Darkly.xcworkspace
2.14.3 - 2019-02-26 18:41:44
[2.14.3] - 2019-02-25
- Added support for integrating without a package manager
- Updated to
4.0.1, which adds platform specific targets to support integration without a package manager.
2.14.2 - 2019-01-25 03:15:14
[2.14.2] - 2019-01-24
- Added nullability specifiers to public SDK classes.
- Updated to
4.0.0, which eliminates a 1-second delay in SDK initialization.
2.14.1 - 2018-12-21 23:32:01
[2.14.1] - 2018-12-21
- Added copy methods to several objects involved in creating a summary event.
- Added additional synchronization to creating a summary event in order to potentially prevent some crash scenarios.
2.14.0 - 2018-12-06 00:49:22
[2.14.0] - 2018-12-05
LDClientthat provides a dictionary of feature flag keys and values. Accessing feature flags via
allFlagsdoes not record any analytics events.
- Support for multiple LaunchDarkly projects or environments. Each set of feature flags associated with a mobile key is called an
environment. • Added
secondaryMobileKeysto LDConfig. LDConfig
mobileKeyrefers to the primary environment, and must be present. All entries in
secondaryMobileKeysrefer to optional secondary environments. NOTE: See
LDClient.hfor the requirements to add
secondaryMobileKeys. The SDK will throw an
NSInvalidArgumentExceptionif an attempt is made to set mobile keys that do not meet these requirements. • Installed
LDClientInterfaceprotocol used to access secondary environment feature flags. May also be used on the primary environment to provide normalized access to feature flags. • Adds
environmentForMobileKeyNamed:to vend an environment (primary or secondary) object conforming to
LDClientInterface. Use the vended object to access feature flags for the requested environment. • Adds new constant
kLDPrimaryEnvironmentNameused to vend the primary environment's
LDUserBuilder buildmethod no longer restores cached user attributes. The SDK sets into the
LDUserModelobject only the attributes in the
LDUserBuilderat the time of the build message. On start, the SDK restores the last cached feature flags, which the SDK will use until the first feature flag update from the server.
- Changed the format for caching feature flags to associate a set of feature flags with a mobile key. Downgrading to an earlier version will be able to store feature flags, but without the environment association. As a result, the SDK will not restore cached feature flags from 2.14.0 if the SDK is downgraded to a version before 2.14.0.
- Installed a URL cache that does not use the
[NSURLSession defaultSession]or the
[NSURLCache sharedURLCache], precluding conflicts with custom client app URL caching.
- Fixed defect preventing SDK from calling
featureFlagDidUpdatewhen deleting a feature flag under certain conditions.
- Fixed defect preventing URL caching for feature flag requests using the
- Fixed defect causing the loss of some analytics events when changing users.
2.13.9 - 2018-11-06 01:00:59
[2.13.9] - 2018-11-05
- Fixed defect causing a crash when unknown data exists in a feature flag cache.
- Renamed function parameters to avoid the use of Objective-C++ reserved words.
2.13.8 - 2018-10-24 05:03:26
[2.13.8] - 2018-10-23
- Fixed defect preventing feature flags cached prior to version 2.11.0 from restoring correctly and possibly crashing