This plugin provides client-side integration for the HockeyApp service, allowing you to easily add crash reporting, beta distribution and user metrics to your Cordova app(s).
Cordova 5.0.0+ is fully supported, along with the following associated platforms:
To check which versions of each Cordova platform you are currently using, you can run the following command and inspect the
Installed platforms list:
cordova platform ls
If you're running an older Android and/or iOS platform than is mentioned above, and would be open to upgrading, you can easily do so by running the following commands (omitting a platform if it isn't neccessary):
cordova platform update androidcordova platform update ios
After you've created your HockeyApp account, and registered your app with the service, you can begin integrating the Cordova plugin into your app by running the following command:
cordova plugin add cordova-plugin-hockeyapp@latest
With the CodePush plugin installed, configure your app to initialize the HockeyApp client (using your app ID) by calling the following function within your
deviceready handler (or the equivalent location):
hockeyappstartnull null "APP_ID";
As a reminder, the app ID can be retrieved from the details page of your app in the HockeyApp portal (see the
App ID field below).
If you would like to test out the crash reporting feature and don't already have a crash in your app (nice job!), you can add the following method call anywhere in your app:
And that's it! Your app will now send crash reports and user metrics (e.g. daily/monthly unique users, # of sessions per day) to the server without doing any additional work. Make sure to remove the call to
forceCrash once you're satisfied with your test and are ready to begin sending your app to testers and on into production.
If you would like to add additional capabilities to your app (e.g. detecting updates, capturing user feedback, adding custom instrumentation to view app-specific usage data), then check out the following sections, or view the API reference for more details.
If you're using HockeyApp to distribute beta builds to your testers, then you'll likely also want to collect feedback from them in addition to simply viewing crash reports and usage metrics. To do this, simply call the following method in order to display a UI to your users that allows them to send receive feedback directly to you:
You can call this method in response to a "Give Feedback" button, in a shake gesture handler, or wherever is appropriate for your app.
If you would like your beta testers to be notified whenever a new version of your app is available, you can call the following method to check for an update and display a dialog when available:
You can call this method in your
deviceready handler, in a "Check for update" button, or wherever is appropriate for your app.
NOTE: This should not be called in production/release builds intended for the Google Play Store.
NOTE: Using this feature currently requires being registered with the HockeyApp preseason program.
By default, once you've called the
hockeyapp.start() method, your app will begin automatically collecting basic metrics for daily and monthly users and sessions. However, it is very likely that you will want to track custom app events (e.g. "View_Cart", "Added_Item") in order to understand how your users are engaging with your app at a more granular/actionable level. In order to instrument your app to capture this data for both beta and production collection, simply call the following method where appropriate in your app:
By default, any time your app crashes, the report sent to HockeyApp will include the call stack, as well as various other pieces of information (e.g. OS, device manufacturer) to help narrow down and/or repro the cause of the issue. However, it can be very helpful to understand the context of the users app when inspecting a crash report, and therefore, if you need to "attach" additional metadata to a crash report, you can simply add the following line of code:
addMetaData method will "merge" the objects together such that any future crash reports will include a union of all object properties that were specified by any call to
When you view a crash report in the HockeyApp portal, you can see the metadata that you attached to it by selecting the Description button underneath the Data section within the Crash Logs tab of the respective crash report.
The HockeyApp API is exposed to your app via the global
hockeyapp object, which is available after the
deviceready event has fired. This API exposes the following top-level methods:
addMetaData - Attaches arbitrary metadata to the next crash report in order to provide more context about the user's state.
feedback - Displays the feedback UI so that testers can send and receive feedback about the app.
forceCrash - Immediately crashes the app. This is used strictly for testing the HockeyApp crash reporting capabilities.
start - Initializes the HockeyApp plugin, and configures it with the approrpiate app ID and user settings (e.g. should crash reports be automatically submitted).
trackEvent - Logs an app-specific event for analytic purposes.
successCallback - Function that will be triggered when the metadata has been successfully added.
errorCallback - Function that will be triggered when adding the metadata failed for some reason.
Displays the feedback UI so that testers can send and receive feedback about the app.
successCallback - Function that will be triggered when the feedback UI is successfully displayed.
errorCallback - Function that will be triggered when an error occurs displaying the feedback UI.
Immediately crashes the app. This is used strictly for testing the HockeyApp crash reporting capabilities.
Initializes the HockeyApp plugin, and configures it with the appropriate app ID and user settings (e.g. should crash reports be automatically submitted).
successCallback - Function that will be triggered when the initialization is successful.
errorCallback - Function that will be triggered when an error occurs trying to initialize the plugin.
appID - The ID of the app as provided by the HockeyApp portal.
autoSend - Specifies whether you would like crash reports to be automatically sent to the HockeyApp server when the end user restarts the app. Defaults to
ignoreDefaultHandler - Specifies whether you would like to display the standard dialog when the app is about to crash. This parameter is only relevant on Android, and therefore, you can set it to anything on iOS. Defaults to
loginMode - The mechanism to use in order to authenticate users. Defaults to
hockeyapp.loginMode enum provides the following available options:
ANONYMOUS - The end user isn't authenticated at all.
EMAIL_ONLY - The end user will be prompted to specify a valid email address. If this mode is selected, the
appSecret parameter must also be specified.
EMAIL_PASSWORD: The end user will be prompted for a valid email/password combination.
VALIDATE: The end user will not be prompted to authenticate, but the app will try to validate with the HockeyApp service.
NOTE: Only the
ANONYMOUS login mode is supported on iOS, and therefore, you can only use the other modes within Android apps.
appSecret - The app secret as provided by the HockeyApp portal. This parameter only needs to be set if you're setting the
loginMode parameter to
Logs an app-specific event for analytic purposes.
successCallback - Function that will be triggered when the event has been successfully tracked.
errorCallback - Function that will be triggered when tracking the event failed for some reason.
eventName - The name (e.g. "ITEM_ADDED") of the custom event that should be logged.