{"id":794,"date":"2014-11-15T13:20:17","date_gmt":"2014-11-15T19:20:17","guid":{"rendered":"http:\/\/dev.iachieved.it\/iachievedit\/?p=794"},"modified":"2014-11-15T13:20:17","modified_gmt":"2014-11-15T19:20:17","slug":"a-technique-for-displaying-ios-build-versions-in-swift","status":"publish","type":"post","link":"https:\/\/dev.iachieved.it\/iachievedit\/a-technique-for-displaying-ios-build-versions-in-swift\/","title":{"rendered":"A Technique for Displaying iOS Build Versions (in Swift)"},"content":{"rendered":"

It is a universally recognized best practice to visibly expose your iOS application’s version number somewhere on the screen. Often times you will see it on the application’s splash screen or can get to it by selecting the About<\/i> menu item (assuming the application has a menu). No matter where it’s location (I have my preference as to where it should be, which I will describe momentarily), it’s a good idea to have it easily viewed by both your beta testers and your users.<\/p>\n

To be clear, in this post we’re not going to talk about techniques for automatically incrementing the version or build numbers, or strategies for injecting git commit-ish<\/code> or branch identifiers into your application. There are plenty of resources on these topics on the Web. What we will discuss are the differences between CFShortVersionString<\/code> and CFBundleVersion<\/code> and how you can combine the two to provide a straightforward and adequate version number for your application.<\/p>\n

I have always used the major.minor.build<\/i> version number format, where major.minor<\/i> are typically referred to as marketing versions<\/i>, because they are heavily influenced by marketing departments and their desire to articulate to customers “how much new content” is in a given version compared to a previous one. For example, it’s pretty safe to assume that version 2.0 of some given software has a lot of new features compared to version 1.0. It’s also pretty safe to assume that version 1.1 is not radically different from version 1.0. <\/p>\n

So we can agree that the marketing and product management teams are walking around talking about version major.minor<\/i>, and that’s fine. For the purposes of distributing and tracking versions of our application, however, we need one more field, the build<\/i> identifier. Ideally, this number should always be increasing, and no two different builds that are distributed to beta testers should have the same build number. (Note: we say “ideally” but in reality the CFBundleVersion<\/code>, which we will use as our build<\/i> identifier, must be incremented when posting a new version to iTunesConnect).<\/p>\n

It turns out that our Xcode target comes with Identity<\/i> settings such as Bundle Identifier<\/b>, Version<\/b>, and Build<\/b>. We will leverage those settings, and in particular refer to the combination of Version<\/b> and Build<\/b> as our application version.<\/p>\n

\"appversion_initial\"<\/a><\/p>\n

The Xcode Version<\/b> is prepopulated with 1.0<\/code> for a new project, and this will serve as our major.minor<\/code> marketing version<\/i>. It also happens to be the version number that people will see on the iTunes store. The Xcode Build<\/b> version will be the build<\/code> value in our major.minor.build<\/code> tuple. Again, let’s take a moment to stress that for this post we aren’t going to talk about how to automatically increment that value and will increment it by hand every time we build a version that we want to distribute.<\/p>\n

Now that we know what values we want to treat as major.minor.build<\/code> let’s look at how we can access them in our application. It turns out these two values have names in our application’s main bundle<\/i>, which is loaded from the contents of the applications Info.plist<\/code>. We can extract the values by referring to them by their names: CFBundleShortVersionString<\/code> and CFBundleVersion<\/code>. Here’s the Swift code for doing so, and it should be placed in your application(application:didFinishLaunchingWithOptions:)<\/code> routine in the AppDelegate<\/code> class.<\/p>\n

[objc]
\nlet appInfo = NSBundle.mainBundle().infoDictionary as Dictionary<String,AnyObject>
\nlet shortVersionString = appInfo["CFBundleShortVersionString"] as String
\nlet bundleVersion = appInfo["CFBundleVersion"] as String
\n[\/objc]<\/p>\n

Note<\/b>: We’re leveraging Swift’s as<\/code> keyword, which allows us to specify that appInfo<\/code> is a Dictionary<\/code> of AnyObject<\/code>s with keys of type String<\/code>. Furthermore, we apply as<\/code> again to tell Swift that the objects we are retrieving for the keys CFBundleShortVersionString<\/code> and CFBundleVersion<\/code> are String<\/code>s. Don’t make the mistake in thinking that our appInfo<\/code> dictionary consists of only of String-String<\/code> key-value pairs. Refer to Apple’s documentation<\/a> for details of the types of values stored.<\/p>\n

We can combine the CFBundleShortVersionString<\/code> and CFBundleVersion<\/code> together as:<\/p>\n

[objc]
\nlet applicationVersion = shortVersionString + "." + bundleVersion
\n[\/objc]<\/p>\n

Okay, now that we’ve established we can create a version string from CFBundleShortVersionString<\/code> and CFBundleVersion<\/code>, where should we display it? I am a fan of placing it in the application’s iOS Settings<\/i> page. This is page created automatically by iOS for your application, and it can be found by going to the iOS Settings application and scrolling down to the bottom of the default page. For complete details of an application settings page, see Apple’s documentation<\/a>.<\/p>\n

To create a settings page you will need to create a Settings Bundle<\/b> for your application. In Xcode select File – New – File<\/b> and when presented with choosing a template for your new file, select iOS – Resource – Settings Bundle<\/b>, like so:<\/p>\n

\"add_settings_bundle\"<\/a><\/p>\n

Select Next<\/b> and ensure that your settings bundle is included in your application target (it should be by default). Click Create<\/b> and you will see Xcode has included Settings.bundle<\/code> in your project (I also place my Settings.bundle<\/code> in the Supporting Files<\/b> group):<\/p>\n

\"settingsbundle_added\"<\/a><\/p>\n

We are interested in the file called Root.plist<\/code>, where we will add a Group<\/b> section called About<\/b>, which will contain both our copyright line as well as version number. Click on Root.plist<\/code> to bring up the default contents:<\/p>\n

\"rootplist_default\"<\/a><\/p>\n

Delete Item 1, Item 2, and Item 3 by clicking on the row for the item to highlight it, and then right-click and choose Cut<\/b>. When you delete one item the remaining items will renumber themselves, so simply ensure only one item remains, Item 0, which by default is a Group<\/b>. <\/p>\n

Click on the disclosure triangle for Item 0 and you will see Title<\/b> and Type<\/b>. Leave the Type<\/b> as it is (a Group<\/b>), and change the title to About<\/b>. Your panel should look like this:<\/p>\n

\"rootplist_about_only\"<\/a><\/p>\n

Now for the trickier part, and it’s only trickier because the Xcode plist editor can be a pain. Click on the Preference Items row and right-click and select Add Row<\/b>. You will probably notice that our Group<\/b> got moved to Item 1. We don’t want that, so click and drag the Item 1 row back to be the first entry. Add another row, and again, rearrange the entries such that our About<\/b> group is the first. It should look something like this:<\/p>\n

\"rootplist_withabout_and_fields\"<\/a><\/p>\n

Now, let’s set the two fields. The first will be our copyright statement. Click on the disclosure triangle for Item 1, and then right-click on Item 1 and Add Row<\/b>. The default row should have Default Value<\/b> as its type. Put your copyright statement as the default value, change the title field to Copyright<\/b>, and then for Identifier<\/b> put application_copyright<\/code>.<\/p>\n

The second field will be our application version number. Click on the disclosure triangle for Item 2, and then right-click on Item 2 and Add Row<\/b>. Set the default value to 0.0.0, change the title field to Version<\/b>, and then for Identifier<\/b> put application_version<\/code>.<\/p>\n

Your settings Root.plist<\/code> should now look like<\/p>\n

\"rootplist_completed\"<\/a><\/p>\n

If you ran the application as is and then navigated to the iOS Settings page for the application, you would see your copyright statement and 0.0.0 as the version number. Of course we want to get the actual<\/i> version number in there. Here’s the code for doing so (again, place it after your extract the values from appInfo<\/code> in your application delegate’s application(application:didFinishLaunchingWithOptions)<\/code> routine):<\/p>\n

[objc]
\n let defaults = NSUserDefaults.standardUserDefaults()
\n defaults.setObject(applicationVersion, forKey: "application_version")
\n defaults.synchronize()
\n[\/objc]<\/p>\n

NSUserDefaults.standardUserDefaults()<\/code> gives us access to our application’s settings, to which we write our applicationVersion<\/code> to the entry given by the key application_version<\/code>. defaults.synchronize()<\/code> persists the updated information to storage such that other applications (such as iOS Settings) can retrieve the value.<\/p>\n

Run the application again, browse to the iOS Settings for the application, and find<\/p>\n

\"appversion_final\"<\/a><\/p>\n

To increment your build<\/i> number, go to your project target and simply change it, rebuild the application, and see the new number available in the settings page.<\/p>\n

Again, we’ve tiptoed around the topic of how and when to update your build version. In the past I’ve written elaborate scripts which ran under CruiseControl<\/a>, extracted the SVN version number, injected that number into the Info.plist<\/code> using PListBuddy<\/a>, generated fancy build records that could be used independently to package other components together, etc. In the end I found that it was often more trouble than it was worth, and if you are running a development team with only a handful of folks, simply appoint one to be responsible for building the version that gets tested and eventually posted to Apple for review. They can either build the application by hand (using Xcode) or develop automated tools for it; the important thing is the information is unique for each build distributed and can easily be viewed!<\/p>\n","protected":false},"excerpt":{"rendered":"

It is a universally recognized best practice to visibly expose your iOS application’s version number somewhere on the screen. Often times you will see it on the application’s splash screen or can get to it by selecting the About menu item (assuming the application has a menu). No matter where it’s location (I have my […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5,2],"tags":[],"class_list":["post-794","post","type-post","status-publish","format-standard","hentry","category-swift","category-xcodetips"],"_links":{"self":[{"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/posts\/794"}],"collection":[{"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/comments?post=794"}],"version-history":[{"count":20,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/posts\/794\/revisions"}],"predecessor-version":[{"id":822,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/posts\/794\/revisions\/822"}],"wp:attachment":[{"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/media?parent=794"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/categories?post=794"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.iachieved.it\/iachievedit\/wp-json\/wp\/v2\/tags?post=794"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}