Swiftpack.co - Package - launchdarkly/ios-client-sdk

LaunchDarkly SDK for iOS

CircleCI SwiftPM compatible CocoaPods compatible Carthage compatible Platform

LaunchDarkly overview

LaunchDarkly is a feature management platform that serves over 100 billion feature flags daily to help teams build better software, faster. Get started using LaunchDarkly today!

Twitter Follow

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 |

Installation

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"))
]

CocoaPods

To use the CocoaPods dependency manager to integrate LaunchDarkly into your Xcode project, specify it in your Podfile:

use_frameworks!
target 'YourTargetName' do
  pod 'LaunchDarkly', '~> 5.2'
end

Carthage

To use the Carthage dependency manager to integrate LaunchDarkly into your Xcode project, specify it in your Cartfile:

To integrate LaunchDarkly into your Xcode project using Carthage, specify it in your Cartfile:

github "launchdarkly/ios-client-sdk" ~> 5.2

Manual installation

If you prefer not to use the aforementioned dependency managers, it is possible to integrate the SDK manually.

  1. 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.
  2. Open the new ios-client-sdk folder and drag LaunchDarkly.xcodeproj into the project navigator of your application's Xcode project. It should appear nested within your application's blue project icon.
  3. 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.
  4. Select the "General" tab, and if necessary expand the subsection "Frameworks, Libraries, and Embedded Content".
  5. Click the "+" button in the expanded subsection. Under "LaunchDarkly" within the dialog you will see 4 frameworks, select LaunchDarkly.framework for iOS, or LaunchDarkly_<platform> for other platforms.

Learn more

Check out our documentation for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the complete reference guide for this SDK.

Testing

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.

Contributing

We encourage pull requests and other contributions from the community. Check out our contributing guidelines for instructions on how to contribute to this SDK.

About LaunchDarkly

  • 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

Github

link
Stars: 30

Used By

Total: 0

Releases

[5.2.0] - 2020-10-09 - 2020-10-09 12:46:09

Added

Fixed

  • 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 LDUser.privateAttributes or LDConfig.privateUserAttributes properties.
  • 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

Added

  • 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.

Fixed

  • 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.

Added

  • Support for multiple LaunchDarkly projects or environments. Each set of feature flags associated with a mobile key is called an environment. This adds:
    • LDConfig.setSecondaryMobileKeys and LDConfig.getSecondaryMobileKeys which allows configuring a mapping of names to the SDK keys for each additional environment. LDConfig.mobileKey is 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 LDConfig and LDClient.
  • 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 LDConfig properties diagnosticOptOut and diagnosticRecordingInterval.
  • The SDK can now be configured with LDConfig.wrapperName and LDConfig.wrapperVersion to 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 evaluationReasons field to the Objective-C bindings for LDConfig to 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.
  • LDInvalidArgumentError that is thrown on incorrect API usage.
  • Added typeMismatch field to ObjcLD<T>ChangedFlag classes (bound to LD<T>ChangedFlag in Objective-C) that is true/YES when the flag value did not match the registered observer.

Changed (build)

  • 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.

Changed (API)

  • The LDClient instance method start has been replaced with a static method LDClient.start for initializing all configured environments.
  • LDChangedFlag no longer includes the oldValueSource and newValueSource properties, as LDFlagValueSource was removed.
  • The following were renamed for consistency internally and with other SDKs:
    • LDClient.reportEvents() has been renamed to LDClient.flush().
    • LDClient.stop() has been renamed to LDClient.close().
    • LDClient.trackEvent(key: data: ) method have been renamed to LDClient.track(key: data: )
    • LDClient.allFlagValues has been renamed to LDClient.allFlags.
    • EvaluationDetail has been renamed to LDEvaluationDetail.
    • The ObjC<T>EvaluationDetail classes have been renamed to corresponding ObjcLD<T>EvaluationDetail. The names when exposed in Objective-C have been updated to replace the ObjC prefix with LD, e.g. ObjCStringEvaluationDetail to LDStringEvaluationDetail.
  • LDClient.track no longer throws JSONError and instead throws LDInvalidArgumentError.
  • The fallback parameter of all LDClient and ObjcLDClient variation methods has been renamed to defaultValue to help distinguish it from fallback values in rules specified in the LaunchDarkly dashboard.

Changed (behavioral)

  • 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.
  • The LDClient.identify, LDClient.flush, LDClient.setOnline, and LDClient.close instance methods now operate on all configured environments. Any completion arguments will complete when the operation has completed for all configured environments.

