Manage App updates

When an new version of an app installs on a device, you might want to keep all or part of the data created with the previous version.

It is the role of the deployed program to manage the updates.

App Update Strategy

Detect if a previous app is installed. Each deployed app should store a file (named version.txt for this example) that contains the version of the deployed app. This file allows the app to detect if an older version of the app is installed by checking for the existence of the version.txt file. By reading the file contents, the app can retrieve the exact version of the previously deployed app.

When no previous app is detected, perform a fresh install. This might involve these tasks:
  • Create version.txt.
  • Create configuration files.
  • Create and populate the database.
  • Copy read-only files to the writable document area.
When an previous install of the app is detected and its version identified, perform an upgrade. This might evolve these tasks:
  • Update version.txt to the new version number.
  • Convert existing configuration files to a new file format.
  • Upgrade the database schema while keeping the data.
  • Delete obsolete files.
  • Copy read-only files to the writable document area.
    Tip: Having a clear separation between the initialization data (in the read-only directory) and the current user data (in the read-write directory) can help you manage your upgrades.
    You are provided with two APIs that allow you to reference the underlying directories transparently:
    • The base.Appliation.getProgramDir() method returns the base program directory, storing your compiled files, an initial database file, and so on. On an iOS device, this is a read-only directory.
    • os.Path.pwd() defines a writable directory for holding writable files, such as an error log or the user database.

When the version of the previous install is an older version of the app, a strategy might be to run in sequence all upgrade scripts from the detected version to the latest. For example, when installing v1.5 on a device where v1.3 is the previous version, the upgrade script from v1.3 to v.4 will be executed first, then the upgrade script from v1.4 to v1.5.

This strategy involves storing modified data outside of the directory folders where the app installs, to prevent user data from being overwritten during install. This allows the programmer to read old data and do the appropriate steps to (eventually) convert them to a newer format.

Tools

The Diff Schema and Generate Database Update Script tools in Genero Studio provides database migration scripts from a previous database schema to a newer database schema.
  • Diff Schema identifies the differences between two schemas
  • Generate Database Update Script takes the file created using Diff Schema and generates an upgrade script. This database upgrade script can be incorporated in the app sources to manage the database upgrade.

These scripts can be called in sequence to migrate from an older version to the current.

Testing updates

App updates should be tested in a real life environment.
  • Install the previous production app on a device.
  • Use the app such that it stores user data.
  • Deploy the new version of the app.
  • Verify the upgrade works as expected.

For more information, see Technical Note TN2285: Testing iOS App Updates in the iOS Developer Library.