iOS-factor: Best Practices for Building High-Quality iOS Apps

Each topic is covered by a factor, describing the ideal state of iOS app development

Anatolii Kasianov
Aug 7 · 7 min read
Photo by Emils Plinte on Unsplash

That feeling, when you pull the old project from Git and it does not compile…

Even though this project is in the App Store, “production-ready”, the previous developer did not maintain it properly. There are many possible reasons — deprecated Swift version, external dependencies, missing certificates…

iOS-factor was inspired by the famous Twelve-Factor App framework,
a methodology to write high-quality web services. iOS-factor uses the same structure and similar principles, re-written and applied to the iOS app development processes.

It aims to provide a collection of best practices for building high-end iOS applications.

Each topic is covered by a factor, which describes the ideal state of what a certain category of the iOS app development process could look like.

This article is a summary. You can also read the full series. The project was started by Felix Krause.


1. Dependencies

Ideally, your build tools never rely on the implicit existence of system-wide packages.

It declares all dependencies, completely and exactly, via a dependency declaration manifest. This includes the exact versions of Xcode, CocoaPods, and fastlane.

The benefit of explicit dependency declaration is that it simplifies setup for developers new to the app, as well as having a reliable build system that is also able to run past-builds again in a reproducible fashion.

As iOS development cannot be containerized, as is already the case for web development, we’re limited to third-party tools for fulfilling this requirement, until Apple provides an official solution.

2. Config

Apps sometimes store configs as constants in the code. This is a violation of iOS-factor, which requires strict separation of config from code. Config varies substantially across deploys, code does not.

There are many ways to inject config values during build time:

As deployments on the iOS platform are significantly slower than server deployments, you might want a way to quickly update config over the air (OTA) to react to issues quickly.

OTA config updates are powerful and allow you to instantly:

Potential approaches to implementing OTA updates of config:

3. Dev/Prod Parity

Historically, there have been substantial gaps between development (a developer making live edits to the app on their local machine) and production (an app deployed on the App Store, accessed by end-users).

An iOS-factor app is designed for continuous deployment by keeping the gap between development and production small.

Looking at the three gaps described above:

4. Deployment

As described in the dependencies factor, the code repository should include all dependencies needed to build, test, and release the iOS app.

Unfortunately, because Xcode has to run on macOS, we can not use Docker or containers.

Right now, the best approach we can take, as iOS developers, is:

5. Prefer Local Over Remote

In recent years, some development teams have started to use approaches that require less development work, at the expense of the user’s app experience. They’re moving more logic to a remote back end and have the iOS app be a thin client showing the server results.

This approach results in user frustration when the app is used in a situation with a less-than-perfect internet connection.

An app should do as much of the business logic and calculations on-device as possible, for a variety of reasons:

If your app requires an internet connection for everything (e.g. social networking app or ride-sharing app), your app should still work (in read-only mode) without an internet connection to access historic data (e.g. recent rides, recent direct messages).

6. Backwards-Compatible APIs

While the majority of your end-users will update to the most recent update within a few weeks, there will always be a subset of users who won’t.

The basic concept is that you don’t update an existing API but add a new one instead and let them run in parallel.

7. App Versioning

Version and build numbers work together to uniquely identify a particular App Store submission for an app:

In today’s iOS development process there is no reason to manually change those numbers.

There is no need to use third-party tools, Xcode has a tool called agvtool built-in. (more details).

8. Rollbacks

The App Store doesn’t natively allow rollbacks, so this section describes how to achieve similar results, using the technology available.

Using phased releases, you can slowly roll out a build to production, starting with a subset of the active users.

The main benefit of this approach is the built-in way to pause a rollout, before it reaches a high amount of users, allowing you to replace the binary.

However, even with phased releases, there is no way to completely revoke a build.

As with phased releases, App Store and TestFlight builds can only be updated by doing this:

The above steps can be done manually, however, it is recommended to fully automate the process so you can react quickly.

Alternative: Resign an old build:

However, resigning iOS apps often introduces more problems, especially because the Xcode command line tools offer no good way of doing so.

9. Persistence of Data

Storing data and configurations according to Apple’s guidelines is crucial for your app’s lifecycle, in particular when it comes to iCloud sync, upgrading to a new phone, and restoring a phone from a backup.

Make sure you follow Apple’s official iOS Data Storage Guidelines:

Never store sensitive user information (like passwords or sessions) in those directories. Instead, use the keychain API.


This is a living project, maintained by the iOS development community.

You can find the full source on GitHub, update existing pages, or add new factors.

Better Programming

Advice for programmers.

Anatolii Kasianov

Written by

iOS developer from Kyiv, Ukraine. Available for my next remote contract.

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade