Getting Started With the Swift iOS Feature Flag

Guide

2

INTRO

Mobile users expect more. They want their applications to be as stable as yesterday while looking and acting more and more like tomorrow. How do you keep up? How can you reliably test and push new features without risking a disastrous release?

Feature toggles (also known as feature flags) are one way. They provide app developers with a way to add new behavior to an application and then enable or disable it without deploying a new release.

So how do feature toggles work? Add some new behavior to the application, wrap it in a boolean, default it to “off,” and then flip it when it’s safe, right?

There’s more to it than that. Effectively using feature flags requires understanding feature flag strategy and tactics.

I’ll get you to your first iOS feature flag quickly, and then give you a deeper understanding of feature flags and how to avoid creating technical debt when you are using them.

This tutorial assumes familiarity with basic iOS concepts and the ability to set up and use Xcode. While I’ll use an iPhone simulator for testing the application, you can use whatever method you feel most comfortable with. I’ll be using the latest version of Xcode, which is 9.3.1 at the time of this writing, and Swift 4.1.

The source code for the completed project is available here.

3

A BASIC FEATURE TOGGLE

Let’s start with the basic single view iOS application offered by Xcode 9.

We’ll add a Label to the application’s single view like below:

4

We’ll add the label to the viewDidLoad() method of our ViewController, with the name GreetingLabe, and assign a greeting to it.

We could set the default value in the UILabel definition if we want, but we’ll define it explicitly throughout the tutorial to make the behavior easy to see.

We don’t need to make any further changes to the sample code. Let’s build and run the application.

We have a basic iOS app to work with. We’ll use feature toggles to modify the application’s greeting.

@IBOutlet weak var greetingLabel: UILabel! override func viewDidLoad() { super.viewDidLoad() greetingLabel.text = "Hello, World!" }

5

AN IOS FEATURE TOGGLE

So let’s imagine we want to replace our greeting with a different one depending on the season.

A fundamental mechanism would be a boolean flag.

When we build and run this version we see the new greeting below:

And we have our first feature toggle!

But this means modifying, building, and getting a release through the App Store whenever we want to change our greeting.

var isNewYear = true @IBOutlet weak var greetingLabel: UILabel!override func viewDidLoad() { super.viewDidLoad() if isNewYear { greetingLabel.text = "Happy New Year!" } else { greetingLabel.text = "Hello, World!" }}

6

Modifying a configuration file would be a bit simpler and shave a little bit of time and effort off the release cycle. Let’s create a property list and add our toggle in the form of a configuration property to it.

We have a property list named featureflag.plist. In it, there is one parameter: a boolean flag named isNewYear.

We’ll load it and use the property to set our flag. We’ll load the file in the controller, even though that’s not what we would do in production code, to keep things simple.

Now we can toggle the value of isNewYear to YES or NO via the properties file, and we’ll see the proper greeting.

The plist gets us out of modifying code when we want to toggle a feature, but we still need to build and release.

Let’s look at a better way to change, and more importantly, manage feature toggles.

@IBOutlet weak var greetingLabel: UILabel!override func viewDidLoad() { super.viewDidLoad() var myDict: NSDictionary? if let path = Bundle.main.path(forResource: "featureflag", ofType: "plist") { myDict = NSDictionary(contentsOfFile: path) } isNewYear = myDict?["isNewYear"] as! Bool if isNewYear { greetingLabel.text = "Happy New Year!" } else { greetingLabel.text = "Hello, World!" }}

7

GETTING STARTED WITH ROLLOUT

First, you’ll need to create a free Rollout account here.

Once that’s done, sign in to your Rollout account and create a new application.

Be sure to select iOS, as shown above.

Next, you’ll see instructions for adding Rollout to your application.

First, download rox.zip, unzip it, and add the rox directory to your project’s directory tree.

Next, add RoxSdk.xcodeproj and ROXCore.framework to your project.

8

Then, select Add Files to… from the Project Navigator.

Now, select the files from the RoxSdk directory in the zip file output.

