How to create a new version

This how-to describes how to create a new version for an existing app on HockeyApp. If you don't have an app, please read How to create a new app first.

Before uploading files to populate a new version, it is important to understand what these files do. Creating an app enables HockeyApp to gather crash data, but you will need to upload a symbolication or deobfuscation file, which allows HockeyApp to translate memory addresses into locations in your original source code. Uploading a build allows you to distribute your app directly to testers from HockeyApp.

Creating a new version

There are four methods to create a new version. In addition, HockeyApp will automatically create a new version when a crash for your app, feedback or user metrics is received and the version does not exist. The version number is taken from the data received to create the version. You can then upload symbolication and deobfuscation files later, but be aware that those files will not have retroactive effects--that is, your initial crash reports will refer only to locations in memory, and only crash reports after the upload of those files will give meaningful stack traces.

The new HockeySDKs (4.0.0. and newer) can send metrics data to our backend and a corresponding app version will automatically get added to the app. Depending on your development process, this might result in a multitude of empty builds in HockeyApp. You can disable metrics collection for debug build as described in this article.

1. Drop .ipa or .apk on the dashboard (beta apps only)

This method only works if the bundle identifier (iOS) or package name (Android) matches the bundle identifier of the app.

Drag an .ipa file for iOS or .apk file for Android from a Finder window and drop it on the dashboard. The upload will start immediately and the progress is shown with a progress bar. When the upload is finished, the status will change to "Processing" and afterwards you are redirected to the version page.

2. Drop .ipa, .apk or .dsym on the app page (.ipa and .apk for beta apps only, .dsym for all types)

Click on the app's icon on the dashboard to load the app page. Drag an .ipa file for iOS or .apk file for Android from a Finder window (or Windows Explorer or your favorite Linux file manager) and drop it anywhere on the app page. The upload will start immediately and the progress is shown with a progress bar. When the upload is finished, the status will change to "Processing" and afterwards you are redirected to the version page.

3. Upload via API (beta apps only)

In addition to uploading from a browser via the HockeyApp Dashboard you can upload an .ipa file for iOS or .xcarchive for Mac or iOS via the HockeyApp for Mac uploader or the HockeyApp for Windows uploader or upload .ipa, .apk or .dSYM.zip files via the API.

4. Manual entry (all app types)

Click on the app's icon on the dashboard to load the app page. Click on the blue "Add Version" button, then on the link "manually". Fill out the form as follows:

  • Version / Version Name: optional; use for your marketing version number (e.g. 1.0)
  • Build Number / Version Code: required; use incremental build numbers for each version (e.g. 1, 2, 3) and put the marketing version number into the Version field (e.g. 1.0); you can use other numbering schemes, but must ensure that the Bundle Number is different for every version.
  • Accept Crash Reports: default "yes"; select "no" if HockeyApp should not accept crash reports for this version.
  • Release Notes: optional; write either plain text, Textile or Markdown.

After the version has been created, you can edit it's details by clicking on the "Manage Version" button on the version page. Please note that you can not edit the bundle version or bundle short version if you have uploaded an .ipa or .apk file.

Note: New apps won't appear to users if you don't increase the CFBundle Version (iOS)/Version Code (Android) with each new build via your perl script or in the GUI, since the most recent version of an app is always based on Bundle Version (iOS)/Version Code (Android).

Automatic Updates

Important: Automatic updates only work if you increase the build number (iOS: CFBundleVersion, Android: versionCode) with every new version on HockeyApp!

  • In order to push automatic updates of your app to your users, you will need to enable automatic upgrades in the SDK integration process for your app.
  • You can use the API or GUI to set a version as a "mandatory update" via the API or GUI to require your users to upgrade in order to continue to use your app.
  • You can also use the API or GUI to set the "minimum version" of the users' operating system that is required in order to download the update.
  • If your app is restricted, then your users will need to authenticate in order to download the latest version of your app.

Note: HockeyApp can only prompt users to install the newest update, it can't install updates automatically without user interaction. The Apple store also only prompts users to install updates. Currently, only the Google Play store can update apps without user interaction.

Code Signing

Before uploading a build to HockeyApp for distribution, you should perform the necessary steps to code sign that build.

You can review the steps for code signing on many platform sites, including

Note that in the event of an improperly signed app, iOS devices will raise an error that the app has been damaged.