DEV Community: Ross Butler

Get More from Codable by Implementing a JSON Key Decoding Strategy

Ross Butler — Sat, 22 Aug 2020 18:44:50 +0000

If you’re not using these, you’re probably writing more code than necessary

Codable is a protocol that was introduced in Swift 4 to make the serialization and deserialization of data into and out of Swift structures a breeze. This post assumes some knowledge of how to use Codable so if you’re unfamiliar with the basics it’s worth reading Encoding and Decoding Custom Types first as a primer. With that being said, let’s continue.

Imagine you have the following JSON you wish to deserialize:

Here’s the series of Swift structures you might write to deserialize the data:

Then using JSONDecoder decode the data as follows:

Very quickly you’ll run into the following error message:

keyNotFound(CodingKeys(stringValue: “travelsOn”, intValue: nil), Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: “vehicles”, intValue: nil), _JSONKey(stringValue: “Index 0”, intValue: 0)], debugDescription: “No value associated with key CodingKeys(stringValue: \”travelsOn\”, intValue: nil) (\”travelsOn\”).”, underlyingError: nil))

That’s because the JSONDecoder is looking for the the key travelsOn in your JSON file. Unfortunately, the actual name of the key in the JSON file is travels-on.

No problem, we can solve this by implementing CodingKeys and custom conformance to the Codable protocol as follows:

We’ve implemented our own initializer and encode function in order deserialize / serialize using the JSON keys provided by our CodingKeys enum. But that’s quite a bit of extra code - had our JSON keys been in snake case as follows then it would have made life much easier:

This is because in this instance, we could have specified a JSON key decoding strategy and avoided have to write all of that extra code:

This one line of code specifying a keyDecodingStrategy saved us from having to implement an initalizer, encode function and CodingKeys enum.

Unfortunately our original JSON file uses kebab case rather than snake case keys and Foundation doesn’t provide a key decoding strategy for kebab case.

However, it does provide the custom key decoding strategy:

case custom(([CodingKey]) -> CodingKey)

This allows us the ability to implement our own custom key decoding strategy for decoding keys in whatever format we wish. All we need to do is provide an implementation of the custom key decoding strategy returning an implementation of the CodingKey protocol (we’ve named our implementation AnyKey following the example provided in the Apple documentation):

Note that the CodingKey protocol defines two failable initializers which must be implemented:

init?(intValue: Int)
init?(stringValue: String)

However we’ve provided an additional non-failable intializer to make our implementation a little more straightforward.

