Beta Test with HockeyApp
This is part two of a four part series and assumes you’ve already set-up continuous integration with our sample project. If you haven’t already, I highly recommend reading Continuous Integration for Cordova Apps.
Unit tests and end-to-end tests provide a great sanity check before pushing code into source control, but the best bugs are often discovered through manual testing. Real human users just have a better sense for when something isn’t “right.”
For beta testing, I prefer HockeyApp over Apple TestFlight or the Google beta program because it allows me to distribute to unlimited beta testers, collect crash analytics and user feedback.
With HockeyApp, I can:
- Upload my apps manually through the website or through a CI system
- Distribute to a controlled group of iOS, Android and Windows users
- Collect detailed crash reporting and analytics
- Collect user feedback (e.g. send messages, attach screenshots, threaded communication)
- Control the app version installed on user devices
- Integrate with most popular bug tracking systems
HockeyApp is also free for accounts with up to 2 apps, so it’s a no-brainer to try.
Get Started
While HockeyApp allows you to manually upload app packages through their website, we want to automate releases through our build server on VSTS. So, let’s start by creating a free account on http://www.hockeyapp.net.
Once you’ve created an account, we need to establish trust with VSTS by sharing an API Token. Go to Account Settings within the HockeyApp portal and select API Tokens in the sidebar. From here, create an “All Apps” token with “Full Access” rights. HockeyApp will generate a 32-character token. You’re going to use that token in a minute, but just keep the tab open for now.
Switch to a new browser tab and open the Build tab of your VSTS account. Right-click on the Android-Build definition that you previously created and select Clone. After all, there’s no need to start from scratch again. In the cloned build definition, add the HockeyApp build step after “Cordova Build”.
To get the HockeyApp Connection, you’ll need to take one extra step. Click Manage adjacent to the input box. In the new window, select HockeyApp, then enter the 32-character token you created in HockeyApp.
When you return to VSTS, simply click the refresh button adjacent to the drop-down to make your new connection appear. Configure your build step as pictured below:
Label | Value | Why? |
---|---|---|
HockeyApp Connection | All Apps | Points to the API token you created in HockeyApp and establishes trust |
App ID | com.ryanjsalva.superfly | This is the default App ID of my sample project. You can find/change it by looking for the <widget> tag in config.xml |
Binary File Path | platforms/android/build/outputs/apk/android-debug.apk | Default location where Cordova outputs the native app package |
Symbols File Path | Not used by our project | |
Native Library File Path | Not used by our project | |
Release Notes (File) | Not used by our project | |
Release Notes | Recommended update. | Because if we say it’s “recommended”, surely they’ll install it, right? |
Publish | Checked | Immediately publishes to HockeyApp |
Mandatory | Unchecked | Not a required update |
Notify Users? | Checked | Users are more likely to install if you tell them something is available |
Tags | No tags mean the update goes to everyone | |
Teams | No teams mean the update goes to everyone | |
Users | No users mean the udpate goes to everyone | |
Enabled | Checked | We want to run this build step |
Continue on error | Unchecked | Stop the presses when there’s a build error |
Always run | Unchecked | Since we never continue on error, it’s okay to leave this unchecked |
Save this build definition as Android-Beta. We won’t build yet because there are still a few code changes necessesary, but celebrate anyway with a song in your headphones. I recommend The Modern Lovers’ Girlfriend.
Invoke HockeyApp from Code
The HockeyApp SDK is delivered as a Cordova plugin. That plugin is already installed in our sample project (you’re welcome), but we need to invoke it. Fortunately, that only requires modifying a few lines. In /www/js/app.js, uncomment the following line and replace “APP_ID” with the value for <widget id="APP_ID">
found in config.xml. Assuming you don’t create your own APP_ID, the value will be “com.ryanjsalva.superfly”.
Note that the APP_ID needs to match in three places:
Location | Value | Why? |
---|---|---|
/config.xml | <widget id="APP_ID"> |
Authoritative source for APP_ID |
/www/js/app.js | hockeyapp.start(null,null,"APP_ID") |
Establishes app identity when calling into the HockeyApp API |
VSTS | HockeyApp build step configuration | I honestly don’t know |
Next, we need to uncomment a few lines from /www/js/controllers.js
These methods will be invoked when we click the corresponding menu items in our app’s menu bar. As you can see, there’s not much to them. The one thing I’d call out is hockeyapp.addMetaData([json])
. You can invoke this method at any time to record n parameters describing your runtime state. This can be tremendously helpful if you need help debugging you app in the wild.
Run that build, you crazy kid
Now, you’re ready to automate your next build with another commit. Go back to Terminal and run:
When you return to VSTS, you should find a build in the queue for Android-Beta.
Install HockeyApp on your Android Device
While that’s building, grab your Android phone and install HockeyApp. HockeyApp is also available for iOS and Windows, but this tutorial only builds for Android… so, hopefully, you’ve got an Android phone handy 😛
After authenticating on your Android device – and assuming the beta build has completed – you should see an app appear in your HockeyApp mobile client. Install and open it. You’ll find at least two fun features to try in the sample app sidebar menu:
- Fake Crash will force the mobile app to crash so you have a chance to explore HockeyApp’s crash analytics
- Send Feedback allows beta testers to submit feedback to the development team directly through the app. Don’t forget to try attaching a picture (e.g. a screenshot) where you can annotate with crude finger drawings.
Once you’ve had a chance to play with the app and forced a few crashes, go back to the HockeyApp portal. With a few minutes of exploring, you’ll find lots of neat features. Listen to a song in your headphones while exploring, I recommend “March of the Nucleotides by Bit Shifter.”