You’ll see ROXCore.framework icon in the Project Navigator. Add those files.

9

Next, we need to remove the framework from the project’s linked frameworks. Select your project’s name at the top of Navigator tab.

And scroll down in the application information page to Linked Frameworks and Libraries.

10

Next, select ROXCore.framework and then click the minus to remove it.

We want to add it back to embedded binaries. Click the plus in Embedded Binaries.

Then, select ROXCore.framework and ROX.frameworkiOS and click Add.

Last, we need to set up a build step to strip out unneeded libraries from our production application.

First, add a script build phase:

11

Then locate the strip_frameworks.sh script:

And drag it into the script target:

12

INITIALIZE THE API

The Xcode project is ready now, and we can initialize the API.

Finally, click Setup SDK back at the Rollout dashboard.

Add the import ROX declaration at the top of AppDelegate.swift.

ROllout assigned a unique initialization key to our application. Add ROX.setup() to didFinishLaunchingWithOptions. The top of AppDelegate.swift should look similar to this:

//// AppDelegate.swift// Feature Flag IOS Example//// Created by Eric Goebelbecker on 5/20/18.// Copyright © 2018 Eric Goebelbecker. All rights reserved.//import UIKitimport ROX

@UIApplicationMainclass AppDelegate: UIResponder, UIApplicationDelegate {

var window: UIWindow?

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { ROX.setup(withKey:"<YOURAPPKEY>") return true }

13

Now we can run the application to initialize Rollout. Click Activate App on the Rollout dashboard. After the application builds and runs, you are rewarded with this:

14

ADD A MANAGED FEATURE FLAG

Let’s create a feature flag and register it with Rollout. If we look at our Rollout dashboard and check flags, we see this:

There are no flags, and there is no way to add one. That’s because we create them from our application, not from the dashboard.

In Swift, feature flags are RoxFlags, and are managed in RoxContainers.

First, add this class to the project:

We’ve created a single flag named isNewYear with a default value of true.

import Foundationimport ROXpublic class Flags: RoxContainer { public let isNewyear = RoxFlag(withDefault: true);}

15

We register the container with the API before calling Rox.setup(). Make this change to AppDelegate:

We’re registering the container with Rollout. The first argument to register() is a name that rollout will associate with it.

Run the application and then go to the Flags menu item in the Rollout dashboard.

The new flag is there. We see the container name and the flag name in the dashboard.

let flags = Flags()

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { ROX.register("Flags", container: flags) ROX.setup(withKey:"yourappkey") // Override point for customization after application launch. return true }

16

READING A MANAGED FEATURE FLAG

Next, we need to update our code to use the RoxFlag instead of the property list.

Rollout retrieves feature flag values asynchronously and caches them. It extracts the latest value from the cache on startup while initiating a fetch from the network in parallel.

This means that the first time we run our application, we will immediately get the default value for our flag (false for toggles unless we override), and then the value set at Rollout upstream will be retrieved sometime later.

Since we want to see the value of the flag before we load our view, we need to do a little bit of extra work. This will also teach us a bit more about the Rollout API.

We’re going to add something to our call to ROX.setup().

First, we create a RoxOptions. This object holds configuration settings that we can pass to the API when we initialize it. One of those options, onConfigurationFetched, is a callback for when the latest configuration is successfully fetched from Rollout.

When our callback is executed, we use NotificationCenter to notify any interested objects that new information has been retrieved.

There are a few advantages to using NotificationCenter instead of trying to call our view directly:

• Since this callback will be called on startup, our ViewController probably hasn’t been created yet.

• If we add more controllers to the application, later things will start to get complicated.

• Threading issues are delegated to listeners (as we’ll see).

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

let options = RoxOptions() options.onConfigurationFetched = { (result: RoxFetcherResult) -> Void in NotificationCenter.default.post(name: Notification.Name(rawValue: "update"), object: nil) }; ROX.register("FeatureFlags", container: flags) ROX.setup(withKey:"5b0755c73f389f1cbf68639d", options:options) return true}

17

Next, we need to make some changes in ViewController.swift.

ViewDidLoad() is now subscribing to update events and delegating them to a method named UpdateLabels()

We moved setting the value of our label to UpdateLabels(). In it, we get a reference to AppDelegate so we can access its copy of the flags and check them. However, we have to dispatch this task to the main thread because only the UI thread can modify the view.

We check the value of isNewYear and set the label appropriately. RolloutFlags() also has an enabled block, but since we need to set the label back if the flag is toggled from “on “to “off,” the if/else logic makes more sense.

@IBOutlet weak var greetingLabel: UILabel!override func viewDidLoad() { super.viewDidLoad() NotificationCenter.default.addObserver(self, selector: #selector(updateLabels), name: NSNotification.Name(rawValue: "update"), object: nil)} @objc func updateLabels() { DispatchQueue.main.async { let appDelegate = UIApplication.shared.delegate as! AppDelegate if (appDelegate.flags.isNewYear.isEnabled) { self.greetingLabel.text = "Happy New Year!" } else { self.greetingLabel.text = "Hello, World!" } }}

18

MANAGING A FEATURE FLAG

We manage flags by adding them to experiments. An experiment is a scheme for controlling flags (and other variables) in production.

First, click on Production in the left-hand side menu and then click Experiments. This will bring up a screen with a Create Experiment button. Click that and fill out the new experiment window appropriately.

And we see a console for setting flags to true, false, or split. Leave it set to False.

If we run our application now, we see “Hello, World!”

Next, change it to True and restart the application.

Select Set Audience.

19

We see the Happy New Year greeting!

Flip it back to false and click the phone’s home button. Then tap on the application icon to open it again. It flips back to Hello World!

We can change the behavior of the application without touching code and releasing a new version. We can even alter it while the application is running on a client’s device.

Before we move on, let’s take a look at the experiment on the console again. Flip the flag from true to split.

This option allows us to distribute a change to a percentage of users, hence the term “experiment.” If you play with it now, you’ll need to completely start and stop the application to see different settings to overcome the API’s caching.

This is the power of feature flags!

20

EXTRA CREDIT: CONFIGURATIONS

Tying the contents of a label to a true/false flag is an admittedly contrived example, but it kept the tutorial code focused and simple.

Let’s take a look at another mechanism for setting a label. Rollout supports managing configuration values from the dashboard.

Let’s add a new field to Flags.

A RoxConfigurationString is exactly what it sounds like.

Build and run the application again, and then go back to the Rollout dashboard.

Under Production and Configurations, we see our new value.

If we click on it, we can set it to a value like so:

public class Flags: RoxContainer{ public let isNewYear = RoxFlag() public let greetingText = RoxConfigurationString(defaultValue: "Hello, World!")}

21

Select >= for the criteria, and enter Happy New Year! for the value.

Then we need to make a small code change. Change updateLabels() to use the value of our new member:

And run the app. We see Happy New Year!

Let’s change it.

Close and open the application. No need to restart or rebuild: our notification mechanism with handle the change.

We can change our application config with Rollout!

func updateLabels() { DispatchQueue.main.async { let appDelegate = UIApplication.shared.delegate as! AppDelegate self.greetingLabel.text = appDelegate.flags.greetingText.value }}

22

CONCLUSION

This guide demonstrates how to get started with Rollout with iOS and Swift. The API supports any iOS platform that runs Swift, including Apple TV. Rollout’s documentation has details on how you can do a great deal more with flags, configuration settings, experiments, versions, and grouping users.

You now have an understanding of feature flag management and how it can improve your iOS code. You’ve seen how it can help you manage projects and eliminate unnecessary releases. Get to work!

23

For more information:

visit https://rollout.io email us at support@rollout.io

Rollout is an advanced feature management solution that gives engineering and product

teams feature control, post-deployment. It’s the most effective way to roll out new features to the right audience while protecting customers from

failure and improving KPI’s.