When implementing a custom key decoding strategy, you must provide a closure which accepts an array of type `CodingKey. An array is passed to the closure rather than a single key in order to provide all of the ancestors of the current key providing some context for the current key to be decoded in case this affects the decoding strategy in any way. The current key will always be the last key in the array.

For example, when decoding the key number-of-wheels in our original JSON example, the array passed to the closure would look as follows:
▿ 3 elements

0 : CodingKeys(stringValue: "vehicles", intValue: nil) ▿ 1 : _JSONKey(stringValue: "Index 0", intValue: 0)
stringValue : "Index 0" ▿ intValue : Optional
some : 0 ▿ 2 : _JSONKey(stringValue: "number-of-wheels", intValue: nil)
stringValue : "number-of-wheels"
intValue : nil

The last key is the actual key we are interested in however note that the previous key in the array is a JSON key with an int value of 0. This is because the number-of-wheels key belongs to a JSON object at position 0 in the array of vehicles objects.

You might have wondered why we needed to provided an implementation of the initializer init?(intValue: Int) as part of the CodingKey protocol - this is so that we are able to index arrays which aren’t usually indexed by strings.

Using our new key decoding strategy, all we need write to decode our original JSON file is:

{% gist https://gist.github.com/rwbutler/6d5bfad21d4edd62c41dbf470c257f6d %}

The new key coding strategy can be applied every time we need to use the Codable protocol to deserialize from JSON into a Swift structure from now on making it worth the initial investment of writing a custom key decoding strategy.

However, if you’d rather make use of some pre-written implementations then LetterCase provides a number of implementations for converting keys from a number of popular letter cases including kebab case, train case and macro case amongst others:

convertFromCapitalized
convertFromDashCase
convertFromKebabCase
convertFromLispCase
convertFromLowerCase
convertFromLowerCamelCase
convertFromMacroCase
convertFromScreamingSnakeCase
convertFromTrainCase
convertFromUpperCase
convertFromUpperCamelCase

LetterCase is an open-source framework available under MIT license compatible with Cocoapods, Carthage and Swift Package Manager. As well as providing implementation of JSONDecoder.KeyDecodingStrategy for decoding JSON it provides implementations of JSONEncoder.KeyEncodingStrategy for going the other way and encoding JSON keys.

It also provides an implementation for converting from one letter case to another therefore you if you wanted to decode the original JSON file:

Into variables of macro case e.g.

Then this could be achieved as follows:

Summary

Hopefully this article has shown that by spending a little bit of time upfront creating a custom JSON key decoding strategy, a lot of time can be saved further down the road by reusing the same strategies each and every time you need to decode JSON keys of a different letter case.

LetterCase can be found open-sourced on GitHub under MIT license and is compatible with both Cocoapods, Carthage and Swift Package Manager.

How to Debounce UIButton Taps

Ross Butler — Thu, 02 Apr 2020 21:35:44 +0000

Does your QA like to button bash? Here’s a solution.

We’re all familiar with the situation — we’ve implemented the greatest new feature our app has ever seen. It gets to QA and the first thing they do is rapidly bash the button that pushes the next UIViewController five times in a row.

Mechanical switches typically operate using two metallic contacts which when the switch is depressed come into contact within one another thus completing a circuit. These contacts are usually made of a springy metal which may bounce apart from one another once or several times before coming into final contact with one another. This effect can result in several transitions from low to high power state occurring which in a logic circuit may potentially register as multiple button taps. In order to guard against this, the signal state can be sampled at a low rate until a state change can be reliably said to have occurred. This process is known as debouncing.

The term has been appropriated particularly in the JavaScript and reactive programming communities to refer to the process of observing a stream of successive events until a steady state is reached at which point an event representing that steady state (i.e. the final state) is dispatched. If this idea were to be applied to a stream of button taps then the button tap event would only be dispatched at some point after the last button tap had occurred. This would typically be implemented by introducing a delay in emitting the button tap event such that the event is only emitted if no subsequent button taps were made during the delay period.

It is frequently referenced in relation to throttling because the two operations are somewhat similar in nature. Both involve sampling a stream of events — with throttling we are interested in emitting a sampled version (the sample rate or delay is usually passed as a parameter to the throttling function) of the original event stream. This might be implemented by emitting the first or the last button tap events every delay period for example every 0.5 seconds. With debouncing we are interested in sampling the original event stream and only emitting an event once a steady state has been reached i.e. once the value no appears to be changing.

An example of where this could be useful is the implementation of search suggestions. We might generate excessive traffic on an API if we were to send a request to a search suggestions API each time the user types a new letter into a text field however if we were to throttle the stream events we might only dispatch the request to the API every couple of seconds rather than on each letter press. If we wanted to implement pre-loading of search results such that results appeared without having to hit a done button or equivalent we might debounce the stream of input events such that we dispatch a request to the search API at some delay time after we stop receiving new input.

In terms of debouncing a stream of button taps, it wouldn’t make sense to wait until after the last button tap to dispatch the button tapped event as this would make the UI appear unresponsive. In this case, accepting the first button tap and then ignoring subsequent button taps allows the UI to remain responsive without potentially causing incorrect program behaviour through the execution of the original button tap handler code multiple times.

We can implement such behaviour on a UIButton in Swift fairly simply though an extension on UIControl as follows:

public extension UIControl {
    @objc static var debounceDelay: Double = 0.5
    @objc func debounce(delay: Double = UIControl.debounceDelay, siblings: [UIControl] = []) {
        let buttons = [self] + siblings
        buttons.forEach { $0.isEnabled = false }
        let deadline = DispatchTime.now() + delay
        DispatchQueue.main.asyncAfter(deadline: deadline) {
            buttons.forEach { $0.isEnabled = true }
        }
     }
}

In the above code sample, we simply set the button’s isEnabled property to false for a period of 0.5 seconds after the initial tap and then set it back to true after the delay period elapses. We put the extension on UIControl rather than UIButton as the isEnabled property is actually defined on UIControl rather than UIButton and allows the code to be used more generally. We also set a global delay of 0.5s such that if this function is invoked within a button’s handler function then all subsequent button taps will be ignored for this period by default — however, if we wish to override this delay on a per button basis then we may pass the overridden delay value to the debounce function as a parameter.

One last thing to note is we also allow an array of sibling UIControls to be passed as a parameter to the function in case we wish to temporarily debounce other controls at the same time as the original button. For example, say that we have two buttons A and B whereby tapping button A results in UIViewController A being pushed whilst tapping button B results in UIViewController B being pushed. If we rapidly tapped button A followed by button B (which might happen if a delay in pushing UIViewController A occurred due to a delay introduced by poor signal strength and a logic error) whilst only debouncing button A then at best we would end up in a situation whereby UIViewController A would be pushed followed by UIViewController B. At worst such a scenario could result in an application crash. Therefore we allow sibling controls to be simultaneously debounced in order to avoid scenarios whereby button handlers for distinct buttons being invoked simultaneously could result in unintended interactions.

Functional Reactive Programming (FRP) frameworks such as RxSwift frequently provide implementations of debouncing and throttling functions including Apple’s Combine framework introduced with iOS 13. The Combine implementation of debounce, emits an event after the input stream has reached a steady state which would be exactly what we would need in the example above involving making an API request for search results following data entry into a text field.

func debounce<S>(for dueTime: S.SchedulerTimeType.Stride, scheduler: S, options: S.SchedulerOptions? = nil) -> Publishers.Debounce<AnyPublisher<Output, Failure>, S> where S : Scheduler

In terms of debouncing button taps however the use of this function wouldn’t be ideally suited since as mentioned above, there would be a delay between tapping the button and the UI reacting to the tap.

The Swift extension above is much more in-line with Combine’s throttle implementation which can emit either the first or last event within the specified time interval. It accepts a parameter latest which if set to false will cause the first event within a time interval to be emitted which seems more in-line with our desired behaviour of allowing the button and the UI to remain responsive whilst still ignoring subsequent button bashing.

func throttle<S>(for interval: S.SchedulerTimeType.Stride, scheduler: S, latest: Bool) -> Publishers.Throttle<PassthroughSubject<Output, Failure>, S> where S : Scheduler

Summary

By applying a concept prevalent in web development (particularly JavaScript) and reactive programming using a simple Swift extension or FRP library function we can guard against unintended consequences in our application and hopefully see fewer tickets coming back from QA as a result. 😎

The extension on UIControl can be found open-sourced on GitHub under MIT license along with a sample app in order to allow you to try it out. Note how each button tap in the sample application does not result in ‘Button tapped!’ being printed. Instead due to button taps being debounced, the text is printed no more than once every 0.5s.

Solving the Captive Portal Problem on iOS

Ross Butler — Sun, 01 Sep 2019 12:11:21 +0000

Making Internet connectivity detection more robust by detecting Wi-Fi networks without Internet access.

In iOS development, the de facto means of detecting Internet connectivity has been to make use of Apple’s Reachability sample code. However Reachability cannot actually detect whether connectivity is present, only that an interface is available that might allow a connection.

Consider the case of an app user making use of a public Wi-Fi hotspot which requires the user to register or agree to terms of service via a captive portal prior to Internet connectivity being established e.g. at your local Starbucks branch. The device will appear to have connected to a Wi-Fi network but any request for data will fail until the user has agreed to the Wi-Fi hotspot’s terms of service or registered as a new user — depending on the requirements of the hotspot. Reachability under these circumstances will return a response indicating that Wi-Fi is available even though true Internet connectivity is in fact unavailable.

This can result in confusion as your app will behave as though it is online whilst connected to such a hotspot since Reachability checks will indicate the presence of a Wi-Fi connection. Meanwhile, attempts made by your app to retrieve data from the Internet will fail. This in turn may translate to poor reviews on the App Store.

How iOS Solves the Captive Portal Issue

So how do we go about ensuring that our app has true Internet connectivity? As it turns out iOS already has a solution to this problem.

iOS adopts a protocol called Wireless Internet Service Provider roaming (WISPr 2.0) published by the Wireless Broadband Alliance. This protocol defines the Smart Client to Access Gateway interface describing how to authenticate users accessing public IEEE 802.11 (Wi-Fi) networks using the Universal Access Method in which a captive portal presents a login page to the user.

The user must then register or provide login credentials via a web browser in order to be granted access to the network using RADIUS or another protocol providing centralized Authentication, Authorization, and Accounting (AAA).

In order to detect a that it has connected to a Wi-Fi network with a captive portal, iOS contacts a number of endpoints hosted by Apple — an example being https://www.apple.com/library/test/success.html. Each endpoint hosts a small HTML page of the form:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
    <TITLE>Success</TITLE>
</HEAD>
<BODY>
    Success
</BODY>
</HTML>

If on downloading this small HTML page iOS finds that it contains the word Success as above then it knows that Internet connectivity is available. However, if a login page is presented by a captive portal then the word Success will not be present and iOS will realize that the network connection has been hijacked by a captive portal and will present a browser window allowing the user to login or register.

Apple hosts a number of these pages such that should one of these pages go down, a number of fallbacks can be checked to determine whether connectivity is present or whether our connection is blocked by the presence of a captive portal. Unfortunately iOS exposes no framework to developers which allows us to make use of the operating system’s awareness of captive portals.

Connectivity is an open-source framework available under MIT license which wraps Reachability and endeavors to replicate iOS’s means of detecting captive portals. When Reachability detects Wi-Fi or WWAN connectivity, Connectivity contacts a number of endpoints to determine whether true Internet connectivity is present or whether a captive portal is intercepting the connections. This approach can also be used to determine whether an iOS device is connected to a Wi-Fi router with no Internet access.

Connectivity provides an interface as close to Reachability as possible so that it is familiar to developers used to working with Reachability. This includes providing the methods startNotifier() and stopNotifier() to begin checking for changes in Internet connectivity. Once the notifier has been started, you may query for the current connectivity status synchronously using the status property (similar to Reachability’s currentReachabilityStatus) or asynchronously by registering as an observer with the default NotificationCenter for the notification kNetworkConnectivityChangedNotification (in Swift this is accessed via Notification.Name.ConnectivityDidChange) — similar to Reachability’s notification kNetworkReachabilityChangedNotification.

By default, Connectivity contacts a number of endpoints already used by iOS but it recommended that these are supplemented by endpoints hosted by the developer by appending to the connectivityURLs property. Further customization is possible through setting the successThreshold property which determines the percentage of endpoints contacted which must result in a successful check in order to conclude that connectivity is present. The default value specifies that 75% of URLs contacted must result in a successful connectivity check.

Usage

To get started using Connectivity, simply instantiate an instance and assign a closure to be invoked when Connectivity detects that you are connected to the Internet, when disconnected, or in both cases as follows:

let connectivity: Connectivity = Connectivity()
let connectivityChanged: (Connectivity) -> Void = { [weak self] connectivity in
     self?.updateConnectionStatus(connectivity.status)
}
connectivity.whenConnected = connectivityChanged
connectivity.whenDisconnected = connectivityChanged
func updateConnectionStatus(_ status: Connectivity.ConnectivityStatus) {
    switch status {
        case .connectedViaWiFi:
        case .connectedViaWiFiWithoutInternet:
        case .connectedViaWWAN:
        case .connectedViaWWANWithoutInternet:
        case .notConnected:
    }

}

Then to start listening for changes in Connectivity call:

connectivity.startNotifier()

Remember to call connectivity.stopNotifier() when you are done.

One-Off Checks

Sometimes you only want to check the connectivity state as a one-off. To do so, instantiate a Connectivity object then check the status property as follows:

let connectivity = Connectivity()
switch connectivity.status {
    case .connectedViaWiFi:

    case .connectedViaWiFiWithoutInternet:

    case .connectedViaWWAN:

    case .connectedViaWWANWithoutInternet:

    case .notConnected:

}

Alternatively, you may check the following properties of the Connectivity object directly if you are only interested in certain types of connections:

var isConnectedViaWWAN: Bool
var isConnectedViaWiFi: Bool

var isConnectedViaWWANWithoutInternet: Bool
var isConnectedViaWiFiWithoutInternet: Bool

Connectivity URLs

It is possible to set the URLs which will be contacted to check connectivity via the connectivityURLs property of the Connectivity object before starting connectivity checks with startNotifier().

connectivity.connectivityURLs = [URL(string: “https://www.apple.com/library/test/success.html")!]

Notifications

If you prefer using notifications to observe changes in connectivity, you may add an observer on the default NotificationCenter:

NotificationCenter.default.addObserver(_:selector:name:object:)

Listening for Notification.Name.ConnectivityDidChange, the object property of received notifications will contain the Connectivity object which you can use to query connectivity status.

Polling

In certain cases you may need to be kept constantly apprised of changes in connectivity state and therefore may wish to enable polling. Where enabled, Connectivity will not wait on changes in Reachability state but will poll the connectivity URLs every 10 seconds (this value is configurable). ConnectivityDidChange notifications will be emitted and whenConnected / whenDisconnected closures will be invoked only where changes in connectivity state occur.

To enable polling:

connectivity.isPollingEnabled = true
connectivity.startNotifier()

SSL

As of Connectivity 1.1.0, using HTTPS for connectivity URLs is the default setting. If your app doesn’t make use of App Transport Security and you wish to make use of HTTP URLs as well as HTTPS ones then either set isHTTPSOnly to false or set shouldUseHTTPS to false when instantiating the Connectivity object as follows*:

let connectivity = Connectivity(shouldUseHTTPS: false)

*Note that the property will not be set if you have not set the NSAllowsArbitraryLoads flag in your app's Info.plist first.

Threshold

To set the number of successful connections required in order to be deemed successfully connected, set the successThreshold property. The value is specified as a percentage indicating the percentage of successful connections i.e. if four connectivity URLs are set in the connectivityURLs property and a threshold of 75% is specified then three out of the four checks must succeed in order for our app to be deemed connected:

connectivity.successThreshold = Connectivity.Percentage(75.0)

Summary

Connectivity emulates iOS’s method of detecting captive portals and exposes this functionality to the developer with a familiar interface. Being able to reliably detect more nuanced situations such as where an iOS device is connected to a Wi-Fi router without Internet access allows app developers to provide users with better information and to develop more robust online functionality.

Connectivity can be found open-sourced on GitHub under MIT license and is compatible with both Cocoapods and Carthage.

If you found this article interesting, a subsequent article Detecting Internet Access on iOS 12+ explains how the Network framework introduced in iOS 12 can be used in place of Reachability.

Feature Flags, A/B Testing & MVT on iOS

Ross Butler — Sat, 31 Aug 2019 17:34:32 +0000

Toggle features, phase feature roll outs and run A/B tests in your iOS apps without having to release a new version of your app or shelling out an unnecessary monthly fee for an online platform.

There are a lot of platforms charging monthly subscriptions to provide feature flagging and A/B testing capabilities for iOS apps these days but all it really takes is a JSON file and some client-side code.

This article shows how you can bundle or host your own JSON configuration to provide feature flagging / testing capabilities for your app using the open-source FeatureFlags framework which is freely available under the MIT license and is compatible with both Cocoapods and Carthage.

Some powerful features of this framework include capabilities you might not expect such as the ability to roll out an A/B test to a percentage of users, adjust that percentage remotely (which can be used for phased feature roll out) and then roll out the feature to all users when you’re ready to do so.

Installation

The first step is installation of the FeatureFlags pod / framework using either Cocoapods or Carthage. If you’re already familiar with how to install a framework via these methods you may want to skip ahead to the section on Usage.

Cocoapods

CocoaPods is a dependency manager which integrates dependencies into your Xcode workspace. To install it using RubyGems run:

gem install cocoapods

To install FeatureFlags using Cocoapods, simply add the following line to your Podfile:

pod "FeatureFlags"

Then run the command:

pod install

For more information see here.

Carthage

Carthage is a dependency manager which produces a binary for manual integration into your project. It can be installed via Homebrew using the commands:

brew update
brew install carthage

In order to integrate FeatureFlags into your project via Carthage, add the following line to your project’s Cartfile:

github "rwbutler/FeatureFlags"

From the macOS Terminal run carthage update --platform iOS to build the framework then drag FeatureFlags.framework into your Xcode project.

For more information see here.

Usage

With the framework integrated into your project, the next step is configuration using a JSON file which may be bundled as part of your app or remotely. The JSON file may be newly-created or could an existing configuration JSON file that you’re using already. Simply add a key called features at the top level of your file mapping to an array of features as follows:

{
    "features": []
}

The contents of the array depends on the feature flags and tests to be configured.
To let FeatureFlags know where to find your configuration file:

guard let featuresURL = Bundle.main.url(forResource: "features", withExtension: "json") else { 
    return 
}
FeatureFlags.configurationURL = featuresURL

Or:

guard let featuresURL = URL(string: "https://www.exampledomain.com/features.json") else {
    return 
}
FeatureFlags.configurationURL = featuresURL

In the event that you opt to host your JSON file remotely, you may provide a bundled fallback as part of your app bundle:

guard let fallbackURL = Bundle.main.url(forResource: "features", withExtension: "json") { 
    return 
}
FeatureFlags.localFallbackConfigurationURL = fallbackURL

Your remotely-hosted JSON file will always take precedence over bundled settings and remotely-defined settings will be cached so that in the eventuality that the user is offline, the last settings retrieved from the network will be applied.

Feature Flags

In order to configure a feature flag add a feature object to the features array in your JSON configuration.

{
    "features": [{
        "name": "Example Feature Flag",
        "enabled": false
    }]
}

Then add an extension on Feature.Name to import your feature flag in code as follows:

import FeatureFlags
extension Feature.Name {
    static let exampleFeatureFlag = Feature.Name(rawValue: "Example Feature Flag")
}

Make sure that the raw value matches the string in your JSON file. Then call the following to check whether the feature flag is enabled:

Feature.isEnabled(.exampleFeatureFlag))

If the string specified in your Feature.Name extension doesn't match the value in your JSON file, the default value returned is false. If you need to check the feature exists, you can write:

if let feature = Feature.named(.exampleFeatureFlag) {
    print("Feature name -> \(feature.name)")
    print("Feature enabled -> \(feature.isEnabled())")
}

A/B Tests

To configure an A/B test, add the following feature object to the features array in your JSON file:

{
    "name": "Example A/B Test",
    "enabled": true,
    "test-variations": ["Group A", "Group B"]
}

The only difference between a feature flag and an A/B test involves adding an array of test variations. FeatureFlags will assume that you are configuring an A/B test if you add two test variations to the array — add any more and the test will automatically become a multivariate test (MVT).
Import your feature into code with an extension on Feature.Name:

extension Feature.Name {
    static let exampleABTest = Feature.Name(rawValue: "Example A/B Test")
}

And then using the following to check which group the user has been assigned to:

if let test = ABTest(rawValue: .exampleABTest) {
    print("Is in group A? -> \(test.isGroupA())")
    print("Is in group B? -> \(test.isGroupB())")
}

Alternatively, you may prefer the following syntax:

if let feature = Feature.named(.exampleABTest) {
    print("Feature name -> \(feature.name)")
    print("Is group A? -> \(feature.isTestVariation(.groupA))")
    print("Is group B? -> \(feature.isTestVariation(.groupB))")
    print("Test variation -> \(feature.testVariation())")
}

Feature A/B Tests

A feature A/B test is a subtle variation on (and subtype of) an A/B test. In a generic A/B test you may want to check whether a user has been placed in the blue background or red background test variation. A feature A/B test specifically tests whether the introduction of a new feature is an improvement over a control group without the feature. Thus in a feature A/B test — the feature is either off or on.
To configure a feature A/B test use the following JSON:

{
    "name": "Example Feature A/B Test",
    "enabled": true, // whether or not the test is enabled
    "test-variations": ["Enabled", "Disabled"]
}

extension Feature.Name {
    static let exampleFeatureABTest = Feature.Name(rawValue: "Example Feature A/B Test")
}

By naming the test variations Enabled and Disabled, FeatureFlags knows that your intention is to set up a feature A/B test.

Configuring a feature A/B test has the advantage over a generic A/B test in that instead of having to write:

if let feature = Feature.named(.exampleFeatureABTest) {
    print("Feature name -> \(feature.name)")
    print("Is group A? -> \(feature.isTestVariation(.enabled))")
    print("Is group B? -> \(feature.isTestVariation(.disabled))")
    print("Test variation -> \(feature.testVariation())")
}

You may simply use the following to determine which test group the user has been assigned to:

Feature.isEnabled(.exampleFeatureABTest))

Ordinarily using the Feature.enabled() method tests to see whether a feature is globally enabled; in this specific instance it will return true if the user belongs to the group receiving the new feature and false if the user belongs to the control group. Note that this method also return false if the enabled property is set to false in the JSON for this feature i.e. the test is globally disabled.

Multivariate (MVT) Tests

Configuration of a multivariate test follows much the same pattern as that of an A/B test. Add the following feature object to the features array in your JSON file:

{
    "name": "Example MVT Test",
    "enabled": true,
    "test-variations": ["Group A", "Group B", "Group C"]
}

FeatureFlags knows that you are configuring a MVT test if you add more than two test variations to the array. Again, import your feature into code with an extension on Feature.Name:

extension Feature.Name {
    static let exampleMVTTest = Feature.Name(rawValue: "Example MVT Test")
}

Using the following to check which group the user has been assigned to:

if let feature = Feature.named(.exampleMVTTest) {
    print("Feature name -> \(feature.name)")
    print("Is group A? -> \(feature.isTestVariation(.groupA))")
    print("Is group B? -> \(feature.isTestVariation(.groupB))”)
    print("Is group C? -> \(feature.isTestVariation(.groupC))”)
    print("Test variation -> \(feature.testVariation())”)
}

You are free to name your test variations whatever you wish:

{
    "name": "Example MVT Test",
    "enabled": true, // whether or not the test is enabled
    "test-variations": ["Red", "Green", "Blue"]
}

Simply create an extension on Test.Variation to map your test variations in code:

extension Test.Variation {
    static let red = Test.Variation(rawValue: "Red")
    static let green = Test.Variation(rawValue: "Green")
    static let blue = Test.Variation(rawValue: "Blue")
}

Then check which group the user has been assigned to:

if let feature = Feature.named(.exampleMVTTest) {
    print("Feature name -> \(feature.name)")
    print("Is red? -> \(feature.isTestVariation(.red))")
    print("Is green? -> \(feature.isTestVariation(.green))")
    print("Is blue? -> \(feature.isTestVariation(.blue))")
    print("Test variation -> \(feature.testVariation())")
}

Advanced Usage

Test Bias

By default for any A/B or MVT test, the user is equally likely to be assigned each of the specified test variations i.e. for an A/B test, there’s a 50%/50% chance of being assigned one group or another. For a MVT test with four variations, the chance of being assigned to each is 25%.
It is possible to configure a test bias such that the likelihood of being assigned to each test variation is not equal. To do so, simply add the following JSON to your feature object:

{
    "features": [{
        "name": "Example A/B Test",
        "enabled": true,
        "test-biases": [80, 20],
        "test-variations": ["Group A", "Group B"]
    }]
}

The number of weightings specified in the test-biases array must be equal to the number of test variations and must amount to 100 otherwise the weightings will be ignored and default to equal weightings.

Labels

It is possible to attach labels to test variations in case you wish to send analytics respective to the test group to which a user has been assigned.

To do so, define an array of labels of equal length to the number of test variations specified:

{
    "features": [{
        "name": "Example A/B Test",
        "enabled": true,
        "test-biases": [50, 50],
        "test-variations": ["Group A", "Group B"],
        "labels": ["label1-for-analytics", "label2-for-analytics"]
     }]
}

Then to retrieve your labels in code you would write the following:

if let feature = Feature.named(.exampleABTest) {
    print("Group A label -> \(feature.label(.groupA))")
    print("Group B label -> \(feature.label(.groupB))")
}

Rolling Out Features

The most powerful feature of the FeatureFlags framework is the ability to adjust the test biases in your remote JSON configuration file and have the users automatically be re-assigned to new test groups. For example, you might decide to roll out a feature using a 10%/90% (whereby 10% of users receive the new feature) split in the first week, 20%/80% in the second week and so on.

Simply update the weightings in the test-biases array and the next time the framework checks your JSON configuration, groups will be re-assigned.

When you are done A/B or MVT testing a feature you will have gathered enough analytics to decide whether or not to roll out the feature to your entire user base. At this point, you may decide to disable the feature entirely by setting the enabled flag to false in your JSON file or in the case of a successful test, you may decide to roll out the feature to all users by adjusting the feature object in your JSON file from:

{
    "features": [{
        "name": "Example A/B Test",
        "enabled": true,
        "test-biases": [50, 50],
        "test-variations": ["Group A", "Group B"],
        "labels": ["label1-for-analytics", "label2-for-analytics"]
    }]
}

To a feature flag globally enabled for all users as follows:

{
    "features": [{
        "name": "Example A/B Test",
        "enabled": true
    }]
}

QA

In order to test that both variations of your new feature work correctly you may need to adjust the status of your feature flags / tests at runtime. To this end FeatureFlags provides the FeatureFlagsViewController which allows you to toggle features flags on/off in debug builds of your app or cycle A/B testing or MVT testing variations.

To display the view controller specify the navigational preferences desired and then push the view controller by providing a UINavigationController:

let navigationSettings = FeatureFlagsViewControllerNavigationSettings(
    autoClose: true, 
    closeButtonAlignment: .right, 
    closeButton: .save, 
    isNavigationBarHidden: false
)

FeatureFlags.pushFeatureFlags(
    delegate: self, 
    navigationController: navigationController, 
    navigationSettings: navigationSettings
)

Should you need further information on the state of each feature flag / test, you may use 3D Touch to peek / pop more information.

Refreshing Configuration

Should you need to refresh your configuration at any time you may call FeatureFlags.refresh() which optionally accepts a completion closure to notify you when the refresh is complete.

If you have opted to include your feature flag information as part of an existing JSON file which your app has already fetched you may wish to use the following method passing the JSON file data to avoid repeated network calls:

FeatureFlags.refreshWithData(_:completion:)

Summary

FeatureFlags provides an inexpensive solution to implementing feature flagging, A/B testing and MVT allowing you to self-host your configuration and incorporating powerful features such as phased feature roll out which you can control easily by adjusting the test biases in your configuration file. We’ve seen that it is even possible to roll out a feature to all users by converting an A/B test or MVT to a globally-enabled feature flag which saves us having to release a new version of our app to the store.

FeatureFlags can be found open-sourced on GitHub under MIT license and is compatible with both Cocoapods and Carthage.