ericvt/HockeySDK-Android

The official Android SDK for the HockeyApp service

Version 3.7.0-beta.2

Introduction

HockeySDK-Android implements support for using HockeyApp in your Android application.

The following features are currently supported:

1. Collect crash reports: If your app crashes, a crash log is written to the device's storage. If the user starts the app again, they will be asked asked to submit the crash report to HockeyApp. This works for both beta and live apps, i.e. those submitted to Google Play or other app stores! Crash logs contain viable information for you to help resolve the issue. Furthermore you as a developer can add additional information to the report as well.

2. Update Alpha/Beta apps: The app will check with HockeyApp if a new version for your alpha/beta build is available. If yes, it will show a dialog to the user and let him see the release notes, the version history and start the installation process right away. You can even force the installation of certain updates.

3. Feedback: Besides crash reports, collecting feedback from your users from within your app is a great option to help with improving your app. You act and answer feedback directly from the HockeyApp backend.

4. Authenticate: To help you stay in control of closed tester groups you can identify and authenticate users against your registered testers with the HockeyApp backend. The authentication feature supports several ways of authentication.

This document contains the following sections:

1. Requirements
2. Setup
3. Obtain an App Identifier
4. Get the SDK
5. Integrate HockeySDK
6. Add Crash Reporting
7. Add Update Distribution
8. Add In-App Feedback
9. Add Authentication
10. Changelog
11. Advanced Setup
12. Manual Library Dependency
13. Crash Reporting
14. Update Distribution
15. In-App Feedback
16. Documentation
17. Troubleshooting
18. Contributing
19. Contributor License
20. Contact

1. Requirements

1. We assume that you already have an Android project in Android Studio or another Android IDE.
2. The SDK runs on devices with Android 2.3 or later, but you need to build your app with Android SDK 3.0 (Level 11) or later for the integration with HockeySDK.

2. Setup

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.

2.1 Obtain an App Identifier

Please see the "How to create a new app" tutorial. This will provide you with an HockeyApp-specific App Identifier to be used to initialize the SDK.

2.2 Get the SDK

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:3.7.0-beta.2'

also make sure your repository configuration contains

repositories {
  mavenCentral()
}

or

repositories {
  jcenter()
}

2.3 Integrate HockeySDK

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.

2.4 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.

2.5 Add Update Distribution

This will add the in-app update mechanism to your app. For more configuration options of the update manager module see 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 make sure to 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.

2.6 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.

2.7 Add Authentication

You can force authentication of your users through the LoginManager class. This will show a login screen to users if they are not fully authenticated to protect your app.

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.

3. Changelog

You can access the full changelog in our releases-section. The following paragraphs contain information what you might need to change when upgrading to the different new versions.

3.1 Upgrading from 3.6.x to 3.7.0

1. We didn't introduce any breaking changes, except that we have raised the minimum API level to 9.
2. Also consider switching to our new register-calls and adding your App ID to your configuration as described above.
3. If you integrate the SDK using Gradle, you can remove the previously required activities from your manifest file.

 <!-- HockeySDK Activities – no longer required as of 3.7.0! -->
 <activity android:name="net.hockeyapp.android.UpdateActivity" />
 <activity android:name="net.hockeyapp.android.FeedbackActivity" />
 <activity android:name="net.hockeyapp.android.PaintActivity" />

4. Advanced Setup

4.1 Manual Library Dependency

If you don't want to use Android Studio, Gradle, or Maven you can also download and add the library manually.

1. Download the latest release from here.
2. Unzip the file.
3. Copy the file libs/HockeySDK-$version.aar to the libs folder of your Android project. ($version is the version of the downloaded SDK)
4. Configure your development tools to use the aar-file in the libs folder.

Then proceed with the SDK integration.

4.2 Crash Reporting

The following options show only some of the many possibilities to interact and fine-tune the crash reporting feature. For more please check the full documentation of the classes net.hockeyapp.android.CrashManager and net.hockeyapp.android.CrashManagerListener in our documentation.

To configure a custom CrashManagerListener use the following register() method when configuring the manager:

  CrashManager.register(context, APP_ID, new MyCustomCrashManagerListener());

4.2.1 Autosend crash reports

Crashes are usually sent the next time the app starts. If your custom crash manager listener returns true for shouldAutoUploadCrashes(), crashes will be sent without any user interaction, otherwise a dialog will appear allowing the user to decide whether they want to send the report or not.

public class MyCustomCrashManagerListener extends CrashManagerListener {
  @Override
  public boolean shouldAutoUploadCrashes() {
    return true;
  }
}

4.2.2 Attach additional meta data

Starting with HockeyApp 3.6.0, you can add additional meta data (e.g. user-provided information) to a crash report. To achieve this call CrashManager.handleUserInput() and provide an instance of net.hockeyapp.android.objects.CrashMetaData.

4.3 Update Distribution

You can customize the behavior of the in-app update process in several ways. The main class to look at is net.hockeyapp.android.UpdateManagerListener in our documentation.

To configure a custom UpdateManagerListener use the following register() method when configuring the manager:

  UpdateManager.register(context, APP_ID, new MyCustomUpdateManagerListener());

4.3.1 Providing your own user interface for the update process

The UpdateManager will select a suitable activity or fragment depending on the availability of the feature. You can also supply your own by implementing the respective methods:

public class MyCustomUpdateManagerListener extends UpdateManagerListener {
  @Override
  public Class<? extends UpdateActivity> getUpdateActivityClass() {
    return MyCustomUpdateActivity.class;
  }

  @Override
  public Class<? extends UpdateFragment> getUpdateFragmentClass() {
    return MyCustomUpdateFragment.class;
  }
}

4.4 In-App Feedback

As stated in the setup guide you'll typically want to show the feedback interface from an onClick, onMenuItemSelected, or onOptionsItemSelected listener method.

4.4.1 Capturing a screenshot for feedback

You can configure a notification to show to the user. When they select the notification the SDK will create a screenshot from the app in its current state and create a new feedback draft from it.

1. Open the activity from which you want to enable the screenshot.
2. Add this to your onCreate() method or an onClick() listener:

  FeedbackManager.setActivityForScreenshot(YourActivity.this);

5. Documentation

Our documentation can be found on HockeyApp.

6.Troubleshooting

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

2. Check if the applicationId in your build.gradle file matches the Bundle Identifier of the app in HockeyApp. HockeyApp accepts crashes only if both the App ID and the bundle identifier match their corresponding values in your app. Please note that the package value in your AndroidManifest.xml file might differ from the bundle identifier.

3. If your app crashes and you start it again, does the dialog show up 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.

7. Contributing

We're looking forward to your contributions via pull requests.

Development environment

• Mac/Linux/Windows machine running the latest version of Android Studio and the Android SDK

8. Contributor License

You must sign a Contributor License Agreement before submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to submit a request via the form and then electronically sign the CLA when you receive the email containing the link to the document. You need to sign the CLA only once to cover submission to any Microsoft OSS project.

9. Contact

If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to open a GitHub issue here or contact us at support@hockeyapp.net