HockeyApp for Android (SDK)

General

This article describes on how to integrate HockeyApp into your Android apps. The client allows testers to update your app to another beta version right from within the application. It will notify the tester if a new update is available. It also allows to send feedback and crash reports right from within the application. If a crash has happened, it will ask the tester on the next resume of the main activity whether he wants to send information about the crash to the server. The latter feature works for both beta apps and apps for Google Play.

In addition to HockeySDK, we also offer a native app for Android to download & install new apps, manage invites, and register the devices.

Requirements

The SDK runs on devices with Android 2.3 or higher, but you need to build your app with Android SDK 3.0 (Level 11) or higher for the integration with HockeySDK. Please contact Android or Amazon for general Android App or Amazon App development questions not directly related to HockeyApp.

Integrate HockeySDK

We recommend integration of our compiled library into your project using Android Studio and Gradle.
For other ways to setup the SDK, see advanced setup.
A sample integration can be found in this GitHub repository.

Note: For initial setup it is assumed that you want to use all of HockeyApp's features such as crash reporting, update distribution, and feedback. This means your app also needs all the basic permissions. If you only want to use a subset of features and thus only need to ask for a subset of permissions, please see the permissions section of our Readme on Github.

Add the SDK to your app module's dependencies in Android Studio by adding the following line to your dependencies { ... } configuration:

compile 'net.hockeyapp.android:HockeySDK:4.0.0'

also make sure your repository configuration contains

repositories {
  mavenCentral()
}

or

repositories {
  jcenter()
}
  1. Open your module's build.gradle file.
  2. Add the following manifest placeholder to your configuration (typically the defaultConfig):

    manifestPlaceholders = [HOCKEYAPP_APP_ID: "$APP_ID"]
    
  3. The param $APP_ID must be replaced by your HockeyApp App Identifier. The app identifier can be found on the app's page in the "Overview" section of the HockeyApp backend.

  4. Save your build.gradle file and make sure to trigger a Gradle build sync.

  5. Open your AndroidManifest.xml file and add a meta-data-tag for the HockeySDK.

    <application> 
    //your activity declarations and other stuff
    <meta-data android:name="net.hockeyapp.android.appIdentifier" android:value="${HOCKEYAPP_APP_ID}" />
    </application>
    
  6. Save your AndroidManifest.xml file.

Now that you've integrated the SDK with your project it's time to make use of its features.

Modify Code

Add crash reporting

This will add crash reporting capabilities to your app. Advanced ways to configure crash reporting are covered in advanced setup.

  1. Open your main activity.
  2. Add the following lines:
import net.hockeyapp.android.CrashManager;

public class YourActivity extends Activity {
  @Override
  public void onResume() {
    super.onResume();
    // ... your own onResume implementation
    checkForCrashes();
  }
    
  private void checkForCrashes() {
    CrashManager.register(this);
  }

}

When the activity is resumed, the crash manager is triggered and checks if a new crash was created before. If yes, it presents a dialog to ask the user whether they want to send the crash log to HockeyApp. On app launch the crash manager registers a new exception handler to recognize app crashes.

Add update distribution

This will add the in-app update mechanism to your app. For more configuration options of the update manager module see the section about advanced setup.

  1. Open the activity where you want to inform the user about eventual updates. We'll assume you want to do this on startup of your main activity.
  2. Add the following lines and make sure to always balance register(...) calls to SDK managers with unregister() calls in the corresponding lifecycle callbacks:
import net.hockeyapp.android.UpdateManager;

public class YourActivity extends Activity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Your own code to create the view
    // ...
    
    checkForUpdates();
  }

  private void checkForUpdates() {
    // Remove this for store builds!
    UpdateManager.register(this);
  }
  
  private void unregisterManagers() {
    UpdateManager.unregister();
  }

    
  @Override
  public void onPause() {
    super.onPause();
    unregisterManagers();
  }
  
  @Override
  public void onDestroy() {
    super.onDestroy();
    unregisterManagers();
  }

}

When the activity is created, the update manager checks for new updates in the background. If it finds a new update, an alert dialog is shown and if the user presses Show, they will be taken to the update activity. The reason to only do this once upon creation is that the update check causes network traffic and therefore potential costs for your users.

