This document is the base of the wiki documentation currently available at: https://github.com/TheRealKerni/HockeyKit/wiki
Easily distribute applications, including updates with maximum ease of use for end-user and great flexibility for developers.
-
Over-The-Air app distribution
Distribute your applications via an automatically generated, and optimized for each type of client. So your app can be installed directly when invoked from a mobile device, or downloaded if called from a desktop computer.
-
In-App-Updates
Optional client to be integrated into your applications. Works similar to the Sparkle framework on the Mac. The app checks if there is an update available from your server and will provide upgrade options. If the operation system does not support OTA updates, the client will still inform the user about available updates.
-
Multiple Application Support
Provide multiple applications from one server to multiple clients and testers. Either by providing them all on a single web site, or individual pages per application.
-
Automatically generated web pages
Device specific and optimized web pages are automatically generated for each application. So the tester can either install the application directly if loading the web page on a device, or download the files when loading the web page from a desktop computer.
By default all available applications appear in a single web page, but there is also an option to provide individual pages for each or selected applications.
-
Multiple Version Support
Upload multiple version of the same app to the server. Useful with the "Team Management" feature. It also provides you the option to store specific release notes per version.
-
Team Management (iOS 4.x only, API V2 required)
Assign devices (and their users) to specific teams and provide them different app versions. Your designer should get the latest unstable version but your clients Q&A testing only gets the most stable ones. This feature requires the apps to include the Hockey client.
-
Device Authentication (iOS only, API V2 required)
Add another security level to your applications. If non-authorized persons gets hold of your application, they could re-sign the application with their own certificates. This feature activates device authentication against your own Hockey service and blocks the application from being used if the device is not authorized.
-
Installation statistics (iOS only)
See which device is of which type, the installed app version, the system language (API V2 only), the OS version and see the last time the app has been started.
-
Does not require a database, PHP5 sufficient
The server only uses the filesystem and PHP5. There are no additional requirements.
-
Easy to setup and use
The server component is designed to be managed without any database, it only uses the filesystem to achieve all of its functionalities. This makes it very easy to install and maintain.
-
Server
The server is the heart of Hockey. It provides all the features, handles the apps and app versions, statistics and generates the website to download and install each app.
The server is backwards compatible with Hockey version 1.0, but a lot of features require the client to be upgraded to version 2.0.
-
Client
The optional client eases distribution of your apps updates and enables additional features like "team management" and "device authentication".
Most importantly it enables upgrading versions absolutely seamless for your testers. They only need to install the app once by invoking the web interface provided by the server and can then focus on testing the app. Every update will be presented on start up of the application. You could even stop reminding them on updates via email, since if they are good testers, they should use the app frequently anyway ;)
The client will present version specific release notes to the user, and if the different versions are stored individually on the server, even provides the option to see the complete release notes history. This is also very helpful if the tester is going to skip one or multiple version and will still see all the changes made since the last installed version.
- iOS
- Android
The branching structure follows the git flow concept, defined by Vincent Driessen: http://nvie.com/posts/a-successful-git-branching-model/
The main branch where the source code of HEAD always reflects a production-ready state.
Consider this to be the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release. Some would call this the “integration branch”.
These are used to develop new features for the upcoming or a distant future release. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).
These branches support preparation of a new production release. By using this, the develop branch is cleared to receive features for the next big release.
Hotfix branches are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned.
The following steps assume that you are installing Hockey on an Apache server.
-
Have a server accessible to your potential testers with PHP 5 support
-
Create a directory which will hold you applications, later referred as the public server directory.
-
Copy the content of the public directory in the repository, including the .htaccess file (!), onto your server into the public server directory created in 2.
-
Create another directory on your server, preferably outside the public accessible HTML path (for better security), later referred as the include server directory
-
Copy the content of the includes directory into this include server directory created in step 4
-
Open the public server directory created in 2. and open the config.php file in an editor. Adjust the path to relatively point to the include server directory created in 4.
-
Open the stats directory inside the public server directory
-
Grant the php process write access to the userlist.txt, usually be activating write access for the unix group
-
To restrict access to the stats directory open the .htaccess file inside the stats directory in an editor
-
Adjust the AuthUserFile parameter to point to a .htpasswd file containing the user and password to access the stats page via a browser
Note: Refer to your server documentation on how to generate a .htpasswd file. For more information check out the Apache documentation
Note: Make sure the server is set to override directory specific settings in the hockey folder, in Apache this is handled with the AllowOverride All setting. And also make sure it has rewrite rules enabled, in Apache this is usually done with the following line:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
-
Open the public server directory
-
Create a new subdirectory with the name of the bundle identifier of your application, e.g. com.yourcompanyname.myapplicationbeta, later referred as the application directory
It is highly recommended to use separate bundle identifiers for the release, beta and debug version of your application. This way you and the testers can use them side by side on the device which makes testing easier and always having a fallback possibility. For developers this eases bug reports reported for release versions.
There are two options to add an actual application version. You can later migrate between these two pretty easily, but lets make the differences clear first. The first option is to have only one version of an app available. This means that every new version will have to overwrite the previous files on the server.
Please note that there may be only one file of each type present in a directory. If there are multiple files of a type, the server will randomly choose one.
By default only the extension name of a file is important and visible by showing a "." at the beginning of the file definition, the name of the file can be anything. There are exceptions, of course.
The second option having multiple versions per application stored, is required to use the feature Team Management and allowing the Hockey client to present all release notes for all available versions. It is highly recommended to use this option.
- Upload the app package into the application directory
iOS: The app package is a .ipa file. Android: The app package is a .apk file. 2. Upload the application manifest file into the application directory
iOS: This is a .plist file, the format is defined in the appendix Android: This is a .json file, the format is defined in the appendix
Ever single version of the application has to be stored into its own subdirectory under the application directory, referred to as version directory. For obscurity reasons, it is possible to add a prefix string to the name of each version directory. This prefix string has to be identical for each version inside a application directory. Hockey will reverse sort the subdirectories to identify the latest version.
Example version directory names:
aksufy1
aksufy2
aksufy3
aksufy4
aksufy5
In this example, the version directory aksufy5 will contain the latest version.
Once a new version directory has been added, simply upload the files mentioned above in Only have on version available into this version directory instead.
-
Adding Release Notes
Release notes are written in HTML and provided in a .html file in the same directory as the application package is located
-
Adding Application Icon
The application images can be provided as a .png file, copied into the application directory
-
Hiding application from main web page
Place a file named private into the application directory. This will hide the application from the main page and make it only accessible via the application specific web page. To get that specific page add /apps/bundleidentifier to your hockey installation path, where bundleidentifier is the bundle identifier of the requested application, e.g. http://www.yourdomain.com/beta/apps/com.mycompany.myapp. Watch for case-sensitivity of the bundle identifier!
-
Restricting access to specific teams (iOS only)
Place a .team file inside the version directory. Add a comma separated list of team strings which will get access to this specific app version. If non of the team strings is actually associated to any device, this app version will not be available for anybody. Definition of the possible team strings, will be described below in TODO
Please note that there has to be at least one version without team access available, otherwise you would have to distribute individual versions via email or something else. That is because app version restricted for a team will not be shown on the web page, so initial installation will not be possible!
Defining the devices is required to enable the Team Management, Device Authentication and Stats features. The definition of a team is optional, but required if the Team Management feature should be used. The file to edit is named userlist.txt and located inside the stats directory, which itself is inside the public server directory.
Example:
# UDID;the testers name;team1,team2
C8E3F82A-4E2B-5509-A1BE-52984C5CE592;Andreas Linde;hockeycore
C8E3F82A-4E2B-5509-A1BE-52984C5CE593;Stanley Rost;hockeycore
C8E3F82A-4E2B-5509-A1BE-52984C5CE594;Dummy User
The file defined one device per line, comments are allowed by starting a line with the # character. Each line defines its data semicolon separated and the optional team names are comma separated
Explanation:
- The first element defined the device UDID
- The second element defines the name to be shown for this device, usually the owners name
- The third element is optional, and defines the associated team strings to this device. So team strings are defined implicitly by adding any string to a device.
It is possible to import the UDID strings and names from the Apple developer portal. Follow these steps:
- Invoke the /stats/index.php page in the browser on your desktop computer
- Follow the instructions shown in the footer of the page.
The first option to integrate the client is by downloading the sources and integrate them into your repository. You might already have some required 3rd party frameworks integrated into your project, like the JSONKit parser. Simply leave those out and replace them with the most recent version.
Add all the files from the /client/iOS/ folder, except the Beta Automatisation and HockeyLib folder into your project. If you already have a supported JSON library present in your project, then there is no need to copy the one from HockeyKit. The currently supported JSON frameworks are JSONKit and SBJson.
t.b.d.
t.b.d.
-
Add the following setting to your Xcode project settings Preprocessor Macros
CONFIGURATION_$(CONFIGURATION) -
Include the following frameworks into your project, if they are not yet present:
SystemConfiguration.framework QuartzCode.framework CoreGraphics.framework UIKit.framework Foundation.frameworkTo add frameworks into Xcode 4, select the project, the target, the Build Phase tab and open the Link Binaries With Libraries expander. Click on the + button to add frameworks.
-
Include the header into your UIApplicationDelegate subclass, this assumes your AppStore distribution configuration is named AppStore_Distribution
#if !defined (CONFIGURATION_AppStore_Distribution) #import "BWHockeyManager.h" #endif -
Initialize Hockey with the code below and replace the URL to point to your server hockey public URL path (without index.php !).
Optionally adjust additional Hockey parameters. The first update check will be invoked automatically in the next runloop.
// This variable is available if you add "CONFIGURATION_$(CONFIGURATION)" // to the Preprocessor Macros in the project settings to all configurations #if !defined (CONFIGURATION_AppStore_Distribution) [BWHockeyManager sharedHockeyManager].updateURL = @"http://your.server.com/"; #endif -
Optionally set the UIWindow rootViewController property (iOS 4 only, make sure it is not set on iOS 3.x if you require compatibility) which should be used to push the modal Hockey Update view onto. If it is not set Hockey will try to find the best way by itself.
if ([window respondsToSelector:@selector(setRootViewController:)]) { [window setRootViewController:YourRootViewControllerClass]; } -
If you want the update view to be accessible without a new update being actually, add the BWHockeyViewController to your In-App Settings page
#if !defined (CONFIGURATION_AppStore_Distribution) BWHockeyViewController *hockeyViewController = [[BWHockeyManager sharedHockeyManager] hockeyViewController:NO]; // ... // Pass the selected object to the new view controller. [self.navigationController pushViewController:hockeyViewController animated:YES]; #endif
t.b.d.
t.b.d.
-
updateURL (required)
Value: NSString
default: nil
Description: URL pointing to your server setup, e.g. http://beta.myserver.com/
-
delegate (optional)
Value: id
default: nil
Description: the delegate instance responding to BWHockeyManagerDelegate protocol
-
sendUserData (optional)
Value: BOOL
default: YES
Description: Send the current user data: device type, iOS version, app version, UDID. Required to be YES for team management
-
sendUsageTime (optional)
Value: BOOL
default: YES
Description: Send the the users usage time of the app to the service, only in 15 minute granularity!
-
allowUserToDisableSendData (optional)
Value: BOOL
default: YES
Description: Allows the user to overwrite the developers settings of sendUserData and sendUsageTime. showUserSettings has to be set to YES to allow the user to change the settings which the developer activated. If the develop does not activate sendUsageTime e.g., the user also cannot change it.
-
alwaysShowUpdateReminder (optional)
Value: BOOL
default: NO
Description: Display the new version alert only once (NO) or always if the current version is outdated (YES)
-
checkForUpdateOnLaunch (optional)
Value: BOOL
default: YES
Description: Check for updates will be performed after the application becomes active. If set to NO you have to take care your to invoke the checks yourself in your code by calling - (void)checkForUpdate;
-
showDirectInstallOption* (optional)
Value: BOOL
default: NO
Description: Shows an install button in the alert view notifying about pending updates. This way the user can install the update without checking the update screen first.
-
requireAuthorization (optional)
Value: BOOL
default: NO
Description: Each new version requires an authorization against the server, if that is denied, the version will always be block the screen. The authenticationSecret has to be also set and be identical to the server side setting!
-
authenticationSecret (optional)
Value: NSString
default: nil
Description: Defines the secret string which is also used to generate the authorization token string. It is mandatory if requireAuthorization is set to YES. And the value has to be identical to the server side secret token.
-
compareVersionType (optional)
Value: HockeyComparisonResult (HockeyComparisonResultDifferent, HockeyComparisonResultGreater)
default: HockeyComparisonResultDifferent
Description: Alert about a new version if the version string is different or if the evaluated version number is greater than the currently installed version number
-
updateSetting (optional)
Value: HockeyUpdateSetting (HockeyUpdateCheckStartup, HockeyUpdateCheckDaily, HockeyUpdateCheckManually)
default: HockeyUpdateCheckStartup
Description: Defines how often Hockey should check for updates, if set to HockeyUpdateCheckManually, make sure to allow the user to navigate to the hockey update screen from within your UI, otherwise he/she will never be able to check for new updates!
-
showUserSettings (optional)
Value: BOOL
default: YES
Description: Let the user change the updateSetting value or not
All methods are optional.
-
- (void)connectionOpened
Invoked when the internet connection is started, to let the app enable the activity indicator.
-
- (void)connectionClosed()
Invoked when the internet connection is closed, to let the app disable the activity indicator.
-
*- (UIViewController *)viewControllerForHockeyManager:(BWHockeyManager )hockeyManagerConnectionOpened()
Optional parent view controller for the update screen when invoked via the alert view, default is the root UIWindow instance.
The file is defined by Apple and available here. To make the usage of this file easier with Hockey, there are some things to know:
-
The value of the url key has to be URL
When uploading the application and creating the .plist file, you don't have to know the exact URL the .ipa file will be accessible with. Hockey will take care of this.
-
Don't add the application icon data!
If there is an application icon available in the application directory, Hockey will automatically add the required data to the .plist file.
By default Android does not need such a manifest file for distribution apps. But for Hockey to show a proper name and version information on the web page and in the client, this is required.
The structure is pretty simple, so here is an example:
{
"title": "HockeyDemo",
"versionCode": 2,
"versionName": "1.0"
}
Explanation:
- Title: The string to be shown as the name of the application
- versionCode: Identical to the versionCode value used to build the version
- versionName: Identical to the versionName value used to build the version