Removed

  • The LDClient.shared static property and its ObjcLDClient.sharedInstance wrapper property has been removed. After calling LDClient.start, the initialized instances can be retrieved with LDClient.get(environment: ).
  • The LDClient.config and its ObjcLDClient.config wrapper property has been removed, configuration of the SDK should be done with LDClient.start.
  • The LDClient.user and its ObjcLDClient.user wrapper property has been removed. The initial user should be configured with LDClient.start, and updates to the user should be performed with LDClient.identify.
  • LDFlagValueSource and ObjcLDFlagValueSource were removed in favor of using LDEvaluationDetail and ObjcLD<T>EvaluationDetail.
  • 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.
  • variationAndSource methods were removed from LDClient and its ObjcLDClient wrapper in favor of variationDetail methods.
  • LDUser.init?(object: ) and corresponding ObjcLDUser failable initializers were removed.
  • JSONError and JSONErrorDomain extensions on JSONSerialization were removed.
  • Removed isEqual extension to Array, this was only intended for internal SDK use.
  • Removed == and != extension to Optional<[String: Any]> (note that this was not declared as Equatable conformance). This extension was only intended for internal SDK use.
  • Removed LDFlagValue enum and the ObjcLDFlagValue wrapper which were exposed but not used in any public APIs.
  • Removed Sysctl struct (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

  • Added a new method signature for startCompleteWhenFlagsReceived that 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 Bool on completion indication whether the operation timed out.

[4.6.0] - 2020-05-26 - 2020-05-27 01:18:19

Added

  • Added maxCachedUsers option to LDConfig. You can now specify the number of users to be cached or use -1 for unlimited cached users.

Fixed

  • FlagStore properly synchronizes reads and writes to prevent a potential race condition.

[4.5.0] - 2020-03-26 - 2020-03-27 04:22:01

Changed

  • Updated SDK code to build, run, and test on Xcode 11.4.

[4.4.1] - 2020-02-04 - 2020-02-13 20:01:20

Changed

  • 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

Added

  • Added startCompleteWhenFlagsReceived function which contains modified completion behavior. This new function's completion will only return after flag values are received. Previously the start completion 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

Fixed

  • 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

Changed

  • Updated to ios-eventsource version 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

Added

  • Implemented variationDetail which 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 track method now supports an additional metricValue parameter.

[4.2.1] - 2019-11-15 - 2019-11-15 19:37:09

Changed

  • Updated to ios-eventsource version 4.0.3. This appends a platform name to bundle identifiers. (Thanks, cswelin!)

Fixed

  • Comparing two nil objects of type [String: Any]? no longer causes a crash. (#197)

[4.2.0] - 2019-10-25 - 2019-10-25 20:47:24

Added

  • The identify function 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 ConnectionInformation that 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 observeCurrentConnectionMode allows your application to listen to changes in the SDK's connection to LaunchDarkly.

Changed

  • The user property is now deprecated in favor of the identify function.

[4.1.2] - 2019-07-11 - 2019-07-11 17:17:03

Fixed

  • 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

Changed

  • Updated to ios-eventsource version 4.0.2. This fixes a potential hang on LDClient start.

[4.1.1] - 2019-07-09 - 2019-07-09 23:03:02

Change

  • Updated to ios-eventsource version 4.0.2. This fixes a potential hang on LDClient start.

[4.1.0] - 2019-06-19 - 2019-06-19 23:18:02

Change

  • Installs new deviceModel into EnvironmentReporter and renames old deviceModel to deviceType.
  • Updated MacOS model detection to use CwSysCtl.

Fixed

  • 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

Changed

  • Added nonnull to featureKey parameters on exposed variation methods.

Fixed

  • Added length check to flagConfigValueForKey to prevent dictionary access when key is nil.

3.0.2 - 2019-05-15 19:53:21

[3.0.2] - 2019-05-15

Changed

  • 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.

Changed

  • 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

Added

  • Implements URL caching for REPORT requests.
  • Installs the ability to read cached data in all cached data schemas from 2.3.3 through 3.0.1 and store the feature flags in the 4.0.0 cached 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.

Fixed

  • 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

Changed

  • 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

Changed

  • 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

  • Changed the following to repair macOS builds:
    • Removed extraneous framework reference from Darkly_macOS target
    • Deselected Autocreate schemes in Darkly.xcworkspace

2.14.3 - 2019-02-26 18:41:44

[2.14.3] - 2019-02-25

Changed

  • Added support for integrating without a package manager
  • Updated to DarklyEventSource version 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

  • Added nullability specifiers to public SDK classes.

Changed

  • Updated to DarklyEventSource version 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

Changed

  • 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

Added

  • Added allFlags property to LDClient that provides a dictionary of feature flag keys and values. Accessing feature flags via allFlags does 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 secondaryMobileKeys to LDConfig. LDConfig mobileKey refers to the primary environment, and must be present. All entries in secondaryMobileKeys refer to optional secondary environments. NOTE: See LDClient.h for the requirements to add secondaryMobileKeys. The SDK will throw an NSInvalidArgumentException if an attempt is made to set mobile keys that do not meet these requirements. • Installed LDClientInterface protocol 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 kLDPrimaryEnvironmentName used to vend the primary environment's LDClientInterface from environmentForMobileKeyNamed:.

Changed

  • LDUserBuilder build method no longer restores cached user attributes. The SDK sets into the LDUserModel object only the attributes in the LDUserBuilder at 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

  • Fixed defect preventing SDK from calling userUpdated or featureFlagDidUpdate when deleting a feature flag under certain conditions.
  • Fixed defect preventing URL caching for feature flag requests using the REPORT verb.
  • 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

  • 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

  • Fixed defect preventing feature flags cached prior to version 2.11.0 from restoring correctly and possibly crashing