Add in-app feedback

This will add the ability for your users to provide feedback from right inside your app. Detailed configuration options are in advanced setup.

  1. You'll typically only want to show the feedback interface upon user interaction, for this example we assume you have a button feedback_button in your view for this.
  2. Add the following lines to your respective activity, handling the touch events and showing the feedback interface:
import net.hockeyapp.android.FeedbackManager;

public class YourActivity extends Activitiy {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Your own code to create the view
    // ...

    FeedbackManager.register(this);

    Button feedbackButton = (Button) findViewById(R.id.feedback_button);
    feedbackButton.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            FeedbackManager.showFeedbackActivity(MainActivity.this);
        }
    });
  }
  
}

When the user taps on the feedback button it will launch the feedback interface of the HockeySDK, where the user can create a new feedback discussion, add screenshots or other files for reference, and act on their previous feedback conversations.

Add User Metrics

HockeyApp automatically provides you with nice, intelligible, and informative metrics about how your app is used and by whom.

  • Sessions: A new session is tracked by the SDK whenever the containing app is restarted (this refers to a 'cold start', i.e. when the app has not already been in memory prior to being launched) or whenever it becomes active again after having been in the background for 20 seconds or more.
  • Users: The SDK anonymously tracks the users of your app by creating a random UUID that is then securely stored. The UUID is securely stored in the preferences of the client app.

To integrate User Metrics with your app, perform the following steps:

  1. Open your app's main activity and add the import statement and one line of code to the activity's onCreate-callback:
//add this import
#import net.hockeyapp.android.metrics.MetricsManager;

//add this to your main activity's onCreate()-callback
MetricsManager.register(this, getApplication());

Your app will now send metrics which you can use to count your active and overall usage numbers.

Add authentication

You can force authentication of your users through the LoginManager class. This will show a login screen to protect your app to users as users launch the app the first time.

Note This section shows the basic way to integrate HockeyApp's authentication feature. For a full overview, head over to the Knowledge Base on Authentication in Android.

  1. Retrieve your app secret from the HockeyApp backend. You can find this on the app details page in the backend right next to the "App ID" value. Click "Show" to access it.
  2. Open the activity you want to protect, if you want to protect all of your app this will be your main activity.
  3. Add the following lines to this activity:
import net.hockeyapp.android.LoginManager;

public class YourActivity extends Activity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Your own code to create the view
    // ...

    LoginManager.register(this, APP_SECRET, LoginManager.LOGIN_MODE_EMAIL_PASSWORD);
    LoginManager.verifyLogin(this, getIntent());
  }
}

Make sure to replace APP_SECRET with the value retrieved in step 1. This will launch the login activity every time a user launches your app.

Changes for Usage Time

If you want to track the usage time of your app or of some of its activities, you need to add the following calls to your activity:

    @Override
    protected void onResume() {
      super.onResume();
      Tracking.startUsage(this);
      // Further statements
      // ...
    }

    @Override
    protected void onPause() {
      // Further statements
      // ...
      Tracking.stopUsage(this);                 
      super.onPause();
    }

If your app targets API level 14 or higher as the minimum, you can also use the ActivityLifecycleCallbacks and register them in a custom Application instance with registerActivityLifecycleCallbacks.

Checklist if crashes do not appear in HockeyApp

  1. Check if the APP_ID matches the App ID in HockeyApp.

  2. Check if the package name in your AndroidManifest.xml matches the field "Package Name" of the app in HockeyApp. HockeyApp accepts crashes only if both the App ID and the package name equal their corresponding values in your app.

  3. If your app crashes and you start it again, is the dialog shown which asks the user to send the crash report? If not, please crash your app again, then connect the debugger and set a break point in CrashManager.java, method register to see why the dialog is not shown.

  4. If it still does not work, please contact us.

Additional options


###Mac desktop app

Our Mac app can provide easy uploading of your app versions to HockeyApp. Check out the installation tutorial.

API Documentation

The API documentation can be found in the docs folder or online here.

Documentation

Additional HockeyApp Android SDK documentation can be found at: